Összetevők használata Razor JavaScript-alkalmazásokban és SPA-keretrendszerekben

Ez a cikk bemutatja, hogyan renderelheti Razor az összetevőket JavaScriptből, hogyan használhat Blazor egyéni elemeket, és hogyan hozhat létre Angular- és React-összetevőket.

Megjegyzés:

Javasoljuk, hogy az összetevők meglévő JavaScript-alkalmazásba való integrálásakor blazor.server.js használja a Blazor Server (blazor.webassembly.js) és Blazor WebAssembly (Razor) szkripteket, amíg a blazor.web.js (Blazor Web App) szkript további támogatást nem kap a jövőben. További információ: RegisterCustomElement működése leállt a 8-as verzióban Blazor (dotnet/aspnetcore #53920).

Angular-mintaalkalmazások

• CustomElementsBlazorSample () (Blazor Serverjaviercn/CustomElementsBlazorSampleág: blazor-server): Blazor Server a .NET 8/9-ben támogatott. A .NET 7 minta migrálásával kapcsolatban lásd a migrálást ASP.NET Core-ról a .NET 7-ben a .NET 8-ra és a migrálást ASP.NET Core-ból a .NET 8-ban ASP.NET Core-ba a .NET 9-ben.
• CustomElementsBlazorSample (Blazor WebAssembly) (javiercn/CustomElementsBlazorSample, ág: blazor-wasm): A .NET 7 minta migrálásához tekintse meg: Migrálás a .NET 7 ASP.NET Core-ból a .NET 8-ba és Migrálás a .NET 8 ASP.NET Core-ból a .NET 9 ASP.NET Core-ba.

Összetevők renderelése Razor JavaScriptből

Razor az összetevők dinamikusan renderelhetők a JavaScriptből (JS) a meglévő JS alkalmazásokhoz.

Az ebben a szakaszban szereplő példa a következő Razor összetevőt jeleníti meg egy lapon keresztül JS.

Quote.razor:

<div class="m-5 p-5">
    <h2>Quote</h2>
    <p>@Text</p>
</div>

@code {
    [Parameter]
    public string? Text { get; set; }
}

Adja hozzá a Program fájlban az összetevő helyének névterét.

Hívja meg az alkalmazás RegisterForJavaScript gyökérösszetevő-gyűjteményét, hogy egy Razor összetevőt regisztráljon gyökérösszetevőként a JS rendereléshez.

RegisterForJavaScript olyan túlterhelést tartalmaz, amely elfogadja az inicializálási logikát JS (javaScriptInitializer) végrehajtó függvény nevét. A JS függvényt az alkalmazás elindítása után és az összetevők renderelése előtt, közvetlenül az Blazor összetevőregisztrációnként egyszer hívjuk meg. Ez a függvény olyan technológiákkal JS való integrációhoz használható, mint például a HTML egyedi elemei vagy egy JS alapú SPA keretrendszer.

Egy vagy több inicializáló függvényt különböző összetevőregisztrációk hozhatnak létre és hívhatnak meg. A tipikus használati eset ugyanaz az inicializáló függvény újrafelhasználása több összetevőhöz, ami akkor várható, ha az inicializáló függvény az egyéni elemekkel vagy egy másik JS-alapú SPA-keretrendszerrel való integrációt konfigurálja.

Fontos

Ne keverje össze a javaScriptInitializer paraméterét a RegisterForJavaScriptJavaScript inicializálókkal. A paraméter és az JS inicializáló funkció neve véletlen.

Az alábbi példa az előző Quote összetevő dinamikus regisztrációját mutatja be azonosítóként a "quote" értékkel.

• Egy Blazor Server alkalmazásban módosítsa a AddServerSideBlazor fájlban a Program hívást.

  builder.Services.AddServerSideBlazor(options =>
  {
      options.RootComponents.RegisterForJavaScript<Quote>(identifier: "quote", 
          javaScriptInitializer: "initializeComponent");
  });
  

• Blazor WebAssembly Egy alkalmazásban az ügyféloldali RegisterForJavaScriptRootComponents fájlban hívja fel a következőtProgram:

  builder.RootComponents.RegisterForJavaScript<Quote>(identifier: "quote", 
      javaScriptInitializer: "initializeComponent");
  

Csatolja az inicializáló függvényt name és parameters a függvényparamétereket az window objektumhoz. Bemutató céljából az alábbi initializeComponent függvény naplózza a regisztrált összetevő nevét és paramétereit.

wwwroot/jsComponentInitializers.js:

window.initializeComponent = (name, parameters) => {
  console.log({ name: name, parameters: parameters });
}

Renderelje az összetevőt a JS elemből egy tárolóelembe a regisztrált azonosító használatával, és szükség szerint adja át az összetevő paramétereit.

Az alábbi példában:

• Az Quote összetevő (quote azonosító) a quoteContainer függvény meghívásakor jelenik meg az showQuote elemben.
• A rendszer egy idézőjel-sztringet ad át az összetevő paraméterének Text .

wwwroot/scripts.js:

window.showQuote = async () => {
  let targetElement = document.getElementById('quoteContainer');
  await Blazor.rootComponents.add(targetElement, 'quote', 
  {
    text: "Crow: I have my doubts that this movie is actually 'starring' " +
      "anybody. More like, 'camera is generally pointed at.'"
  });
}

const btn = document.querySelector("#showQuoteBtn");
btn.addEventListener("click", showQuote);

Blazor A szkript betöltése után töltse be az előző szkripteket az JS alkalmazásba:

<script src="_framework/{BLAZOR SCRIPT}"></script>
<script src="jsComponentInitializers.js"></script>
<script src="scripts.js"></script>

Az előző példában a {BLAZOR SCRIPT} helyőrző a Blazor szkript.

HTML-ben helyezze el a céltároló elemet (quoteContainer). Az ebben a szakaszban ismertetett bemutatóhoz egy gomb aktiválja az összetevő megjelenítését a QuoteshowQuoteJS függvény meghívásával:

<button id="showQuoteBtn">Show Quote</button>

<div id="quoteContainer"></div>

Az összetevők megjelenítése előtti inicializáláskor a böngésző fejlesztői eszközeinek konzolja naplózza az Quote összetevő azonosítóját (name) és paramétereit (parameters) a meghíváskor initializeComponent :

Object { name: "quote", parameters: (1) […] }
  name: "quote"
  parameters: Array [ {…} ]
    0: Object { name: "Text", type: "string" }
    length: 1

Show Quote gomb kiválasztásakor az Quote komponens megjelenik a Text-ben tárolt idézet megjelenítésével.

Idézet ©1988-1999 Satellite of Love LLC: Mystery Science Theater 3000 (Trace Beaulieu (Crow))

Megjegyzés:

rootComponents.add az összetevő egy példányát adja vissza. Hívja fel dispose a példány felszabadításához:

const rootComponent = await window.Blazor.rootComponents.add(...);

...

rootComponent.dispose();

Az előző példa dinamikusan jeleníti meg a gyökérösszetevőt a showQuote()JS függvény meghívásakor. Ha az indításkor Blazor egy gyökérösszetevőt egy tárolóelembe szeretne renderelni, használjon JavaScript-inicializálót az összetevő rendereléséhez, ahogy az alábbi példa is mutatja.

Az alábbi példa az előző példára épül, az Quote összetevő használatával, a Program fájlban lévő gyökérösszetevő regisztrációval és a jsComponentInitializers.js inicializálásával. A showQuote() függvény (és a script.js fájl) nem használatos.

A HTML-ben helyezze a céltároló elemet a quoteContainer2 következő példához:

<div id="quoteContainer2"></div>

JavaScript-inicializáló használatával adja hozzá a gyökérösszetevőt a céltároló elemhez.

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js:

export function afterStarted(blazor) {
  let targetElement = document.getElementById('quoteContainer2');
  blazor.rootComponents.add(targetElement, 'quote',
    {
      text: "Crow: I have my doubts that this movie is actually 'starring' " +
          "anybody. More like, 'camera is generally pointed at.'"
    });
}

Megjegyzés:

A rootComponents.addhívásához használja a blazor indítási esemény által biztosított b paramétert (kisbetűs Blazor). Bár a regisztráció érvényes a Blazor objektum (nagybetűs B) használatakor, a paraméter használata javasolt.

További funkciókkal rendelkező speciális példáért tekintse meg a BasicTestApp ASP.NET Core referenciaforrás (dotnet/aspnetcore GitHub-adattár) példáját:

• JavaScriptRootComponents.razor
• wwwroot/js/jsRootComponentInitializers.js
• wwwroot/index.html

Megjegyzés:

A .NET referenciaforrásra mutató dokumentációs hivatkozások általában betöltik az adattár alapértelmezett ágát, amely a .NET következő kiadásának aktuális fejlesztését jelöli. Egy adott kiadás címkéjének kiválasztásához használja az Ágak vagy címkék közötti váltás legördülő listát. További információ: A ASP.NET Core-forráskód (dotnet/AspNetCore.Docs #26205) verziócímkéjének kiválasztása.

Blazor egyéni elemek

Egyéni elemek használatával Blazor dinamikusan renderelhet Razor összetevőket különböző JavaScript-technológiákból, például az Angularból, a Reactből és a Vue-ból.

Blazor egyéni elemek:

• Egyéni HTML-elemek implementálásához használjon szabványos HTML-felületeket.
• Ne kelljen manuálisan kezelnie a gyökérösszetevők Razor állapotát és életciklusát JavaScript API-k használatával.
• Hasznos lehet az összetevők más technológiákban írt meglévő projektekbe való fokozatos bevezetéséhez Razor .

Az egyéni elemek nem támogatják a gyermek tartalmat vagy a sablonalapú összetevőket.

Az elem neve

A HTML-specifikáció szerint az egyéni elemcímkének kebab-esetet kell alkalmaznia:

❌ Érvénytelen:mycounter
❌ Érvénytelen:MY-COUNTER
❌ Érvénytelen:MyCounter
✔️Érvényes:my-counter
✔️Érvényes:my-cool-counter

Csomag

Adjon hozzá egy csomaghivatkozást Microsoft.AspNetCore.Components.CustomElements az alkalmazás projektfájljába.

Megjegyzés:

A csomagok .NET-alkalmazásokhoz való hozzáadásáról a Csomagok telepítése és kezelésea csomaghasználati munkafolyamatban (NuGet-dokumentáció) című cikkben talál útmutatást. Ellenőrizze a megfelelő csomagverziókat a NuGet.org.

Példaösszetevő

Az alábbi példák a Counter komponensre épülnek, amely a Blazor projektsablon része.

Counter.razor:

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

Blazor Server regisztráció

Az alábbi lépésekkel regisztrálhat egy gyökérösszetevőt egyéni elemként egy Blazor Server alkalmazásban.

Adja hozzá a Microsoft.AspNetCore.Components.Web névteret a fájl elejéhez Program :

using Microsoft.AspNetCore.Components.Web;

Adjon hozzá egy névteret az alkalmazás összetevőihez. Az alábbi példában az alkalmazás névtere BlazorSample, és az összetevők a Pages mappában találhatók.

using BlazorSample.Pages;

Módosítsa a hívást a következőre AddServerSideBlazor: . Adja meg az egyéni elemet a RegisterCustomElement áramkör opció RootComponents szerint. Az alábbi példa az összetevőt az Counter egyéni HTML-elemhez my-counterregisztrálja:

builder.Services.AddServerSideBlazor(options =>
{
    options.RootComponents.RegisterCustomElement<Counter>("my-counter");
});

Blazor WebAssembly regisztráció

Az alábbi lépésekkel regisztrálhat egy gyökérösszetevőt egyéni elemként egy Blazor WebAssembly alkalmazásban.

Adja hozzá a Microsoft.AspNetCore.Components.Web névteret a fájl elejéhez Program :

using Microsoft.AspNetCore.Components.Web;

Adjon hozzá egy névteret az alkalmazás összetevőihez. Az alábbi példában az alkalmazás névtere BlazorSample, és az összetevők a Pages mappában találhatók.

using BlazorSample.Pages;

RegisterCustomElement hívása RootComponents. Az alábbi példa az összetevőt az Counter egyéni HTML-elemhez my-counterregisztrálja:

builder.RootComponents.RegisterCustomElement<Counter>("my-counter");

A regisztrált egyéni elem használata

Az egyéni elemet bármilyen webes keretrendszerrel használhatja. Az alkalmazás összetevőjét my-counter megjelenítő előző Counter egyéni HTML-elemet például egy React-alkalmazásban használják a következő korrektúrával:

<my-counter></my-counter>

Az egyéni elemek Blazor létrehozásának teljes példájáért tekintse meg a referenciaforrásban található CustomElementsComponent összetevőt.

Megjegyzés:

A .NET referenciaforrásra mutató dokumentációs hivatkozások általában betöltik az adattár alapértelmezett ágát, amely a .NET következő kiadásának aktuális fejlesztését jelöli. Egy adott kiadás címkéjének kiválasztásához használja az Ágak vagy címkék közötti váltás legördülő listát. További információ: A ASP.NET Core-forráskód (dotnet/AspNetCore.Docs #26205) verziócímkéjének kiválasztása.

Paraméterek átadása

Adja át a paramétereket az Razor összetevőnek HTML-attribútumként vagy JavaScript-tulajdonságként a DOM-elemen.

Az alábbi Counter összetevő egy IncrementAmount paramétert használ a Click me gomb növekedésének mértékének beállításához.

Counter.razor:

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    [Parameter]
    public int IncrementAmount { get; set; } = 1;

    private void IncrementCount()
    {
        currentCount += IncrementAmount;
    }
}

Renderelje az összetevőt Counter az egyéni elemmel, és adjon át egy értéket a IncrementAmount paraméternek HTML-attribútumként. Az attribútum neve kebab-case szintaxist alkalmaz (increment-amount, nem IncrementAmount):

<my-counter increment-amount="10"></my-counter>

Másik lehetőségként beállíthatja a paraméter értékét JavaScript-tulajdonságként az elemobjektumon. A tulajdonságnév a camelCase szintaxist alkalmazza (incrementAmount, nem IncrementAmount):

const elem = document.querySelector("my-counter");
elem.incrementAmount = 10;

A paraméterértékeket bármikor frissítheti attribútum- vagy tulajdonságszintaxis használatával.

Támogatott paramétertípusok:

• A JavaScript tulajdonságszintaxisával bármilyen JSON-szerializálható típusú objektumot átadhat.
• HTML-attribútumok használatával sztring-, logikai vagy numerikus típusú objektumok átadására korlátozódik.

Angular- és React-összetevők létrehozása

JavaScript-összetevők létrehozásaJS JavaScript-technológiák összetevőiből Razor , például az Angular vagy a React használatával. A .NET nem tartalmazza ezt a képességet, de lehetővé teszi ezáltal az összetevők Razor renderelésének JS támogatását. A JS GitHubon található összetevő-létrehozási minta bemutatja, hogyan hozhat létre Angular- és React-összetevőket összetevőkből Razor . További információt a GitHub mintaalkalmazás fájljában README.md talál.

Figyelmeztetés

Az Angular és a React összetevő funkciói jelenleg kísérleti jellegűek, nem támogatottak, és bármikor módosíthatók vagy eltávolíthatók. Örömmel vesszük visszajelzését arról, hogy ez az adott megközelítés mennyire felel meg a követelményeknek.