Używanie Razor składników w aplikacjach JavaScript i strukturach SPA

W tym artykule opisano sposób renderowania Razor składników z języka JavaScript, używania Blazor elementów niestandardowych oraz generowania składników Angular i React.

Uwaga

Zalecamy używanie blazor.server.js skryptów (Blazor Server) i blazor.webassembly.js (Blazor WebAssembly) podczas integrowania Razor składników z istniejącą aplikacją JavaScript do czasu dodania lepszej obsługi skryptu blazor.web.js (Blazor Web App) w przyszłości. Aby uzyskać więcej informacji, zobacz RegisterCustomElement przestał działać w Blazor 8 (dotnet/aspnetcore #53920).

Przykładowe aplikacje platformy Angular

• CustomElementsBlazorSample (Blazor Serverjaviercn/CustomElementsBlazorSample, gałąź: blazor-server): Blazor Server jest obsługiwana na platformie .NET 8/9. Aby przeprowadzić migrację tego przykładu platformy .NET 7, zobacz Migrowanie z platformy ASP.NET Core 7.0 do 8.0 i Migrowanie z platformy ASP.NET Core na platformie .NET 8 do ASP.NET Core na platformie .NET 9.
• CustomElementsBlazorSample (Blazor WebAssemblyjaviercn/CustomElementsBlazorSample, gałąź: blazor-wasm): Aby przeprowadzić migrację tego przykładu platformy .NET 7, zobacz Migrowanie z platformy ASP.NET Core 7.0 do 8.0 i Migrowanie z platformy ASP.NET Core na platformie .NET 8 do ASP.NET Core na platformie .NET 9.

Renderowanie składników Razor z poziomu języka JavaScript

Składniki aparatu Razor można dynamicznie renderować z poziomu języka JavaScript (JS) dla istniejących aplikacji JS.

Przykład w tej sekcji renderuje następujący Razor składnik na stronie za pośrednictwem metody JS.

Quote.razor:

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

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

Program W pliku dodaj przestrzeń nazw dla lokalizacji składnika.

Wywołaj RegisterForJavaScript kolekcję składników głównych aplikacji, aby zarejestrować Razor składnik jako składnik główny na potrzeby JS renderowania.

RegisterForJavaScript zawiera przeciążenie, które akceptuje nazwę JS funkcji, która wykonuje logikę inicjowania (javaScriptInitializer). Funkcja jest wywoływana JS raz na rejestrację składnika natychmiast po uruchomieniu Blazor aplikacji i przed renderowaniem wszystkich składników. Ta funkcja może służyć do integracji z technologiami JS , takimi jak elementy niestandardowe HTML lub JSoparta na strukturze SPA.

Co najmniej jedna funkcja inicjatora może być tworzona i wywoływana przez różne rejestracje składników. Typowy przypadek użycia polega na ponownym użyciu tej samej funkcji inicjatora dla wielu składników, co jest oczekiwane, jeśli funkcja inicjatora konfiguruje integrację z elementami niestandardowymi lub inną JSopartą na strukturze SPA.

Ważne

Nie należy mylić parametru javaScriptInitializer z RegisterForJavaScript inicjatorami języka JavaScript. Nazwa parametru i JS funkcji inicjatorów jest przypadkowa.

W poniższym przykładzie pokazano dynamiczną rejestrację poprzedniego Quote składnika z identyfikatorem "quote".

• W aplikacji zmodyfikuj Blazor Server wywołanie metody AddServerSideBlazor w Program pliku :

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

• W aplikacji wywołaj metodę Blazor WebAssembly RegisterForJavaScript RootComponents w pliku po stronie Program klienta:

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

Dołącz funkcję inicjatora z parametrami name funkcji i parameters do window obiektu . W celach demonstracyjnych poniższa initializeComponent funkcja rejestruje nazwę i parametry zarejestrowanego składnika.

wwwroot/jsComponentInitializers.js:

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

Renderuj składnik z elementu do kontenera przy użyciu zarejestrowanego identyfikatora, przekazując parametry składnika zgodnie z JS potrzebami.

W poniższym przykładzie:

• Składnik Quote (quote identyfikator) jest renderowany w elemencie quoteContainer po wywołaniu showQuote funkcji.
• Ciąg cudzysłowu jest przekazywany do parametru Text składnika.

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

Po załadowaniu skryptu załaduj Blazor poprzednie skrypty do JS aplikacji:

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

W poprzednim przykładzie {BLAZOR SCRIPT} symbol zastępczy jest skryptem Blazor .

W kodzie HTML umieść docelowy element kontenera (quoteContainer). Na potrzeby pokazu w tej sekcji przycisk wyzwala renderowanie Quote składnika przez wywołanie showQuoteJS funkcji:

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

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

Podczas inicjowania przed renderowaniem wszystkich składników konsola narzędzi deweloperskich przeglądarki rejestruje Quote identyfikator składnika (name) i parametry (parameters), gdy initializeComponent jest wywoływany:

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

Po wybraniu Show Quote Quote przycisku składnik jest renderowany przy użyciu cudzysłowu przechowywanego w Text wyświetlonym:

Cytat ©1988-1999 Satellite of Love LLC: Mystery Science Theater 3000 (Trace Beaulieu (Wron))

Uwaga

rootComponents.add zwraca wystąpienie składnika. Wywołaj dispose wystąpienie, aby go zwolnić:

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

...

rootComponent.dispose();

Powyższy przykład dynamicznie renderuje składnik główny po wywołaniu showQuote()JS funkcji. Aby renderować składnik główny w elemencie kontenera podczas Blazor uruchamiania, użyj inicjatora języka JavaScript do renderowania składnika, jak pokazano w poniższym przykładzie.

Poniższy przykład opiera się na poprzednim przykładzie, używając Quote składnika, rejestracji składnika głównego w Program pliku i inicjowania jsComponentInitializers.jselementu . Funkcja showQuote() (i script.js plik) nie są używane.

W kodzie HTML umieść element kontenera docelowego, quoteContainer2 na potrzeby tego przykładu:

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

Za pomocą inicjatora języka JavaScript dodaj składnik główny do elementu kontenera docelowego.

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

Uwaga

W przypadku wywołania metody rootComponents.addużyj parametru blazor (małe litery b) dostarczonego Blazor przez zdarzenie początkowe. Chociaż rejestracja jest prawidłowa w przypadku używania Blazor obiektu (wielkie litery B), preferowaną metodą jest użycie parametru .

Aby zapoznać się z zaawansowanym przykładem dodatkowymi funkcjami, zobacz przykład w BasicTestApp źródle referencyjnym platformy ASP.NET Core (dotnet/aspnetcore repozytorium GitHub):

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

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Niestandardowe elementy platformy Blazor

Elementy Blazor niestandardowe umożliwiają dynamiczne renderowanie Razor składników z innych struktur SPA, takich jak Angular lub React.

Blazor elementy niestandardowe:

• Używanie standardowych interfejsów HTML do implementowania niestandardowych elementów HTML.
• Wyeliminuj konieczność ręcznego zarządzania stanem i cyklem życia składników głównych Razor przy użyciu interfejsów API języka JavaScript.
• Są przydatne do stopniowego wprowadzania Razor składników do istniejących projektów napisanych w innych strukturach SPA.

Elementy niestandardowe nie obsługują zawartości podrzędnej ani szablonowych składników.

Nazwa elementu

Zgodnie ze specyfikacją HTML nazwy tagów niestandardowych elementów muszą przyjąć przypadek kebabu:

❌Nieprawidłowy: mycounter
❌Nieprawidłowy: MY-COUNTER
❌Nieprawidłowy: MyCounter
✔️Ważny: my-counter
✔️Ważny: my-cool-counter

Pakiet

Dodaj odwołanie do pakietu do Microsoft.AspNetCore.Components.CustomElements pliku projektu aplikacji.

Uwaga

Aby uzyskać instrukcje dodawania pakietów do aplikacji .NET, zobacz artykuły w sekcji Instalowanie pakietów i zarządzanie nimi w temacie Przepływ pracy użycia pakietów (dokumentacja programu NuGet). Sprawdź prawidłowe wersje pakietów pod adresem NuGet.org.

Przykładowy składnik

Poniższe przykłady są oparte na składniku Counter z szablonu Blazor 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 rejestracja

Wykonaj następujące kroki, aby zarejestrować składnik główny jako element niestandardowy w Blazor Server aplikacji.

Microsoft.AspNetCore.Components.Web Dodaj przestrzeń nazw na początku Program pliku:

using Microsoft.AspNetCore.Components.Web;

Dodaj przestrzeń nazw dla składników aplikacji. W poniższym przykładzie przestrzeń nazw aplikacji to BlazorSample i składniki znajdują się w folderze Pages :

using BlazorSample.Pages;

Zmodyfikuj wywołanie metody .AddServerSideBlazor Określ element niestandardowy z RegisterCustomElement opcją obwodu RootComponents . Poniższy przykład rejestruje składnik za Counter pomocą niestandardowego elementu my-counterHTML :

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

Blazor WebAssembly rejestracja

Wykonaj następujące kroki, aby zarejestrować składnik główny jako element niestandardowy w Blazor WebAssembly aplikacji.

Microsoft.AspNetCore.Components.Web Dodaj przestrzeń nazw na początku Program pliku:

using Microsoft.AspNetCore.Components.Web;

Dodaj przestrzeń nazw dla składników aplikacji. W poniższym przykładzie przestrzeń nazw aplikacji to BlazorSample i składniki znajdują się w folderze Pages :

using BlazorSample.Pages;

Wywołaj metodę RegisterCustomElement na RootComponents. Poniższy przykład rejestruje składnik za Counter pomocą niestandardowego elementu my-counterHTML :

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

Używanie zarejestrowanego elementu niestandardowego

Elementu niestandardowego można używać z dowolną platformą internetową. Na przykład poprzedni my-counter niestandardowy element HTML renderujący składnik aplikacji Counter jest używany w aplikacji React z następującym znacznikiem:

<my-counter></my-counter>

Pełny przykład tworzenia elementów niestandardowych za pomocą Blazorprogramu można znaleźć CustomElementsComponent w składniku w źródle referencyjnym.

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Przekazywanie parametrów

Przekaż parametry do Razor składnika jako atrybuty HTML lub właściwości języka JavaScript w elemencie DOM.

Counter Poniższy składnik używa parametru IncrementAmount w celu ustawienia przyrostowej Click me ilości przycisku.

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

Renderowanie Counter składnika za pomocą elementu niestandardowego i przekazanie wartości do parametru IncrementAmount jako atrybutu HTML. Nazwa atrybutu przyjmuje składnię kebab-case (increment-amountnie IncrementAmount):

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

Alternatywnie można ustawić wartość parametru jako właściwość Języka JavaScript w obiekcie elementu. Nazwa właściwości przyjmuje składnię wielkości liter wielbłąda (incrementAmounta nie IncrementAmount):

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

Wartości parametrów można aktualizować w dowolnym momencie przy użyciu atrybutu lub składni właściwości.

Obsługiwane typy parametrów:

• Korzystając ze składni właściwości języka JavaScript, można przekazać obiekty dowolnego typu serializowalnego w formacie JSON.
• Używanie atrybutów HTML jest ograniczone do przekazywania obiektów ciągów, wartości logicznych lub typów liczbowych.

Generowanie składników platform Angular i React

Składniki specyficzne dla platform internetowych języka JavaScript (JS), takich jak Angular lub React, można generować ze składników aparatu Razor. Ta funkcja nie jest dołączona do platformy .NET, ale jest włączona przez obsługę składników renderowania Razor z programu JS. Przykład generowania składników JS w serwisie GitHub pokazuje, jak generować składniki platform Angular i React ze składników aparatu Razor. Aby uzyskać dodatkowe informacje, zobacz plik README.md przykładowej aplikacji w serwisie GitHub.

Ostrzeżenie

Funkcje składników platform Angular i React są obecnie eksperymentalne, nieobsługiwane i mogą ulec zmianie lub zostać usunięte w dowolnym czasie. Chętnie poznamy Twoją opinię o tym, jak to podejście spełnia Twoje wymagania.