Použití Razor komponent v javascriptových aplikacích a architekturách SPA

Tento článek popisuje, jak vykreslit Razor komponenty z JavaScriptu, používat Blazor vlastní prvky a generovat komponenty Angular a React.

Poznámka:

Při integraci komponent do existující javascriptové aplikace doporučujeme používat blazor.server.js skripty (Blazor Server) a blazor.webassembly.js (Blazor WebAssembly) až do dalšího přidání lepší podpory blazor.web.js skriptu (Blazor Web App).Razor Další informace naleznete v tématu RegisterCustomElement přestal fungovat v Blazor 8 (dotnet/aspnetcore #53920).

Ukázkové aplikace Angular

• CustomElementsBlazorSample (Blazor Server) (javiercn/CustomElementsBlazorSample, branch: blazor-server): Blazor Server je podporován v .NET 8. Pokud chcete migrovat tuto ukázku .NET 7 na .NET 8, přečtěte si téma Migrace z ASP.NET Core 7.0 na 8.0.
• CustomElementsBlazorSample () (javiercn/CustomElementsBlazorSampleBlazor WebAssembly, větev: blazor-wasm): Pokud chcete migrovat tuto ukázku .NET 7 na .NET 8, přečtěte si téma Migrace z ASP.NET Core 7.0 na 8.0.

Vykreslování komponent Razor pomocí JavaScriptu

U stávajících aplikací v JavaScriptu (JS) je možné komponenty Razor dynamicky vykreslovat pomocí JS.

Příklad v této části vykreslí následující Razor komponentu na stránku prostřednictvím JS.

Quote.razor:

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

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

Program Do souboru přidejte obor názvů pro umístění komponenty.

Voláním RegisterForJavaScript kořenové kolekce komponent aplikace zaregistrujte komponentu jako kořenovou komponentu Razor pro JS vykreslování.

RegisterForJavaScript obsahuje přetížení, které přijímá název JS funkce, která spouští logiku inicializace (javaScriptInitializer). Funkce JS se volá jednou za registraci součásti hned po Blazor spuštění aplikace a před vykreslením jakýchkoli komponent. Tuto funkci lze použít pro integraci s technologiemi JS , jako jsou vlastní prvky HTML nebo architektura SPA založená JSna technologii.

Jednu nebo více inicializačních funkcí lze vytvořit a volat různými registracemi komponent. Typickým případem použití je opakované použití stejné funkce inicializátoru pro více komponent, což se očekává, pokud funkce inicializátoru konfiguruje integraci s vlastními prvky nebo jinou JSarchitekturou SPA založenou na technologii SPA.

Důležité

Nezaměňujte javaScriptInitializer parametr RegisterForJavaScript s inicializátory JavaScriptu. Název parametru a JS funkce inicializátorů je shodná.

Následující příklad ukazuje dynamickou registraci předchozí Quote komponenty s "quote" jako identifikátor.

• Blazor Server V aplikaci upravte volání AddServerSideBlazor v Program souboru:

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

• Blazor WebAssembly V aplikaci zavolejte RegisterForJavaScript RootComponents v souboru na straně Program klienta:

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

Připojte funkci inicializátoru s name parameters parametry funkce k objektu window . Pro demonstrační účely zaznamená následující initializeComponent funkce název a parametry registrované komponenty.

wwwroot/jsComponentInitializers.js:

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

Vykreslujte komponentu z JS elementu kontejneru pomocí registrovaného identifikátoru a podle potřeby předáte parametry komponenty.

V následujícím příkladu:

• Komponenta Quote (quote identifikátor) se vykreslí do elementu quoteContainer showQuote při zavolání funkce.
• Řetězci uvozovek se předá parametr komponenty 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 Po načtení skriptu načtěte do aplikace předchozí skriptyJS:

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

V předchozím příkladu {BLAZOR SCRIPT} je Blazor zástupný symbol skript.

V HTML umístěte cílový element kontejneru (quoteContainer). Pro ukázku v této části aktivuje tlačítko vykreslení Quote komponenty voláním showQuoteJS funkce:

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

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

Při inicializaci před vykreslením všech komponent zaznamená Quote konzola vývojářských nástrojů prohlížeče identifikátor komponenty (name) a parametry (parameters), pokud initializeComponent je volána:

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

Show Quote Když je tlačítko vybráno, Quote komponenta se vykreslí s uvozovkou uloženou v Text zobrazeném:

Citace ©1988-1999 Satelit Love LLC: Mystery Science Theater 3000 (Trace Beaulieu (Crow))

Poznámka:

rootComponents.add vrátí instanci komponenty. Zavolejte dispose instanci, aby ji uvolnila:

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

...

rootComponent.dispose();

Předchozí příklad dynamicky vykresluje kořenovou komponentu při showQuote()JS zavolání funkce. Pokud chcete vykreslit kořenovou komponentu do elementu kontejneru při Blazor spuštění, použijte javascriptový inicializátor k vykreslení komponenty, jak ukazuje následující příklad.

Následující příklad vychází z předchozího příkladu Quote pomocí komponenty, registrace kořenové komponenty v Program souboru a inicializace jsComponentInitializers.js. Funkce showQuote() (a script.js soubor) se nepoužívá.

V HTML umístěte cílový element quoteContainer2 kontejneru pro tento příklad:

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

Pomocí inicializátoru JavaScriptu přidejte kořenovou komponentu do cílového elementu kontejneru.

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

Poznámka:

Pro volání rootComponents.addpoužijte blazor parametr (malá písmena b) poskytnutý Blazor počáteční událostí. I když registrace je platná při použití objektu Blazor (velká písmena B), upřednostňovaným přístupem je použití parametru.

Pokročilý příklad s dalšími funkcemi najdete v příkladu referenčního BasicTestApp zdroje ASP.NET Core (dotnet/aspnetcore úložiště GitHub):

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

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Vlastní elementy Blazor

Pomocí Blazor vlastních prvků můžete dynamicky vykreslovat Razor komponenty z jiných architektur SPA, jako je Angular nebo React.

Blazor vlastní prvky:

• K implementaci vlastních elementů HTML použijte standardní rozhraní HTML.
• Eliminujte potřebu ruční správy stavu a životního cyklu kořenových Razor komponent pomocí javascriptových rozhraní API.
• Jsou užitečné pro postupné zavedení Razor komponent do stávajících projektů psaných v jiných architekturách SPA.

Vlastní prvky nepodporují podřízený obsah ani součásti šablony.

Název prvku

Podle specifikace HTML musí názvy vlastních značek elementů přijmout případ kebabu:

❌Neplatný: mycounter
❌Neplatný: MY-COUNTER
❌Neplatný: MyCounter
✔️Platný: my-counter
✔️Platný: my-cool-counter

Balíček

Přidejte odkaz na balíček pro Microsoft.AspNetCore.Components.CustomElements soubor projektu aplikace.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Ukázková komponenta

Následující příklady jsou založené na Counter komponentě Blazor ze šablony projektu.

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 registrace

Pomocí následujících kroků zaregistrujte kořenovou komponentu jako vlastní prvek v Blazor Server aplikaci.

Microsoft.AspNetCore.Components.Web Přidejte obor názvů do horní části Program souboru:

using Microsoft.AspNetCore.Components.Web;

Přidejte obor názvů pro komponenty aplikace. V následujícím příkladu je BlazorSample obor názvů aplikace a komponenty jsou umístěné ve Pages složce:

using BlazorSample.Pages;

Upravte volání AddServerSideBlazorna . Zadejte vlastní prvek s RegisterCustomElement možností okruhu RootComponents . Následující příklad zaregistruje komponentu Counter pomocí vlastního elementu my-counterHTML:

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

Blazor WebAssembly registrace

Pomocí následujících kroků zaregistrujte kořenovou komponentu jako vlastní prvek v Blazor WebAssembly aplikaci.

Microsoft.AspNetCore.Components.Web Přidejte obor názvů do horní části Program souboru:

using Microsoft.AspNetCore.Components.Web;

Přidejte obor názvů pro komponenty aplikace. V následujícím příkladu je BlazorSample obor názvů aplikace a komponenty jsou umístěné ve Pages složce:

using BlazorSample.Pages;

Zavolejte RegisterCustomElement .RootComponents Následující příklad zaregistruje komponentu Counter pomocí vlastního elementu my-counterHTML:

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

Použití registrovaného vlastního elementu

Vlastní elementy můžete používat s libovolnou webovou architekturou. Například předchozí my-counter vlastní element HTML, který vykreslí komponentu aplikace Counter , se používá v aplikaci React s následujícím kódem:

<my-counter></my-counter>

Úplný příklad vytvoření vlastních prvků pomocí Blazortéto komponenty naleznete CustomElementsComponent v referenčním zdroji.

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Parametry předání

Předejte komponentě Razor parametry buď jako atributy HTML, nebo jako vlastnosti JavaScriptu v elementu DOM.

Následující Counter komponenta používá IncrementAmount parametr k nastavení inkrementačního množství Click me tlačítka.

Counter.razor:

@page "/counter"

<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;
    }
}

Vykreslujte komponentu Counter s vlastním elementem a předejte hodnotu parametru IncrementAmount jako atribut HTML. Název atributu přijímá syntaxi kebab-case (increment-amountnikoli IncrementAmount):

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

Případně můžete hodnotu parametru nastavit jako vlastnost JavaScriptu u objektu elementu. Název vlastnosti přijímá syntaxi velbloudího případu (incrementAmountnikoli IncrementAmount):

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

Hodnoty parametrů můžete kdykoli aktualizovat pomocí syntaxe atributu nebo vlastnosti.

Podporované typy parametrů:

• Pomocí syntaxe vlastností JavaScriptu můžete předat objekty libovolného typu serializovatelného typu JSON.
• Pomocí atributů HTML jste omezeni na předávání objektů řetězců, logických nebo číselných typů.

Generování komponent Angular a React

Z komponent Razor můžete generovat komponenty JavaScriptu (JS) pro konkrétní webové architektury, jako jsou Angular nebo React. Tato funkce není součástí .NET, ale je povolená podporou vykreslování Razor komponent z JS. Ukázku generování komponent Angular a React z komponent Razor najdete v ukázce generování komponent JS na GitHubu. Další informace najdete v souboru README.md ukázkové aplikace na GitHubu.

Upozorňující

Funkce komponent Angular a React jsou v současné době experimentální, nepodporují se a kdykoli se můžou změnit nebo odebrat. Uvítáme vaše názory a připomínky ohledně toho, nakolik tento konkrétní přístup splňuje vaše požadavky.