ASP.NET Core Blazor 應用程式中的 JavaScript 位置
注意
這不是這篇文章的最新版本。 如需目前版本,請參閱本文的 .NET 8 版本。
警告
不再支援此版本的 ASP.NET Core。 如需詳細資訊,請參閱 .NET 和 .NET Core 支援原則。 如需目前版本,請參閱本文的 .NET 8 版本。
使用下列任何方法載入 JavaScript (JS) 程式碼:
- 在
<head>
標記 中載入指令碼 (通常不建議使用) - 在
<body>
標記中載入指令碼 - 從外部 JavaScript 檔案載入指令碼 (
.js
) - 在 Blazor 啟動後插入指令碼
警告
只有在元件保證採用靜態伺服器端轉譯 (靜態 SSR) 時,才會將 <script>
標籤放在元件檔案 (.razor
) 中,因為 <script>
標籤無法動態更新。
警告
請勿將 <script>
標籤放在元件檔案 (.razor
) 中,因為 <script>
標籤無法動態更新。
注意
文件範例通常會將指令碼放在 <script>
標籤中,或從外部檔案載入全域指令碼。 這些方法會利用全域函式來使用戶端產生問題。 針對生產應用程式,建議您將 JS 放在個別的 JS模組中,以視需要匯入。 如需詳細資訊,請參閱 JavaScript 模組中的 JavaScript 隔離一節。
注意
文件範例會將指令碼放在 <script>
標籤內,或從外部檔案載入全域指令碼。 這些方法會利用全域函式來使用戶端產生問題。 在 ASP.NET Core 5.0 以前的 Blazor不支援將 JS 放在個別的 JS模組 中,以視需要匯入。 如果應用程式需要使用 JS 模組進行 JS 隔離,建議您使用 ASP.NET Core 5.0 或更新版本來建置應用程式。 如需詳細資訊,請使用 [版本] 下拉式清單選取本文的 5.0 或更新版本,並參閱 JavaScript 模組中的 JavaScript 隔離一節。
在 <head>
標記中載入指令碼
通常不建議使用本節中的方法。
將 JavaScript (JS) 標籤 (<script>...</script>
) 放在 <head>
元素標記中:
<head>
...
<script>
window.jsMethod = (methodParameter) => {
...
};
</script>
</head>
從 <head>
載入 JS 並不是最佳方法,原因如下:
- 如果指令碼相依於 Blazor,則 JS Interop 可能會失敗。 建議您使用其中一種其他方法來載入指令碼,而不是透過
<head>
標記載入指令碼。 - 頁面可能會因為剖析指令碼中的 JS 所需的時間而互動變慢。
在 <body>
標記中載入指令碼
將 JavaScript 標籤 (<script>...</script>
) 放在 關閉</body>
元素 內的 Blazor 指令碼參考之後:
<body>
...
<script src="{BLAZOR SCRIPT}"></script>
<script>
window.jsMethod = (methodParameter) => {
...
};
</script>
</body>
在上述範例中,{BLAZOR SCRIPT}
預留位置是 Blazor 指令碼路徑和檔案名稱。 如需指令碼的位置,請參閱 ASP.NET Core Blazor 專案結構。
從外部 JavaScript 檔案載入指令碼 (.js
) 與元件共置
將 JavaScript (JS) 檔案集合起來用於 Razor 元件,是組織應用程式中指令碼的便利方式。
Blazor 應用程式的 Razor 元件會使用 .razor.js
副檔名來共置 JS 檔案,並使用專案中檔案的路徑來公開尋址:
{PATH}/{COMPONENT}.razor.js
{PATH}
預留位置是元件路徑。{COMPONENT}
預留位置是元件。
發佈應用程式時,架構會自動將指令碼移至 Web 根目錄。 指令碼會移至 bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js
,其中預留位置為:
{TARGET FRAMEWORK MONIKER}
是目標 Framework Moniker (TFM)。{PATH}
是元件路徑。{COMPONENT}
是元件名稱。
指令碼的相對 URL 不需要變更,因為 Blazor 會為您將 JS 檔案放在已發佈的靜態資產中。
本節和下列範例主要著重於說明 JS 檔案集合。 第一個範例示範具有一般 JS 函式的共置 JS 檔案。 第二個範例示範如何使用模組來載入函式,這是大部分生產應用程序的建議方法。 從 .NET 呼叫 JS 完全涵蓋於在 ASP.NET Core Blazor 中從 .NET 方法呼叫 JavaScript 函式,其中還以其他範例進一步說明 BlazorJS API。 第二個範例中的元件處置則涵蓋於 ASP.NET Core Razor 元件生命週期中。
下列 JsCollocation1
元件會透過 HeadContent
元件 載入指令碼,並使用 IJSRuntime.InvokeAsync 呼叫 JS 函式。 {PATH}
預留位置是元件路徑。
重要
如果您在測試應用程式中使用下列程式碼進行示範,請將 {PATH}
預留位置變更為元件的路徑 (例如:.NET 8 或更新版本中的 Components/Pages
或 .NET 7 或更早版本中的 Pages
)。 在 Blazor Web 應用程式 (.NET 8 或更新版本) 中,元件需要全域套用至應用程式或元件定義的互動式轉譯模式。
在 Blazor 指令碼後面新增下列指令碼 (Blazor 啟動指令碼的位置):
<script src="{PATH}/JsCollocation1.razor.js"></script>
JsCollocation1
元件 ({PATH}/JsCollocation1.razor
):
@page "/js-collocation-1"
@inject IJSRuntime JS
<PageTitle>JS Collocation 1</PageTitle>
<h1>JS Collocation Example 1</h1>
<button @onclick="ShowPrompt">Call showPrompt1</button>
@if (!string.IsNullOrEmpty(result))
{
<p>
Hello @result!
</p>
}
@code {
private string? result;
public async void ShowPrompt()
{
result = await JS.InvokeAsync<string>(
"showPrompt1", "What's your name?");
StateHasChanged();
}
}
共置的 JS 檔案會放在 JsCollocation1
元件檔案旁邊,其檔名為 JsCollocation1.razor.js
。 在 JsCollocation1
元件中,指令碼會於共置檔案的路徑參考。 在下列範例中,showPrompt1
函式會接受來自 Window prompt()
的使用者名稱,並將它傳回給 JsCollocation1
元件以供顯示。
{PATH}/JsCollocation1.razor.js
:
function showPrompt1(message) {
return prompt(message, 'Type your name here');
}
一般不建議在生產應用程式中使用上述方法,因為它會利用全域函式來干擾用戶端。 較適合生產應用程式的方法是使用 JS 模組。 相同的一般準則適用於從共置 JS 檔案載入 JS 模組,如下一個範例所示。
下列 JsCollocation2
元件的 OnAfterRenderAsync
方法會將 JS 模組載入 module
中,這是元件類別的 IJSObjectReference。 module
用於呼叫 showPrompt2
函式。 {PATH}
預留位置是元件路徑。
重要
如果您在測試應用程式中使用下列程式碼進行示範,請將 {PATH}
預留位置變更為元件的路徑。 在 Blazor Web 應用程式 (.NET 8 或更新版本) 中,元件需要全域套用至應用程式或元件定義的互動式轉譯模式。
JsCollocation2
元件 ({PATH}/JsCollocation2.razor
):
@page "/js-collocation-2"
@implements IAsyncDisposable
@inject IJSRuntime JS
<PageTitle>JS Collocation 2</PageTitle>
<h1>JS Collocation Example 2</h1>
<button @onclick="ShowPrompt">Call showPrompt2</button>
@if (!string.IsNullOrEmpty(result))
{
<p>
Hello @result!
</p>
}
@code {
private IJSObjectReference? module;
private string? result;
protected async override Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
/*
Change the {PATH} placeholder in the next line to the path of
the collocated JS file in the app. Examples:
./Components/Pages/JsCollocation2.razor.js (.NET 8 or later)
./Pages/JsCollocation2.razor.js (.NET 7 or earlier)
*/
module = await JS.InvokeAsync<IJSObjectReference>("import",
"./{PATH}/JsCollocation2.razor.js");
}
}
public async void ShowPrompt()
{
if (module is not null)
{
result = await module.InvokeAsync<string>(
"showPrompt2", "What's your name?");
StateHasChanged();
}
}
async ValueTask IAsyncDisposable.DisposeAsync()
{
if (module is not null)
{
await module.DisposeAsync();
}
}
}
{PATH}/JsCollocation2.razor.js
:
export function showPrompt2(message) {
return prompt(message, 'Type your name here');
}
僅在 Blazor 的 JS Interop 機制以 IJSRuntime 介面為基礎時,才支援對 Razor 類別庫 (RCL) 中共置的 JS 使用指令碼和模組。 如果您要實作 JavaScript [JSImport]
/[JSExport]
interop,請參閱 JavaScript JSImport/JSExport interop 搭配 ASP.NET Core Blazor。
對於 Razor 類別庫 (RCL) 使用以 IJSRuntime 為基礎的 JS Interop 時提供的指令碼或模組,則會使用下列路徑:
_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js
{PACKAGE ID}
預留位置是 RCL 的封裝識別碼 (或應用程式所參考類別庫的程式庫名稱)。{PATH}
預留位置是元件路徑。 如果 Razor 元件位於 RCL 的根目錄,則不包含路徑區段。{COMPONENT}
預留位置是元件名稱。{EXTENSION}
預留位置符合元件的副檔名 (可以是razor
或cshtml
)。
在以下 Blazor 應用程式範例中:
- RCL 的封裝識別碼為
AppJS
。 - 模組的指令碼會針對
JsCollocation3
元件載入 (JsCollocation3.razor
)。 JsCollocation3
元件位於 RCL 的Components/Pages
資料夾中。
module = await JS.InvokeAsync<IJSObjectReference>("import",
"./_content/AppJS/Components/Pages/JsCollocation3.razor.js");
如需關於 RCL 的詳細資訊,請參閱從 Razor 類別庫 (RCL) 取用 ASP.NET Core Razor。
從外部 JavaScript 檔案 (.js
) 載入指令碼
將具有指令碼來源 (src
) 路徑的 JavaScript (JS) 標籤 (<script>...</script>
) 放在結尾 </body>
元素內的 Blazor 指令碼參考之後:
<body>
...
<script src="{BLAZOR SCRIPT}"></script>
<script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>
在前述範例中:
{BLAZOR SCRIPT}
預留位置是 Blazor 指令碼路徑和檔案名稱。 如需指令碼的位置,請參閱 ASP.NET Core Blazor 專案結構。{SCRIPT PATH AND FILE NAME (.js)}
預留位置是wwwroot
下的路徑和指令檔名稱。
在上述 <script>
標籤的下列範例中,scripts.js
檔案位於應用程式的 wwwroot/js
資料夾中:
<script src="js/scripts.js"></script>
如果您不想將所有指令碼保留在 wwwroot
底下的個別資料夾中,也可以直接從 wwwroot
資料夾提供指令碼:
<script src="scripts.js"></script>
當 Razor 類別庫提供外部 JS 檔案時,請使用其穩定的靜態 Web 資產路徑來指定 JS 檔案:./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}
:
- 需要目前目錄 (
./
) 的路徑區段,才能建立 JS 檔案的正確靜態資產路徑。 {PACKAGE ID}
預留位置是程式庫的封裝識別碼。 如果未在專案檔中指定<PackageId>
,則封裝識別碼預設為專案的組件名稱。{SCRIPT PATH AND FILE NAME (.js)}
預留位置是wwwroot
下的路徑和檔案名稱。
<body>
...
<script src="{BLAZOR SCRIPT}"></script>
<script src="./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>
在上述 <script>
標籤的下列範例中:
- Razor 類別庫的組件名稱為
ComponentLibrary
,而且未在程式庫的專案檔中指定<PackageId>
。 scripts.js
檔案位於類別庫的wwwroot
資料夾中。
<script src="./_content/ComponentLibrary/scripts.js"></script>
如需詳細資訊,請參閱從 Razor 類別庫 (RCL) 取用 ASP.NET Core Razor。
在 Blazor 啟動前或啟動後插入指令碼
若要確保指令碼在啟動前或啟動後 Blazor 載入,請使用 JavaScript 初始設定式。 如需詳細資訊和範例,請參閱 ASP.NET Core Blazor 啟動。
在 Blazor 啟動後插入指令碼
若要在 Blazor 啟動後插入指令碼,請鏈結至手動啟動 Blazor 所產生的 Promise
。 如需詳細資訊和範例,請參閱 ASP.NET Core Blazor 啟動。
JavaScript 模組中的 JavaScript 隔離
Blazor 在標準 JS模組 ( ECMAScript 規範) 中啟用 JavaScript (JS) 隔離。
JS 隔離提供下列優點:
- 已匯入的 JS 不再會產生全域命名空間問題。
- 不需要程式庫和元件的取用者即可匯入相關 JS。
如需詳細資訊,請參閱從 ASP.NET Core Blazor 中的 .NET 方法呼叫 JavaScript 函式。
ASP.NET Core 和 Blazor 支援使用 import()
運算子的動態匯入:
if ({CONDITION}) import("/additionalModule.js");
在上述範例中,{CONDITION}
預留位置代表用來判斷是否應該載入模組的條件式檢查。
關於瀏覽器相容性,請參閱我是否可以使用:JavaScript 模組:動態匯入。