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 ve verzi .NET 8 tohoto článku.

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 ve verzi .NET 8 tohoto článku.

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

Upozorňující

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.

Upozorňující

Neumisťujte <script> značku do souboru komponenty (.razor), protože <script> značku nejde dynamicky aktualizovat.

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 elementu<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.

RazorBlazor 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á životním cyklem komponent 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 Ve webové aplikaci (.NET 8 nebo novější) komponenta vyžaduje interaktivní režim vykreslení použitý globálně pro aplikaci nebo pro 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 void 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 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 Ve webové aplikaci (.NET 8 nebo novější) komponenta vyžaduje interaktivní režim vykreslení použitý globálně pro aplikaci nebo pro 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)
        {
            await module.DisposeAsync();
        }
    }
}

{PATH}/JsCollocation2.razor.js:

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

Pro skripty nebo moduly poskytované knihovnou Razor tříd (RCL) se používá následující cesta:

_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.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 (src) do uzavíracího </body> elementuBlazor:<script>...</script>

<body>
    ...

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

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

  • K vytvoření správné cesty statického prostředku k souboru JS se vyžaduje segment cesty pro aktuální adresář (./).
  • 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 ASP.NET Spuštění CoreBlazor.

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.

Další informace najdete v tématu Volání funkcí JavaScriptu z metod .NET v ASP.NET Core Blazor.

Dynamický import s operátorem import() se podporuje s ASP.NET Core aBlazor:

if ({CONDITION}) import("/additionalModule.js");

V předchozím příkladu {CONDITION} zástupný symbol představuje podmíněnou kontrolu, která určuje, jestli se má modul načíst.

Informace o kompatibilitě prohlížeče najdete v tématu Je možné použít: moduly JavaScriptu: dynamický import.