Verwenden von Razor-Komponenten in JavaScript-Apps und SPA-Frameworks

In diesem Artikel erfahren Sie, wie Sie Razor-Komponenten aus JavaScript rendern, benutzerdefinierte Blazor-Elemente verwenden und Angular- und React-Komponenten generieren.

Hinweis

Wir empfehlen die Verwendung der Skripte blazor.server.js (Blazor Server) und blazor.webassembly.js (Blazor WebAssembly), wenn Sie Razor-Komponenten in eine bestehende JavaScript-Anwendung integrieren, bis in Zukunft eine bessere Unterstützung für das Skript blazor.web.js (Blazor Web App) hinzugefügt wird. Weitere Informationen finden Sie unter RegisterCustomElement funktioniert nicht mehr in Blazor 8 (dotnet/aspnetcore #53920).

Angular-Beispiel-Apps

• CustomElementsBlazorSample (Blazor Server) (javiercn/CustomElementsBlazorSample, Branch: blazor-server): Blazor Server wird in .NET 8 unterstützt. Informationen zum Migrieren dieses .NET 7-Beispiels zu .NET 8 finden Sie unter Migrieren von ASP.NET Core 7.0 zu 8.0.
• CustomElementsBlazorSample (Blazor WebAssembly) (javiercn/CustomElementsBlazorSample, Branch: blazor-wasm): Weitere Informationen zur Migration dieses .NET 7-Beispiels zu .NET 8 finden Sie unter Migration von ASP.NET Core 7.0 zu 8.0.

Rendern von Razor-Komponenten aus JavaScript

Razor Komponenten können für vorhandene JS-Apps dynamisch aus JavaScript (JS) gerendert werden.

Im Beispiel in diesem Abschnitt wird die folgende Razor-Komponente per JS in eine Seite gerendert.

Quote.razor:

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

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

Fügen Sie in der Program-Datei den Namespace für den Speicherort der Komponente hinzu.

Rufen Sie für die Stammkomponentensammlung der App RegisterForJavaScript auf, um eine Razor-Komponente als Stammkomponente für das JS-Rendern zu registrieren.

RegisterForJavaScript enthält eine Überladung, die den Namen einer JS-Funktion akzeptiert, die Initialisierungslogik ausführt (javaScriptInitializer). Die JS-Funktion wird einmal pro Komponentenregistrierung aufgerufen, unmittelbar nach dem Starten der Blazor-App und vor dem Rendern von Komponenten. Diese Funktion kann für die Integration in JS-Technologien wie benutzerdefinierte HTML-Elemente oder ein JS-basiertes SPA-Framework verwendet werden.

Eine oder mehrere Initialisiererfunktionen können erstellt und von verschiedenen Komponentenregistrierungen aufgerufen werden. Der typische Anwendungsfall besteht darin, dieselbe Initialisiererfunktion für mehrere Komponenten wiederzuverwenden, was erwartet wird, wenn die Initialisiererfunktion die Integration mit benutzerdefinierten Elementen oder einem anderen JS-basierten SPA_Framework konfiguriert.

Wichtig

Verwechseln Sie den Parameter javaScriptInitializer von RegisterForJavaScript nicht mit JavaScript-Initialisierern. Der Name des Parameters und des JS-Initialisiererfeatures ist zufällig.

Im folgenden Beispiel wird die dynamische Registrierung der vorherigen Quote-Komponente mit „quote“ als Bezeichner veranschaulicht.

• Ändern Sie in einer Blazor Server-App den Aufruf von AddServerSideBlazor in der Program-Datei:

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

• Rufen Sie in einer Blazor WebAssembly-App RegisterForJavaScript für RootComponents in der clientseitigen Program-Datei auf:

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

Fügen Sie die Initialisiererfunktion mit den Funktionsparametern name und parameters an das window-Objekt an. Zu Demonstrationszwecken protokolliert die folgende initializeComponent-Funktion den Namen und die Parameter der registrierten Komponente.

wwwroot/jsComponentInitializers.js:

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

Rendern Sie die Komponente aus JS mithilfe des registrierten Bezeichners in ein Containerelement, und übergeben Sie bei Bedarf Komponentenparameter.

Im folgenden Beispiel:

• Die Quote-Komponente (quote-Bezeichner) wird in das quoteContainer-Element gerendert, wenn die Funktion showQuote aufgerufen wird.
• Eine Anführungszeichen-Zeichenfolge wird an den Text-Parameter der Komponente übergeben.

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

Nachdem das BlazorSkript geladen ist, laden Sie die vorhergehenden Skripte in die JS-Anwendung:

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

Im vorangegangenen Beispiel ist der {BLAZOR SCRIPT}-Platzhalter das Blazor-Skript.

Platzieren Sie in HTML das Zielcontainerelement (quoteContainer). Für die Demonstration in diesem Abschnitt löst eine Schaltfläche das Rendern der Quote-Komponente aus, indem die JS-Funktion showQuote aufgerufen wird:

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

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

Bei der Initialisierung, bevor Komponenten gerendert werden, protokolliert die Entwicklertools-Konsole des Browsers den Quote-Bezeichner (name) und die Parameter (parameters) der Komponente, wenn initializeComponent aufgerufen wird:

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

Wenn die Schaltfläche Show Quote ausgewählt ist, wird die Quote-Komponente mit dem in Text gespeicherten Anführungszeichen gerendert:

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

Hinweis

rootComponents.add gibt eine Instanz der Komponente zurück. Rufen Sie dispose für die Instanz auf, um sie freizugeben:

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

...

rootComponent.dispose();

Das vorherige Beispiel rendert die Stammkomponente dynamisch, wenn die JS-Funktion showQuote() aufgerufen wird. Um eine Stammkomponente beim Start von Blazor in ein Containerelement zu rendern, verwenden Sie einen JavaScript-Initialisierer, wie im folgenden Beispiel veranschaulicht.

Das folgende Beispiel baut auf dem vorherigen Beispiel auf und verwendet die Quote-Komponente, die Stammkomponentenregistrierung in der Program-Datei und die Initialisierung von jsComponentInitializers.js. Die Funktion showQuote() und die Datei script.js werden nicht verwendet.

Platzieren Sie in HTML das Zielcontainerelement, quoteContainer2, für dieses Beispiel:

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

Fügen Sie mithilfe eines JavaScript-Initialisierers die Stammkomponente zum Zielcontainerelement hinzu.

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

Hinweis

Verwenden Sie für den Aufruf von rootComponents.add den Parameter blazor (klein geschrieben b), der vom Blazor-Startereignis bereitgestellt wird. Die Registrierung ist zwar auch bei Verwendung des Objekts Blazor (mit großem B) gültig, aber die bevorzugte Vorgehensweise besteht darin, den Parameter zu verwenden.

Ein erweitertes Beispiel mit zusätzlichen Features finden Sie in der BasicTestApp ASP.NET Core-Referenzquelle (dotnet/aspnetcore GitHub-Repository):

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

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

Benutzerdefinierte Blazor-Elemente

Verwenden Sie benutzerdefinierte Blazor-Elemente, um Razor-Komponenten aus anderen SPA-Frameworks, z. B. Angular oder React, dynamisch zu rendern.

Benutzerdefinierte Blazor-Elemente:

• Verwenden Sie Standard-HTML-Schnittstellen, um benutzerdefinierte HTML-Elemente zu implementieren.
• Vermeiden Sie die Notwendigkeit, den Zustand und den Lebenszyklus von Razor-Stammkomponenten mithilfe von JavaScript-APIs manuell zu verwalten.
• Sind nützlich für die schrittweise Einführung von Razor-Komponenten in vorhandene Projekte, die in anderen SPA-Frameworks geschrieben wurden.

Benutzerdefinierte Elemente unterstützen keine untergeordneten Inhalte oder Vorlagenkomponenten.

Elementname

Gemäß der HTML-Spezifikation müssen benutzerdefinierte Element-Tagnamen kebab-Case übernehmen:

❌Ungültig: mycounter
❌Ungültig: MY-COUNTER
❌Ungültig: MyCounter
✔️Gültig: my-counter
✔️Gültig: my-cool-counter

Paket

Fügen Sie einen Paketverweis für Microsoft.AspNetCore.Components.CustomElements in der Projektdatei der App hinzu.

Hinweis

Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

Beispielkomponente

Die folgenden Beispiele basieren auf der Counter-Komponente aus der Blazor-Projektvorlage.

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-Registrierung

Führen Sie die folgenden Schritte aus, um eine Stammkomponente als benutzerdefiniertes Element in einer Blazor Server-App zu registrieren.

Fügen Sie den Microsoft.AspNetCore.Components.Web-Namespace am Anfang der Datei Program hinzu:

using Microsoft.AspNetCore.Components.Web;

Fügen Sie einen Namespace für die Komponenten der App hinzu. Im folgenden Beispiel ist BlazorSample der Namespace der App, und die Komponenten befinden sich im Ordner Pages:

using BlazorSample.Pages;

Ändern Sie den Aufruf in AddServerSideBlazor. Geben Sie das benutzerdefinierte Element mit RegisterCustomElement für die RootComponents-Leitungsoption an. Im folgenden Beispiel wird die Counter-Komponente beim benutzerdefinierten HTML-my-counter-Element registriert:

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

Blazor WebAssembly-Registrierung

Führen Sie die folgenden Schritte aus, um eine Stammkomponente als benutzerdefiniertes Element in einer Blazor WebAssembly-App zu registrieren.

Fügen Sie den Microsoft.AspNetCore.Components.Web-Namespace am Anfang der Datei Program hinzu:

using Microsoft.AspNetCore.Components.Web;

Fügen Sie einen Namespace für die Komponenten der App hinzu. Im folgenden Beispiel ist BlazorSample der Namespace der App, und die Komponenten befinden sich im Ordner Pages:

using BlazorSample.Pages;

Rufen Sie RegisterCustomElement für RootComponents auf. Im folgenden Beispiel wird die Counter-Komponente beim benutzerdefinierten HTML-my-counter-Element registriert:

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

Verwenden des registrierten benutzerdefinierten Elements

Verwenden Sie das benutzerdefinierte Element mit einem beliebigen Webframework. Das vorstehende benutzerdefinierte HTML-my-counter-Element, das die Counter-Komponente der App rendert, wird zum Beispiel in einer React-App mit dem folgenden Markup verwendet:

<my-counter></my-counter>

Ein vollständiges Beispiel zum Erstellen benutzerdefinierter Elemente mit Blazor finden Sie in der CustomElementsComponent-Komponente in der Referenzquelle.

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

Übergeben von Parametern

Übergeben Sie die Parameter entweder als HTML-Attribute oder als JavaScript-Eigenschaften für das DOM-Element an Ihre Razor-Komponente.

Die folgende Counter-Komponente verwendet einen IncrementAmount-Parameter, um den Inkrementwert der SchaltflächeClick me festzulegen.

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

Rendern Sie die Counter-Komponente mit dem benutzerdefinierten Element, und übergeben Sie einen Wert als HTML-Attribut an den IncrementAmount-Parameter. Der Attributname verwendet die kebab-Syntax der Groß-/Kleinschreibung (increment-amount, nicht IncrementAmount):

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

Alternativ können Sie den Wert des Parameters als JavaScript-Eigenschaft für das Elementobjekt festlegen. Der Eigenschaftsname übernimmt die camel-Syntax der Groß-/Kleinschreibung (incrementAmount, nicht IncrementAmount):

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

Sie können Parameterwerte jederzeit mithilfe der Attribut- oder Eigenschaftssyntax aktualisieren.

Unterstützte Parametertypen:

• Mithilfe der JavaScript-Eigenschaftssyntax können Sie Objekte eines beliebigen JSON-serialisierbaren Typs übergeben.
• Bei der Verwendung von HTML-Attributen sind Sie auf die Übergabe von Objekten von Zeichenfolgen-, booleschen oder numerischen Typen beschränkt.

Generieren von Angular- und React-Komponenten

Frameworkspezifische JavaScript-JS-Komponenten werden aus Razor-Komponenten für Webframeworks, z. B. Angular oder React, generiert. Diese Funktion ist nicht in .NET enthalten, wird aber durch die Unterstützung für das Rendern von Razor-Komponenten aus JS aktiviert. Das Beispiel für die JS-Komponentengenerierung auf GitHub veranschaulicht, wie Sie Angular- und React-Komponenten aus Razor-Komponenten generieren. Weitere Informationen finden Sie in der README.md-Datei der Beispiel-App auf GitHub.

Warnung

Die Angular- und React-Komponentenfeatures sind derzeit experimentell, werden nicht unterstützt und können jederzeit geändert oder entfernt werden. Wir freuen uns über Ihr Feedback, wie gut dieser Ansatz Ihre Anforderungen erfüllt.