Sdílet prostřednictvím

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

Poznámka:

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

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.

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

Vložený JavaScript se nedoporučuje pro Blazor aplikace. Doporučujeme používat JS uskupení v kombinaci s moduly JS.

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

Značku <script> umístěte do souboru komponenty (.razor) pouze v případě, že je zaručeno použití statického vykreslování na straně serveru (SSR) bez rozšířené navigace. 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řijímají interaktivní režim vykreslování nebo statické SSR s vylepšenou navigaci.

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ýchJS modulů, které je možné importovat v případě potřeby, není podporováno v Blazor dřívějších verzích než .NET 5. Pokud aplikace vyžaduje použití modulů JS pro izolaci JS, doporučujeme k sestavení aplikace použít .NET 5 nebo novější. Další informace najdete v rozevíracím seznamu Verze, kde můžete vybrat verzi .NET 5 nebo novější tohoto článku, a podívejte se na část Izolace 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.

V kódu komponenty lze skripty načíst s využitím komponenty HeadContent s obvyklou poznámkou, že tento přístup zpomaluje načítání stránky u klienta, čemu se doporučujeme vyhnout. Když se skript načte s komponentou HeadContent v aplikaci Blazor Server, Blazor WebAssembly aplikaci nebo Blazor Web App pomocí interaktivního režimu vykreslování (interaktivní SSR, CSR) nebo statického SSR s vylepšenou navigací, přechod mimo stránku komponenty odebere značku <script> z vykresleného <head> obsahu, ale neodstraní JavaScriptový kód skriptu, včetně obslužných rutin událostí, které skript zaregistruje, vystavených proměnných a metod, které skript poskytuje. Pouze Blazor Web App, které používají statický SSR bez rozšířené navigace, uvolní JavaScriptový kód, když uživatel přejde mimo stránku. Obecně je lepší přidávat <script> značky do fyzického <head> obsahu, pokud výslovně nechcete zachovat takové odkazy na skripty v komponentách, které je používají, a nevadí vám, že kód není uvolňován při navigačních událostech.

V kódu komponenty lze skripty načíst s využitím komponenty HeadContent s obvyklou poznámkou, že tento přístup zpomaluje načítání stránky u klienta, čemu se doporučujeme vyhnout. Když je skript načten s komponentou HeadContent, přechod mimo stránku komponenty odebere značku <script> z vykresleného <head> obsahu, ale neodstraní JavaScriptový kód skriptu, včetně obslužných rutin událostí, které registruje skript, zpřístupněné proměnné a metody, které skript poskytuje. Obecně je lepší přidávat <script> značky do fyzického <head> obsahu, pokud výslovně nechcete zachovat takové odkazy na skripty v komponentách, které je používají, a nevadí vám, že kód není uvolňován při navigačních událostech.

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. Likvidace komponent, která je uvedena ve druhém příkladu, je popsána v likvidaci komponenty v ASP.NET CoreRazor.

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 Task 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');
}

Důležité

Nezadávejte značku pro za skriptu , protože modul se načte a automaticky ukládá do mezipaměti při vyvolání dynamického .

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 src</body>:

<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:

  • Last updated on