Olvasás angol nyelven

Megosztás a következőn keresztül:

JavaScript-hely ASP.NET Core Blazor-alkalmazásokban

  • Cikk

Megjegyzés

Ez nem a cikk legújabb verziója. Az aktuális kiadáshoz tekintse meg a jelen cikk .NET 9-es verzióját .

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információ: .NET és .NET Core támogatási szabályzat. Az aktuális kiadáshoz tekintse meg a jelen cikk .NET 9-es verzióját .

Fontos

Ezek az információk egy olyan előzetes termékre vonatkoznak, amelyet a kereskedelmi forgalomba kerülés előtt jelentősen módosíthatnak. A Microsoft nem vállal kifejezett vagy hallgatólagos szavatosságot az itt megadott információkra vonatkozóan.

Az aktuális kiadáshoz tekintse meg a jelen cikk .NET 9-es verzióját .

Töltse be a JavaScript (JS) kódot az alábbi módszerek bármelyikével:

Beágyazott JavaScript nem ajánlott Blazor alkalmazásokhoz. Javasoljuk, hogy JS elrendezést kombináljon a JS modulokkal.

<script> címkék helye

Csak akkor helyezzen <script> címkét egy összetevőfájlba (.razor), ha az összetevő garantáltan statikus kiszolgálóoldali renderelést (statikus SSR) alkalmaz továbbfejlesztett navigáció nélkül. Ha <script> címkét helyez el egy összetevőfájlban, az nem okoz fordítási időt jelző figyelmeztetést vagy hibát, de előfordulhat, hogy a szkriptbetöltési viselkedés nem felel meg az interaktív renderelési módot vagy statikus SSR-t továbbfejlesztett navigációval használó összetevőkre vonatkozó elvárásainak.

Ne helyezzen <script> címkét egy összetevőfájlba (.razor), mert a <script> címke nem frissíthető dinamikusan. Ha egy <script> címkét helyez el egy összetevőfájlban, fordítási időben jelentkező hibát okoz.

Megjegyzés

A dokumentációs példák általában egy <script> címkébe helyezik a szkripteket, vagy külső fájlokból töltik be a globális szkripteket. Ezek a megközelítések globális függvényekkel szennyezi az ügyfelet. Éles alkalmazások esetén javasoljuk, hogy külön JS modulokba helyezze el a JS-t, amelyeket szükség esetén importálhat. További információ: JavaScript-elkülönítés a JavaScript-modulokban szakaszban.

Megjegyzés

A dokumentációs példák szkripteket helyeznek egy <script> címkébe, vagy betöltik a globális szkripteket külső fájlokból. Ezek a megközelítések globális függvényekkel szennyezi az ügyfelet. A JS különálló JS modulokba, amelyek szükség esetén importálhatók, nem támogatottak Blazor ASP.NET Core 5.0-nál korábbi verzióiban. Ha az alkalmazás JS modulok használatát igényli JS elkülönítéshez, javasoljuk, hogy ASP.NET Core 5.0-s vagy újabb verzióját használja az alkalmazás létrehozásához. További információkért használja a Verzió legördülő listát a cikk 5.0-s vagy újabb verziójának kiválasztásához, és tekintse meg a JavaScript-modulok szakaszban található JavaScript-elkülönítést.

Szkript betöltése <head> jelölőnyelvben

Az ebben a szakaszban ismertetett megközelítés általában nem ajánlott.

Helyezze a JavaScript (JS) címkéket (<script>...</script>) a <head> elem jelölésébe ():

<head>
    ...

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

A JS<head>-ból való betöltése nem a legjobb módszer az alábbi okokból:

  • JS interop meghiúsulhat, ha a szkript attól függ, hogy Blazorelérhető-e. Azt javasoljuk, hogy a szkripteket a többi módszer egyikével töltse be, ne a <head> korrektúra használatával.
  • A lap lassabban válhat interaktívvá a szkript JS elemzéséhez szükséges idő miatt.

Az összetevőjelölés esetében a szkriptek egy HeadContent összetevőn keresztül tölthetők be, a szokásos figyelmeztetéssel, hogy a módszer lelassítja a kliens oldal betöltését, ezért javasoljuk annak elkerülését. Ha egy szkript HeadContent összetevővel töltődik be egy Blazor Server alkalmazásban, Blazor WebAssembly alkalmazásban vagy olyan Blazor Web App-ban, amely interaktív renderelési módot (interaktív SSR, CSR) vagy továbbfejlesztett navigációval rendelkező statikus SSR-t használ, az összetevő oldalának elhagyásakor a <script> címke eltávolításra kerül a renderelt <head> tartalomból, de a szkript JavaScript-kódja nem töltődik ki, beleértve az eseménykezelőket, amelyeket a szkript regisztrál, a nyilvánosságra hozott változókat és a szkript által biztosított metódusokat. Csak a Blazor Web App-k, amelyek statikus SSR-t használnak továbbfejlesztett navigáció nélkül, oldják fel a JavaScript-kódot, amikor a felhasználó elnavigál az oldalról. Általában jobb, ha <script> címkéket ad hozzá a fizikai <head> tartalomhoz, kivéve, ha kifejezetten meg szeretné tartani az ilyen szkripthivatkozásokat az őket használó összetevőkben, és nem bánja, hogy a kód nem kerül eltávolításra a navigációs események során.

Az összetevő jelölőnyelv esetében a szkriptek egy HeadContent összetevőn keresztül tölthetők be, a szokásos figyelmeztetéssel, hogy a módszer lassítja az oldal betöltését a kliensnél, ezért javasoljuk, hogy kerülje el. Ha egy szkript HeadContent összetevővel van betöltve, az összetevő oldaláról lépve eltávolítja a <script> címkét a renderelt <head> tartalomból, de nem távolítja el a szkript JavaScript-kódját, beleértve a szkript által regisztrált eseménykezelőket, a közzétett változókat és a szkript által biztosított metódusokat. Általában jobb, ha <script> címkéket ad hozzá a fizikai <head> tartalomhoz, kivéve, ha kifejezetten meg szeretné tartani az ilyen szkripthivatkozásokat az őket használó összetevőkben, és nem bánja, hogy a kód nem kerül eltávolításra a navigációs események során.

Szkript betöltése <body> jelölőnyelvben

Helyezze a JavaScript-címkéket (<script>...</script>) a záró </body> elembe a Blazor szkripthivatkozás után:

<body>
    ...

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

Az előző példában a {BLAZOR SCRIPT} helyőrző a Blazor szkript elérési útja és fájlneve. A szkript helyéről lásd: ASP.NET Core Blazor projektstruktúra.

Szkript betöltése egy külső JavaScript fájlból (.js), egy komponenshez társítva

A JavaScript-fájlok (JS) összetevők (Razor) számára történő együtt elhelyezése kényelmes módszer a szkriptek alkalmazásbeli rendszerezésére.

Razor Blazor-alkalmazások összetevői a JS kiterjesztést használva helyezik el a .razor.js fájlokat, amelyek nyilvánosan elérhetők a projekt fájljának útvonalán keresztül.

{PATH}/{COMPONENT}.razor.js

  • A {PATH} helyőrző az összetevő elérési útja.
  • A {COMPONENT} helyőrző az összetevő.

Az alkalmazás közzétételekor a keretrendszer automatikusan áthelyezi a szkriptet a webgyökérbe. A szkriptek átkerülnek a bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js-ba, ahol a következő helyőrzők találhatók:

Nincs szükség a szkript relatív URL-címének módosítására, mivel a Blazor automatikusan gondoskodik róla, hogy a JS fájl bekerüljön a közzétett statikus eszközök közé.

Ez a szakasz és a következő példák elsősorban a JS fájlelhelyezés magyarázatára összpontosítanak. Az első példa bemutat egy együtt működő JS fájlt egy szokásos JS függvénnyel. A második példa egy modul függvény betöltésére való használatát mutatja be, amely a legtöbb éles alkalmazás esetében ajánlott módszer. A .NET-ből való hívása a .NET metódusok JavaScript függvények ASP.NET Core-ban való meghívásával foglalkozó teljes mértékben le van fedve, ahol további magyarázatok és példák találhatók a API-ra. A második példában jelen lévő komponens ártalmatlanítása az ASP.NET Core Razor komponens ártalmatlanításvan tárgyalva.

Az alábbi JsCollocation1 összetevő betölt egy szkriptet egy HeadContent összetevőn keresztül, és meghív egy JS függvényt IJSRuntime.InvokeAsync. A {PATH} helyőrző az összetevő elérési útja.

Fontos

Ha a következő kódot használja egy tesztalkalmazás bemutatójára, módosítsa a {PATH} helyőrzőt az összetevő elérési útjára (például: .NET 8-ban vagy újabb verzióban Components/Pages vagy a .NET 7-ben vagy korábbi verziókban Pages). Egy Blazor Web App (.NET 8 vagy újabb verzió) az összetevőhöz az alkalmazásra vagy az összetevő definícióra globálisan alkalmazott interaktív renderelési mód szükséges.

Adja hozzá a következő szkriptet a Blazor szkript után (a Blazor indítási szkript helyét):

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

JsCollocation1 összetevő ({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();
    }
}

Az csoportosított JS fájl a JsCollocation1 összetevőfájl mellett található, és a fájl neve JsCollocation1.razor.js. Az JsCollocation1 összetevőben a szkript az csoportosított fájl elérési útjára hivatkozik. Az alábbi példában a showPrompt1 függvény elfogadja a felhasználó nevét egy Window prompt(), és visszaadja a JsCollocation1 összetevőnek megjelenítésre.

{PATH}/JsCollocation1.razor.js:

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

Az előző megközelítés nem ajánlott az éles alkalmazásokban való általános használathoz, mert a megközelítés globális függvényekkel szennyezi az ügyfelet. Az termelési alkalmazások jobb megközelítése a JS modulok használata. Ugyanezek az általános alapelvek vonatkoznak egy JS modul egy csoportosított JS fájlból való betöltésére, ahogyan azt a következő példa is mutatja.

Az alábbi JsCollocation2 összetevő OnAfterRenderAsync metódusa betölt egy JS modult a module-ba, amely az összetevő osztályának IJSObjectReference-je. module a showPrompt2 függvény meghívására szolgál. A {PATH} helyőrző az összetevő elérési útja.

Fontos

Ha a következő kódot használja egy tesztalkalmazásban történő bemutatóhoz, módosítsa a {PATH} helyőrzőt az összetevő elérési útjára. Egy Blazor Web App (.NET 8 vagy újabb verzió) az összetevőhöz az alkalmazásra vagy az összetevő definícióra globálisan alkalmazott interaktív renderelési mód szükséges.

JsCollocation2 összetevő ({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)
            {
            }
        }
    }
}

Az előző példában JSDisconnectedException problémát okoz a modul eltávolítása során, ha BlazorSignalR áramköre elveszik. Ha az előző kódot egy Blazor WebAssembly alkalmazásban használják, nincs SignalR kapcsolat, amit elveszíthetne, így eltávolíthatja a try-catch blokkot, és meghagyhatja a sort, amely megsemmisíti a modult (await module.DisposeAsync();). További információ: ASP.NET Core Blazor JavaScript-együttműködés (JS interop).

{PATH}/JsCollocation2.razor.js:

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

Fontos

Ne helyezzen <script>JsCollocation2.razor.js címkét a Blazor szkript után, mert a modul automatikusan betöltődik és gyorsítótárazódik a dinamikus import() meghívásakor.

A szkriptek és modulok használata a JS osztálykönyvtárban (RCL) lévő csoportosított Razor esetén csak BlazorJS interfészességen alapuló IJSRuntime interop mechanizmushoz támogatott. Ha a JavaScript [JSImport]/[JSExport] interop funkciót implementálja, tekintse meg a JavaScript JSImport/JSExport interop és ASP.NET Core lehetőségeit Blazor.

Az Razor osztálykódtár (RCL) által IJSRuntime-alapú JS interop használatával biztosított szkriptek vagy modulok esetében a következő elérési utat használja a rendszer:

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

  • Az aktuális könyvtár elérési útja (./) szükséges a megfelelő statikus objektum elérési útjának létrehozásához a JS fájlhoz.
  • A {PACKAGE ID} helyőrző az RCL csomagazonosítója (vagy az alkalmazás által hivatkozott osztálytár könyvtárneve).
  • A {PATH} helyőrző az összetevő elérési útja. Ha egy Razor összetevő az RCL gyökerénél található, az elérésiút-szegmens nem lesz benne.
  • A {COMPONENT} helyőrző az összetevő neve.
  • A {EXTENSION} helyőrző megegyezik a komponens kiterjesztésével: razor vagy cshtml.

Az alábbi Blazor alkalmazás példája:

  • Az RCL csomagazonosítója AppJS.
  • A modul szkriptjei be vannak töltve a JsCollocation3 összetevő (JsCollocation3.razor) számára.
  • A JsCollocation3 összetevő az RCL Components/Pages mappájában található.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

További információ az RCL-ekről: ASP.NET Core Razor-összetevők felhasználása Razor osztálytárból (RCL).

Szkript betöltése külső JavaScript-fájlból (.js)

Helyezze a JavaScript (JS) címkéket (<script>...</script>), ahol a szkriptforrás (src) elérési útja van, a záró </body> elem belsejébe, a Blazor szkripthivatkozás után.

<body>
    ...

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

Az előző példában szereplő helyőrzők esetében:

  • A {BLAZOR SCRIPT} helyőrző a Blazor szkript elérési útját és fájlnevét jelöli. A szkript helyéről lásd: ASP.NET Core Blazor projektstruktúra.
  • A {SCRIPT PATH AND FILE NAME (.js)} helyőrző az elérési út és a szkriptfájl neve a wwwrootalatt.

Az előző <script> címke alábbi példájában a scripts.js fájl az alkalmazás wwwroot/js mappájában található:

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

A szkripteket közvetlenül a wwwroot mappából is kiszolgálhatja, ha nem szeretné, hogy az összes szkript külön mappában maradjon a wwwrootalatt:

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

Ha a külső JS fájlt egy Razor osztálykönyvtár adja meg, adja meg a JS fájlt a statikus, stabil webes erőforrás elérési útjával: _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}.

  • A {PACKAGE ID} helyőrző a könyvtár csomagazonosítója. Ha a projektfájlban nincs megadva a <PackageId>, akkor a csomagazonosító alapértelmezés szerint a projekt összeállítás neve lesz.
  • A {SCRIPT PATH AND FILE NAME (.js)} helyőrző a wwwroot alatti elérési út és fájlnév.
<body>
    ...

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

Az előző <script> címke alábbi példájában:

  • A Razor osztálykönyvtár összeállítás neve ComponentLibrary, és a könyvtár projektfájljában nincs megadva <PackageId>.
  • A scripts.js fájl az osztálytár wwwroot mappájában található.
<script src="_content/ComponentLibrary/scripts.js"></script>

További információért lásd: ASP.NET Core Razor összetevőinek felhasználása Razor osztálykönyvtárból (RCL).

Szkript beszúrása Blazor indítása előtt vagy után

Ha gondoskodni szeretne arról, hogy a szkriptek betöltődjenek Blazor indítása előtt vagy után, használjon JavaScript-inicializálót. További információkért és példákért lásd: ASP.NET Core Blazor indítás.

Szkript beillesztése Blazor elindítása után

Ha a Blazor indítása után szeretne szkriptet injektálni, akkor kapcsolódjon ahhoz a Promise-hez, amely a Blazormanuális indításából ered. További információért és példáért lásd: ASP.NET Core Blazor indítás.

JavaScript-elkülönítés JavaScript-modulokban

Blazor engedélyezi a JavaScript (JS) elkülönítését standard JS modulokban (ECMAScript specifikáció).

JS elkülönítés a következő előnyöket biztosítja:

  • Az importált JS már nem szennyezi a globális névteret.
  • A könyvtárak és összetevők felhasználóinak nem szükséges importálni a kapcsolódó JS-t.

Kiszolgálóoldali forgatókönyvekben mindig fogd el a JSDisconnectedException-t arra az esetre, ha a BlazorSignalR áramkörének meghibásodása megakadályozza, hogy egy JS interop hívás lezárja a modult, ami kezeletlen kivételt eredményez. Blazor WebAssembly alkalmazások nem használnak SignalR kapcsolatot JS interop során, így nincs szükség JSDisconnectedException megfogására a Blazor WebAssembly alkalmazásokban a modulok felszabadításához.

További információ: