Dela via

JavaScript-plats i ASP.NET Core Blazor-appar

  • Artikel

Anmärkning

Det här är inte den senaste versionen av den här artikeln. För den aktuella versionen, se .NET 9-versionen av den här artikeln.

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i .NET och .NET Core Support Policy. För den aktuella versionen, se .NET 9-versionen av den här artikeln.

Viktig

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

För den aktuella versionen, se .NET 9-versionen av den här artikeln.

Läs in JavaScript-kod (JS) med någon av följande metoder:

Infogad JavaScript rekommenderas inte för Blazor appar. Vi rekommenderar att du använder JS sammansättning kombinerat med JS moduler.

Plats för <script> taggar

Placera bara en <script>-tagg i en komponentfil (.razor) om komponenten garanterat använder statisk återgivning på serversidan (statisk SSR) eftersom taggen <script> inte kan uppdateras dynamiskt. Att placera en <script> tagg i en komponentfil ger ingen kompileringstidsvarning eller ett fel, men skriptinläsningsbeteendet kanske inte matchar dina förväntningar i komponenter som inte använder statisk SSR när komponenten återges.

Placera inte en <script>-tagg i en komponentfil (.razor) eftersom taggen <script> inte kan uppdateras dynamiskt. Om du placerar en <script> tagg i en komponentfil uppstår ett kompileringsfel.

Anmärkning

Dokumentationsexempel placerar vanligtvis skript i en <script> tagg eller läser in globala skript från externa filer. Dessa metoder förorenar klienten med globala funktioner. För produktionsappar rekommenderar vi att du placerar JS i separata JS moduler som kan importeras när det behövs. Mer information finns i avsnittet JavaScript-isolering i JavaScript-moduler.

Anmärkning

Dokumentationsexempel placerar skript i en <script> tagg eller läser in globala skript från externa filer. Dessa metoder förorenar klienten med globala funktioner. Att placera JS i separata JS moduler som kan importeras vid behov inte stöds i Blazor tidigare än ASP.NET Core 5.0. Om appen kräver användning av JS moduler för JS isolering rekommenderar vi att du använder ASP.NET Core 5.0 eller senare för att skapa appen. För mer information, använd listrutan Version för att välja en version 5.0 eller senare av den här artikeln och se avsnittet JavaScript-isolering i JavaScript-moduler.

Ladda ett skript i <head>-markup

Metoden i det här avsnittet rekommenderas vanligtvis inte.

Placera JavaScript-taggarna (JS) (<script>...</script>) i <head> elementmarkeringen:

<head>
    ...

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

Att läsa in JS från <head> är inte den bästa metoden av följande skäl:

  • JS interop kan misslyckas om skriptet är beroende av Blazor. Vi rekommenderar att du läser in skript med någon av de andra metoderna, inte via <head>-markering.
  • Sidan kan bli interaktiv långsammare på grund av den tid det tar att parsa JS i skriptet.

Ladda ett skript i <body>-markup

Placera JavaScript-taggarna (<script>...</script>) i det avslutande </body>-elementet efter Blazor-skriptreferensen:

<body>
    ...

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

I föregående exempel är platshållaren {BLAZOR SCRIPT}Blazor skriptsökväg och filnamn. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

Läsa in ett skript från en extern JavaScript-fil (.js) som är kopplad till en komponent

Att gruppera JavaScript-filer (JS) för komponenter i Razor är ett bekvämt sätt att organisera skript i en app.

Razor komponenter i Blazor appar placerar JS filer med hjälp av .razor.js-tillägget och kan adresseras offentligt med hjälp av sökvägen till filen i projektet:

{PATH}/{COMPONENT}.razor.js

  • Platshållaren {PATH} är sökvägen till komponenten.
  • Platshållaren {COMPONENT} är en komponent.

När appen publiceras flyttar ramverket automatiskt skriptet till webbroten. Skripten flyttas till bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js, där platshållarna är:

Ingen ändring krävs för skriptets relativa URL eftersom Blazor tar hand om att placera JS-filen i publicerade statiska tillgångar åt dig.

Det här avsnittet och följande exempel fokuserar främst på att förklara JS filplacering. Det första exemplet visar en samlad JS fil med en vanlig JS funktion. Det andra exemplet visar användningen av en modul för att läsa in en funktion, vilket är den rekommenderade metoden för de flesta produktionsappar. Anrop av JS från .NET är helt inkluderat i Anropa JavaScript-funktioner från .NET-metoder i ASP.NET Core Blazor, där du hittar fler förklaringar av BlazorJS API med extra exempel. Komponenthantering, som finns i det andra exemplet, beskrivs i ASP.NET Core Razor komponentlivscykel.

Följande JsCollocation1 komponent läser in ett skript via en HeadContent komponent och anropar en JS-funktion med IJSRuntime.InvokeAsync. Platshållaren {PATH} är sökvägen till komponenten.

Viktig

Om du använder följande kod för en demonstration i en testapp ändrar du platshållaren {PATH} till komponentens sökväg (till exempel Components/Pages i .NET 8 eller senare eller Pages i .NET 7 eller tidigare). I en Blazor Web App (.NET 8 eller senare) kräver komponenten ett interaktivt återgivningsläge som tillämpas antingen globalt på appen eller på komponentdefinitionen.

Lägg till följande skript efter Blazor skriptet (plats för Blazor startskriptet):

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

JsCollocation1 komponent ({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();
    }
}

Den sammankopplade JS-filen placeras bredvid komponentfilen JsCollocation1 med filnamnet JsCollocation1.razor.js. I komponenten JsCollocation1 refereras skriptet på sökvägen till den samplacerade filen. I följande exempel accepterar funktionen showPrompt1 användarens namn från en Window prompt() och returnerar det till JsCollocation1 komponenten för visning.

{PATH}/JsCollocation1.razor.js:

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

Föregående metod rekommenderas inte för allmän användning i produktionsappar eftersom metoden förorenar klienten med globala funktioner. En bättre metod för produktionsappar är att använda JS moduler. Samma allmänna principer gäller för inläsning av en JS modul från en sammanställd JS fil, vilket visas i nästa exempel.

Följande JsCollocation2 komponentens OnAfterRenderAsync-metod läser in en JS-modul i module, som är en IJSObjectReference av komponentklassen. module används för att anropa funktionen showPrompt2. Platshållaren {PATH} är sökvägen till komponenten.

Viktig

Om du använder följande kod för en demonstration i en testapp ändrar du platshållaren {PATH} till komponentens sökväg. I en Blazor Web App (.NET 8 eller senare) kräver komponenten ett interaktivt återgivningsläge som tillämpas antingen globalt på appen eller på komponentdefinitionen.

JsCollocation2 komponent ({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)
            {
            }
        }
    }
}

I det föregående exemplet fångas JSDisconnectedException vid borttagningen av modulen om Blazor:s SignalR-krets går förlorad. Om föregående kod används i en Blazor WebAssembly app finns det ingen SignalR anslutning att förlora, så du kan ta bort try-catch blocket och lämna kvar raden som tar bort modulen (await module.DisposeAsync();). Mer information finns i ASP.NET Core Blazor JavaScript-samverkan (JS interop).

{PATH}/JsCollocation2.razor.js:

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

Viktig

Placera inte en <script> tagg för JsCollocation2.razor.js efter Blazor skriptet eftersom modulen läses in och cachelagras automatiskt när den dynamiska import() anropas.

Användning av skript och moduler för kolokaliserade JS i ett Razor-klassbibliotek (RCL) stöds endast av Blazor:s JS-interop-mekanism baserat på IJSRuntime-gränssnittet. Om du implementerar JavaScript [JSImport]/[JSExport] interop, se JavaScript JSImport/JSExport interop med ASP.NET Core Blazor.

För skript eller moduler som tillhandahålls av ett Razor-klassbibliotek (RCL) med IJSRuntime-baserad JS interop används följande sökväg:

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

  • Sökvägssegmentet för den aktuella katalogen (./) krävs för att skapa rätt statisk tillgångssökväg till JS-filen.
  • Platshållaren {PACKAGE ID} är RCL:s paketidentifierare (eller biblioteksnamn för ett klassbibliotek som refereras av appen).
  • Platshållaren {PATH} är sökvägen till komponenten. Om en Razor komponent finns i roten för RCL inkluderas inte sökvägssegmentet.
  • Platshållaren {COMPONENT} är komponentnamnet.
  • Platshållaren {EXTENSION} matchar tillägget för komponenten, antingen razor eller cshtml.

I följande Blazor app-exempel:

  • RCL:s paketidentifierare är AppJS.
  • Skript för en modul läses in för komponenten JsCollocation3 (JsCollocation3.razor).
  • Komponenten JsCollocation3 finns i mappen Components/Pages för RCL.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

För mer information om RCL:er, se Använd ASP.NET Core Razor-komponenter från ett Razor-klassbibliotek (RCL).

Läsa in ett skript från en extern JavaScript-fil (.js)

Placera JavaScript-taggarna (JS) (<script>...</script>) med en skriptkälla (src) i stänga </body>-elementet efter Blazor-skriptreferensen:

<body>
    ...

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

För platshållarna i föregående exempel:

  • Platshållaren {BLAZOR SCRIPT} är Blazor skriptsökväg och filnamn. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.
  • Platshållaren {SCRIPT PATH AND FILE NAME (.js)} är sökvägen och skriptfilens namn under wwwroot.

I följande exempel på taggen ovan <script> finns filen scripts.js i mappen wwwroot/js i appen:

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

Du kan också hantera skript direkt från mappen wwwroot om du föredrar att inte behålla alla skript i en separat mapp under wwwroot:

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

När den externa JS-filen tillhandahålls av ett Razor klassbibliotekanger du JS-filen med dess stabila statiska webbtillgångssökväg: _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

  • Platshållaren {PACKAGE ID} är bibliotekets paket-ID. Paket-ID:t är som standard projektets sammansättningsnamn om <PackageId> inte anges i projektfilen.
  • Platshållaren {SCRIPT PATH AND FILE NAME (.js)} är sökvägen och filnamnet under wwwroot.
<body>
    ...

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

I följande exempel på föregående <script> tagg:

  • Razor-klassbiblioteket har sammansättningsnamnet ComponentLibraryoch en <PackageId> anges inte i bibliotekets projektfil.
  • Filen scripts.js finns i klassbibliotekets wwwroot mapp.
<script src="_content/ComponentLibrary/scripts.js"></script>

Mer information finns i Consume ASP.NET Core Razor components from a Razor class library (RCL).

Mata in ett skript före eller efter Blazor startar

Använd en JavaScript-initiator för att säkerställa att skript läses in före eller efter Blazor startar. Mer information och exempel finns i ASP.NET Core Blazor start.

Mata in ett skript när Blazor startar

Om du vill mata in ett skript när Blazor startar kedjar du till Promise som är resultatet av en manuell start av Blazor. Mer information och ett exempel finns i ASP.NET Core Blazor start.

JavaScript-isolering i JavaScript-moduler

Blazor möjliggör JavaScript (JS) isolering i standardmoduler JS (ECMAScript-specifikationen).

JS isolering ger följande fördelar:

  • Importerade JS förorenar inte längre det globala namnområdet.
  • Användare av ett bibliotek och komponenter behöver inte importera den relaterade JS.

I scenarier på serversidan bör du alltid fånga JSDisconnectedException ifall förlust av Blazor:s SignalR-krets hindrar ett JS interop-anrop från att frigöra en modul, vilket leder till ett ohanterat undantag. Blazor WebAssembly appar använder inte en SignalR-anslutning under JS interop, så det finns ingen anledning att trapa JSDisconnectedException i Blazor WebAssembly appar för bortskaffande av moduler.

Mer information finns i följande resurser: