Sdílet prostřednictvím

Umístění JavaScriptu v aplikacích ASP.NET Core Blazor

  • Článek

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete v tomto článku ve verzi .NET 9.

K načtení kódu JavaScriptu (JS) můžete použít libovolný z následujících přístupů:

Umístění značek <script>

Značku umístěte <script> do souboru komponenty (.razor) pouze v případě, že je zaručeno přijetí statického vykreslování na straně serveru (statické SSR), protože <script> značku nelze dynamicky aktualizovat. Umístění značky <script> do souboru komponenty nevygeneruje upozornění nebo chybu v době kompilace, ale chování při načítání skriptu nemusí odpovídat vašim očekáváním v komponentách, které při vykreslení komponenty nepřijímají statické SSR.

Neumisťujte <script> značku do souboru komponenty (.razor), protože <script> značku nejde dynamicky aktualizovat. Umístění značky <script> do souboru komponenty způsobí chybu v době kompilace.

Poznámka:

Příklady v dokumentaci obvykle umisťují skripty do značky <script> nebo načítají globální skripty z externích souborů. Tyto přístupy znečišťují klienta globálními funkcemi. Pro produkční aplikace doporučujeme umístit JS do samostatných JS modulů , které se dají v případě potřeby importovat. Další informace najdete v části Izolace JavaScriptu v modulech JavaScriptu.

Poznámka:

Příklady v dokumentaci umisťují skripty do značky <script> nebo načítají globální skripty z externích souborů. Tyto přístupy znečišťují klienta globálními funkcemi. Umístění JS do samostatných JS modulů, které je možné importovat v případě potřeby, není podporováno dříve Blazor než ASP.NET Core 5.0. Pokud aplikace vyžaduje použití modulů JS pro izolaci JS, doporučujeme k sestavení aplikace použít ASP.NET Core 5.0 nebo novější. Pokud potřebujete další informace, v rozevíracím seznamu verzí vyberte pro tento článek verzi 5.0 nebo novější a projděte si část věnovanou izolaci JavaScriptu v modulech JavaScriptu.

Načtení skriptu ve značce <head>

Přístup popsaný v této části se obecně nedoporučuje.

Značky JavaScriptu () umístěteJS<script>...</script> do značky<head>:

<head>
    ...

    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</head>

Načítání JS ze značky <head> není nejlepším řešením z následujících důvodů:

  • Zprostředkovatel komunikace JS může selhat, pokud skript závisí na architektuře Blazor. Doporučujeme načíst skripty pomocí jednoho z dalších přístupů, nikoli prostřednictvím značky <head>.
  • Interaktivita stránky se může zpomalit kvůli času potřebnému k parsování JS ve skriptu.

Načtení skriptu ve značce <body>

Za odkaz na skript umístěte značky JavaScriptu (<script>...</script>) do uzavíracího </body> elementuBlazor

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

V předchozím příkladu {BLAZOR SCRIPT} je Blazor zástupný symbol cesta ke skriptu a název souboru. Umístění skriptu najdete v tématu ASP.NET Blazor Základní struktura projektu.

Načtení skriptu z externího souboru JavaScriptu (.js) umístěného stejně jako komponenta

Umístění souborů JavaScriptu (JS) pro Razor komponenty je pohodlný způsob, jak uspořádat skripty v aplikaci.

Razor Blazor komponenty aplikací kompletují JS soubory pomocí .razor.js rozšíření a jsou veřejně adresovatelné pomocí cesty k souboru v projektu:

{PATH}/{COMPONENT}.razor.js

  • Zástupný {PATH} symbol je cesta ke komponentě.
  • Zástupný {COMPONENT} symbol je komponenta.

Když je aplikace publikovaná, architektura automaticky přesune skript do webového kořenového adresáře. Skripty se přesunou do umístění, kde bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.jsjsou zástupné symboly:

  • {TARGET FRAMEWORK MONIKER}je moniker cílové architektury (TFM).
  • {PATH} je cesta ke komponentě.
  • {COMPONENT} je název komponenty.

Relativní adresa URL skriptu se nevyžaduje žádná změna, protože Blazor se postará o umístění JS souboru do publikovaných statických prostředků za vás.

Tato část a následující příklady se primárně zaměřují na vysvětlení JS kolkace souborů. První příklad ukazuje kompletovaný JS soubor s běžnou JS funkcí. Druhý příklad ukazuje použití modulu k načtení funkce, což je doporučený přístup pro většinu produkčních aplikací. Volání JS z .NET je plně pokryto voláním javascriptových funkcí z metod .NET v ASP.NET Core Blazor, kde existují další vysvětlení BlazorJS rozhraní API s dalšími příklady. Vyřazení komponent, které se nachází v druhém příkladu, se zabývá Razor komponent ASP.NET Core.

Následující JsCollocation1 komponenta načte skript prostřednictvím HeadContent komponenty a volá JS funkci s IJSRuntime.InvokeAsync. Zástupný {PATH} symbol je cesta ke komponentě.

Důležité

Pokud pro ukázku v testovací aplikaci použijete následující kód, změňte {PATH} zástupný symbol na cestu komponenty (například Components/Pages v .NET 8 nebo novějším nebo Pages v .NET 7 nebo starším). Blazor Web App V prostředí (.NET 8 nebo novější) komponenta vyžaduje interaktivní režim vykreslení použitý globálně pro aplikaci nebo definici komponenty.

Za Blazor skript přidejte následující skript (umístění spouštěcího Blazor skriptu):

<script src="{PATH}/JsCollocation1.razor.js"></script>

JsCollocation1 součást ({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 Task ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

Kompletovaný JS soubor se umístí vedle JsCollocation1 souboru komponenty s názvem JsCollocation1.razor.jssouboru . V komponentě JsCollocation1 se na skript odkazuje na cestu kompletovaného souboru. V následujícím příkladu showPrompt1 funkce přijme jméno uživatele z a Window prompt() vrátí ho JsCollocation1 do komponenty pro zobrazení.

{PATH}/JsCollocation1.razor.js:

function showPrompt1(message) {
  return prompt(message, 'Type your name here');
}

Předchozí přístup se nedoporučuje pro obecné použití v produkčních aplikacích, protože přístup znečišťuje klienta globálními funkcemi. Lepším přístupem pro produkční aplikace je použití JS modulů. Stejné obecné principy platí pro načtení JS modulu z kompletovaného JS souboru, jak ukazuje další příklad.

Metoda následující JsCollocation2 komponenty OnAfterRenderAsync načte JS modul module, který je součástí IJSObjectReference třídy komponent. module slouží k volání showPrompt2 funkce. Zástupný {PATH} symbol je cesta ke komponentě.

Důležité

Pokud pro ukázku v testovací aplikaci použijete následující kód, změňte {PATH} zástupný symbol na cestu komponenty. Blazor Web App V prostředí (.NET 8 nebo novější) komponenta vyžaduje interaktivní režim vykreslení použitý globálně pro aplikaci nebo definici komponenty.

JsCollocation2 součást ({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)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

V předchozím příkladu JSDisconnectedException je při vyřazení modulu zachycen v případě Blazorztráty okruhu SignalR . Pokud se předchozí kód použije v Blazor WebAssembly aplikaci, nedojde ke ztrátě připojeníSignalR, takže můžete odebrat blok a nechat řádek, který modul odstranítry-catch().await module.DisposeAsync(); Další informace najdete v tématu ASP.NET Interoperabilita Core Blazor JavaScriptu (JSinteroperabilita).

{PATH}/JsCollocation2.razor.js:

export function showPrompt2(message) {
  return prompt(message, 'Type your name here');
}

Použití skriptů a modulů pro kolaci JS v Razor knihovně tříd (RCL) je podporováno pouze pro BlazorJS mechanismus spolupráce založené na IJSRuntime rozhraní. Pokud implementujete [JSImport] JavaScriptu/[JSExport], prohlédni si javascriptový interop JSImport/JSExport s ASP.NET Core .Blazor

Pro skripty nebo moduly poskytované knihovnou tříd (RCL) využívající Razorinteroperabilitu IJSRuntime založenou na protokolu JS RCL se používá následující cesta:

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js

  • K vytvoření správné cesty statického prostředku k souboru ./ se vyžaduje segment cesty pro aktuální adresář (JS).
  • Zástupný symbol {PACKAGE ID} je identifikátor balíčku RCL (nebo název knihovny tříd, na kterou aplikace odkazuje).
  • Zástupný {PATH} symbol je cesta ke komponentě. Pokud je komponenta Razor umístěná v kořenovém adresáři knihovny RCL, segment cesty není zahrnutý.
  • Zástupný {COMPONENT} symbol je název komponenty.
  • Zástupný {EXTENSION} symbol odpovídá rozšíření komponenty, buď razor nebo cshtml.

V následujícím příkladu aplikace Blazor:

  • Identifikátor balíčku RCL je AppJS.
  • Skripty modulu se načítají pro komponentu JsCollocation3 (JsCollocation3.razor).
  • Komponenta JsCollocation3 je ve složce Components/Pages RCL.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

Další informace o knihovnách RCL najdete v tématu Využívání komponent ASP.NET Core Razor z knihovny tříd Razor (RCL).

Načtení skriptu z externího souboru JavaScriptu (.js)

Za odkaz na skript umístěte značky JavaScriptu (JS) s cestou ke zdroji skriptu (<script>...</script>) do </body>:Blazor

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

Zástupné symboly v předchozím příkladu:

  • Zástupný {BLAZOR SCRIPT} symbol je Blazor cesta ke skriptu a název souboru. Umístění skriptu najdete v tématu ASP.NET Blazor Základní struktura projektu.
  • Zástupný symbol {SCRIPT PATH AND FILE NAME (.js)} je cesta a název souboru skriptu v části wwwroot.

V následujícím příkladu předchozí značky <script> je soubor scripts.js umístěný ve složce wwwroot/js aplikace:

<script src="js/scripts.js"></script>

Skripty můžete také obsluhovat přímo ze wwwroot složky, pokud nechcete zachovat všechny skripty v samostatné složce v části wwwroot:

<script src="scripts.js"></script>

Pokud externí soubor JS poskytuje knihovna tříd Razor, zadejte soubor JS file pomocí cesty statického webového prostředku: _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

  • Zástupný symbol {PACKAGE ID} je ID balíčku knihovny. Pokud v souboru projektu není zadaný parametr <PackageId>, jako ID balíčku se ve výchozím nastavení použije název sestavení projektu.
  • Zástupný symbol {SCRIPT PATH AND FILE NAME (.js)} je cesta a název souboru v části wwwroot.
<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

V následujícím příkladu předchozí značky <script>:

  • Knihovna tříd Razor má název sestavení ComponentLibrary a v souboru projektu knihovny není zadaný parametr <PackageId>.
  • Soubor scripts.js je ve složce wwwroot knihovny tříd.
<script src="_content/ComponentLibrary/scripts.js"></script>

Další informace najdete v tématu Využívání komponent ASP.NET Core Razor z knihovny tříd Razor (RCL).

Vložení skriptu před nebo po Blazor spuštění

Pokud chcete zajistit, aby se skripty načetly před nebo po Blazor spuštění, použijte inicializátor JavaScriptu. Další informace a příklady najdete v tématu Blazor Core.

Vložení skriptu po spuštění architektury Blazor

Pokud chcete po spuštění vložit skript Blazor , zřetězte Promise ho z ručního Blazorspuštění . Další informace a příklad najdete v tématu ASP.NET Spuštění jádraBlazor.

Izolace JavaScriptu v modulech JavaScriptu

Blazorumožňuje izolaci JavaScriptu (JS) ve standardníchJSmodulech (specifikace ECMAScript).

Izolace JS poskytuje následující výhody:

  • Import JS už znečišťuje globální obor názvů.
  • Uživatelé knihovny a komponent už nemusí importovat související JS.

Ve scénářích na straně serveru vždy vyvolá výjimku JSDisconnectedException v případě ztráty BlazorSignalR okruhu brání JS volání zprostředkovatele komunikace v dispozicích modulu, což vede k neošetřené výjimce. Blazor WebAssemblyaplikace během spolupráce nepoužívají SignalR připojeníJS, takže v JSDisconnectedException aplikacích není potřeba soutisknoutBlazor WebAssembly, aby byly k dispozici moduly.

Další informace naleznete v následujících zdrojích: