Aufrufen von JavaScript-Funktionen über .NET-Methoden in ASP.NET Core Blazor

In diesem Artikel wird erläutert, wie JavaScript-Funktionen (JS) aus .NET aufgerufen werden.

Informationen zum Aufrufen von .NET-Methoden aus JS finden Sie unter Aufrufen von .NET-Methoden über JavaScript-Funktionen in Blazor in ASP.NET Core.

Aufrufen von JS-Funktionen

IJSRuntime wird vom Blazor-Framework registriert. Fügen Sie für einen Aufruf an JS über .NET die IJSRuntime-Abstraktion ein, und rufen Sie eine der folgenden Methoden auf:

• IJSRuntime.InvokeAsync
• JSRuntimeExtensions.InvokeAsync
• JSRuntimeExtensions.InvokeVoidAsync

Für die oben genannten .NET-Methoden, die JS-Funktionen aufrufen, gilt Folgendes:

• Der Funktionsbezeichner (String) ist relativ zum globalen Bereich (window). Der Bezeichner zum Aufrufen von window.someScope.someFunction lautet someScope.someFunction. Die Funktion muss nicht registriert werden, bevor sie aufgerufen wird.
• Übergeben Sie eine beliebige Anzahl von serialisierbaren JSON-Argumenten in Object[] an eine JS-Funktion.
• Das Abbruchstoken (CancellationToken) leitet eine Benachrichtigung weiter, dass Vorgänge abgebrochen werden sollen.
• TimeSpan stellt ein Zeitlimit für einen JS-Vorgang dar.
• Der Rückgabetyp TValue muss ebenfalls JSON-serialisierbar sein. TValue sollte mit dem .NET-Typ übereinstimmen, der dem zurückgegebenen JSON-Typ am ehesten entspricht.
• Ein JS Promise-Objekt wird für InvokeAsync-Methoden zurückgegeben. InvokeAsync entpackt das Promise-Objekt und gibt den Wert zurück, der vom Promise-Objekt erwartet wird.

Für Blazor-Apps mit aktiviertem Vorabrendering (was bei serverseitigen Apps standardmäßig der Fall ist) sind Aufrufe von JS während des Vorabrenderings nicht möglich. Weitere Informationen finden Sie im Abschnitt Voarabrendering.

Das folgende Beispiel basiert auf TextDecoder, dabei handelt es sich um einen auf JS basierenden Decoder. Im Beispiel wird veranschaulicht, wie eine JS-Funktion aus einer C#-Methode aufgerufen wird, die eine Anforderung aus Entwicklercode in eine vorhandene JS-API auslagert. Die JS-Funktion akzeptiert ein Bytearray von einer C#-Methode, decodiert das Array und gibt den Text zum Anzeigen an die Komponente zurück.

<script>
  window.convertArray = (win1251Array) => {
    var win1251decoder = new TextDecoder('windows-1251');
    var bytes = new Uint8Array(win1251Array);
    var decodedArray = win1251decoder.decode(bytes);
    return decodedArray;
  };
</script>

Hinweis

Allgemeine Anleitungen zu JS Standort und unseren Empfehlungen für Produktions-Apps finden Sie unter JavaScript-Speicherort in ASP.NET Core Blazor -Apps.

Die folgende -Komponente:

• ruft die JS-Funktion convertArray mit InvokeAsync auf, wenn auf eine Schaltfläche geklickt wird (Convert Array).
• Nachdem die JS-Funktion aufgerufen wurde, wird das übergebene Array in eine Zeichenfolge konvertiert. Die Zeichenfolge wird zur Anzeige an die Komponente zurückgegeben (text).

CallJs1.razor:

@page "/call-js-1"
@inject IJSRuntime JS

<PageTitle>Call JS 1</PageTitle>

<h1>Call JS Example 1</h1>

<p>
    <button @onclick="ConvertArray">Convert Array</button>
</p>

<p>
    @text
</p>

<p>
    Quote ©2005 <a href="https://www.uphe.com">Universal Pictures</a>: 
    <a href="https://www.uphe.com/movies/serenity-2005">Serenity</a><br>
    <a href="https://www.imdb.com/name/nm0472710/">David Krumholtz on IMDB</a>
</p>

@code {
    private MarkupString text;

    private uint[] quoteArray = 
        new uint[]
        {
            60, 101, 109, 62, 67, 97, 110, 39, 116, 32, 115, 116, 111, 112, 32,
            116, 104, 101, 32, 115, 105, 103, 110, 97, 108, 44, 32, 77, 97,
            108, 46, 60, 47, 101, 109, 62, 32, 45, 32, 77, 114, 46, 32, 85, 110,
            105, 118, 101, 114, 115, 101, 10, 10,
        };

    private async Task ConvertArray() => 
        text = new(await JS.InvokeAsync<string>("convertArray", quoteArray));
}

JavaScript-API auf Benutzergesten beschränkt

Dieser Abschnitt gilt für serverseitige Komponenten.

Einige JavaScript-APIs (JS) für Browser können nur im Zusammenhang mit einer Benutzergeste ausgeführt werden, z. B. mit Fullscreen API (MDN-Dokumentation). Diese APIs können nicht über den JS-Interop-Mechanismus in serverseitigen Komponenten aufgerufen werden, da die Behandlung von UI-Ereignissen asynchron und im Allgemeinen nicht mehr im Kontext der Benutzergeste erfolgt. Die App muss das Ereignis auf der Benutzeroberfläche vollständig in JavaScript verarbeiten. Verwenden Sie daher onclick anstelle des Attributs Blazor der @onclick-Anweisung.

Aufrufen von JavaScript-Funktionen ohne Lesen eines zurückgegebenen Werts (InvokeVoidAsync)

Verwenden Sie InvokeVoidAsync in folgenden Fällen:

• .NET ist nicht erforderlich, um das Ergebnis eines JavaScript-Aufrufs (JS) zu lesen.
• JS-Funktionen geben void(0)/void 0 oder undefined zurück.

Stellen Sie eine displayTickerAlert1JS-Funktion bereit. Die Funktion wird mit InvokeVoidAsync aufgerufen und gibt keinen Wert zurück:

<script>
  window.displayTickerAlert1 = (symbol, price) => {
    alert(`${symbol}: $${price}!`);
  };
</script>

Hinweis

Allgemeine Anleitungen zu JS Standort und unseren Empfehlungen für Produktions-Apps finden Sie unter JavaScript-Speicherort in ASP.NET Core Blazor -Apps.

Beispiel (InvokeVoidAsync) für die .razor-Komponente

TickerChanged ruft die handleTickerChanged1-Methode in der folgenden Komponente auf.

CallJs2.razor:

@page "/call-js-2"
@inject IJSRuntime JS

<PageTitle>Call JS 2</PageTitle>

<h1>Call JS Example 2</h1>

<p>
    <button @onclick="SetStock">Set Stock</button>
</p>

@if (stockSymbol is not null)
{
    <p>@stockSymbol price: @price.ToString("c")</p>
}

@code {
    private string? stockSymbol;
    private decimal price;

    private async Task SetStock()
    {
        stockSymbol = 
            $"{(char)('A' + Random.Shared.Next(0, 26))}" +
            $"{(char)('A' + Random.Shared.Next(0, 26))}";
        price = Random.Shared.Next(1, 101);
        await JS.InvokeVoidAsync("displayTickerAlert1", stockSymbol, price);
    }
}

Beispiel (InvokeVoidAsync) für die .cs-Klasse

JsInteropClasses1.cs:

using Microsoft.JSInterop;

namespace BlazorSample;

public class JsInteropClasses1(IJSRuntime js) : IDisposable
{
    private readonly IJSRuntime js = js;

    public async ValueTask TickerChanged(string symbol, decimal price) => 
        await js.InvokeVoidAsync("displayTickerAlert1", symbol, price);

    // Calling SuppressFinalize(this) prevents derived types that introduce 
    // a finalizer from needing to re-implement IDisposable.
    public void Dispose() => GC.SuppressFinalize(this);
}

TickerChanged ruft die handleTickerChanged1-Methode in der folgenden Komponente auf.

CallJs3.razor:

@page "/call-js-3"
@implements IDisposable
@inject IJSRuntime JS

<PageTitle>Call JS 3</PageTitle>

<h1>Call JS Example 3</h1>

<p>
    <button @onclick="SetStock">Set Stock</button>
</p>

@if (stockSymbol is not null)
{
    <p>@stockSymbol price: @price.ToString("c")</p>
}

@code {
    private string? stockSymbol;
    private decimal price;
    private JsInteropClasses1? jsClass;

    protected override void OnInitialized() => jsClass = new(JS);

    private async Task SetStock()
    {
        if (jsClass is not null)
        {
            stockSymbol = 
                $"{(char)('A' + Random.Shared.Next(0, 26))}" +
                $"{(char)('A' + Random.Shared.Next(0, 26))}";
            price = Random.Shared.Next(1, 101);
            await jsClass.TickerChanged(stockSymbol, price);
        }
    }

    public void Dispose() => jsClass?.Dispose();
}

Aufrufen von JavaScript-Funktionen und Lesen eines zurückgegebenen Werts (InvokeAsync)

Verwenden Sie InvokeAsync, wenn .NET das Ergebnis eines JavaScript-Aufrufs (JS) lesen soll.

Stellen Sie eine displayTickerAlert2JS-Funktion bereit. Im folgenden Beispiel wird eine anzuzeigende Zeichenfolge vom Aufrufer zurückgegeben:

<script>
  window.displayTickerAlert2 = (symbol, price) => {
    if (price < 20) {
      alert(`${symbol}: $${price}!`);
      return "User alerted in the browser.";
    } else {
      return "User NOT alerted.";
    }
  };
</script>

Hinweis

Allgemeine Anleitungen zu JS Standort und unseren Empfehlungen für Produktions-Apps finden Sie unter JavaScript-Speicherort in ASP.NET Core Blazor -Apps.

Beispiel (InvokeAsync) für die .razor-Komponente

TickerChanged ruft die handleTickerChanged2-Methode auf und zeigt die zurückgegebene Zeichenfolge in der folgenden Komponente an.

CallJs4.razor:

@page "/call-js-4"
@inject IJSRuntime JS

<PageTitle>Call JS 4</PageTitle>

<h1>Call JS Example 4</h1>

<p>
    <button @onclick="SetStock">Set Stock</button>
</p>

@if (stockSymbol is not null)
{
    <p>@stockSymbol price: @price.ToString("c")</p>
}

@if (result is not null)
{
    <p>@result</p>
}

@code {
    private string? stockSymbol;
    private decimal price;
    private string? result;

    private async Task SetStock()
    {
        stockSymbol = 
            $"{(char)('A' + Random.Shared.Next(0, 26))}" +
            $"{(char)('A' + Random.Shared.Next(0, 26))}";
        price = Random.Shared.Next(1, 101);
        var interopResult = 
            await JS.InvokeAsync<string>("displayTickerAlert2", stockSymbol, price);
        result = $"Result of TickerChanged call for {stockSymbol} at " +
            $"{price.ToString("c")}: {interopResult}";
    }
}

Beispiel (InvokeAsync) für die .cs-Klasse

JsInteropClasses2.cs:

using Microsoft.JSInterop;

namespace BlazorSample;

public class JsInteropClasses2(IJSRuntime js) : IDisposable
{
    private readonly IJSRuntime js = js;

    public async ValueTask<string> TickerChanged(string symbol, decimal price) => 
        await js.InvokeAsync<string>("displayTickerAlert2", symbol, price);

    // Calling SuppressFinalize(this) prevents derived types that introduce 
    // a finalizer from needing to re-implement IDisposable.
    public void Dispose() => GC.SuppressFinalize(this);
}

TickerChanged ruft die handleTickerChanged2-Methode auf und zeigt die zurückgegebene Zeichenfolge in der folgenden Komponente an.

CallJs5.razor:

@page "/call-js-5"
@implements IDisposable
@inject IJSRuntime JS

<PageTitle>Call JS 5</PageTitle>

<h1>Call JS Example 5</h1>

<p>
    <button @onclick="SetStock">Set Stock</button>
</p>

@if (stockSymbol is not null)
{
    <p>@stockSymbol price: @price.ToString("c")</p>
}

@if (result is not null)
{
    <p>@result</p>
}

@code {
    private string? stockSymbol;
    private decimal price;
    private JsInteropClasses2? jsClass;
    private string? result;

    protected override void OnInitialized() => jsClass = new(JS);

    private async Task SetStock()
    {
        if (jsClass is not null)
        {
            stockSymbol = 
                $"{(char)('A' + Random.Shared.Next(0, 26))}" +
                $"{(char)('A' + Random.Shared.Next(0, 26))}";
            price = Random.Shared.Next(1, 101);
            var interopResult = await jsClass.TickerChanged(stockSymbol, price);
            result = $"Result of TickerChanged call for {stockSymbol} at " +
                $"{price.ToString("c")}: {interopResult}";
        }
    }

    public void Dispose() => jsClass?.Dispose();
}

Szenarios der dynamischen Inhaltsgenerierung

Verwenden Sie das [Inject]-Attribut für die dynamische Inhaltsgenerierung mit BuildRenderTree:

[Inject]
IJSRuntime JS { get; set; }

Voarabrendering

In diesem Abschnitt werden serverseitige Apps beschrieben, die Razor-Komponenten vorab rendern. Das Vorabrendering wird in Vorabrendern von ASP.NET Core-Razor-Komponenten behandelt.

Hinweis

Interne Navigation für interaktives Routing in Blazor Web Apps beinhaltet keine Anforderung neuer Seiteninhalte vom Server. Daher findet das Vorabrendern nicht für interne Seitenanforderungen statt. Wenn die App interaktives Routing verwendet, führen Sie ein vollständiges Neuladen der Seite für Komponentenbeispiele durch, die das Vorabrendern veranschaulichen. Weitere Informationen finden Sie unter Prerendering von Razor-Komponenten in ASP.NET Core.

Während der Voreinstellung ist das Aufrufen von JavaScript (JS) nicht möglich. Das folgende Beispiel zeigt, wie JS-Interoperabilität als Teil der Initialisierungslogik einer Komponente auf eine Weise verwendet wird, die mit dem Voarabrendering kompatibel ist.

Die folgende -Funktion scrollElementIntoView:

• Scrollt zum übergebenen Element mit scrollIntoView.
• Gibt den top-Eigenschaftswert des Elements von der getBoundingClientRect-Methode zurück.

window.scrollElementIntoView = (element) => {
  element.scrollIntoView();
  return element.getBoundingClientRect().top;
}

Wenn IJSRuntime.InvokeAsync die JS-Funktion im Komponentencode aufruft, wird ElementReference nur in OnAfterRenderAsync und nicht in einer früheren Lebenszyklusmethode verwendet, da es kein HTML-DOM-Element gibt, bis die Komponente gerendert wird.

StateHasChanged (Referenzquelle) wird aufgerufen, um die erneute Darstellung der Komponente mit dem neuen Status, der aus dem Aufruf zur JS-Interoperabilität erhalten wurde, in die Warteschlange zu stellen (weitere Informationen finden Sie unter Rendern von ASP.NET Core Razor-Komponenten). Es wird keine Endlosschleife erstellt, da StateHasChanged nur aufgerufen wird, wenn scrollPosition auf null festgelegt wurde.

PrerenderedInterop.razor:

@page "/prerendered-interop"
@using Microsoft.AspNetCore.Components
@using Microsoft.JSInterop
@inject IJSRuntime JS

<PageTitle>Prerendered Interop</PageTitle>

<h1>Prerendered Interop Example</h1>

<div @ref="divElement" style="margin-top:2000px">
    Set value via JS interop call: <strong>@scrollPosition</strong>
</div>

@code {
    private ElementReference divElement;
    private double? scrollPosition;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && scrollPosition is null)
        {
            scrollPosition = await JS.InvokeAsync<double>(
                "scrollElementIntoView", divElement);

            StateHasChanged();
        }
    }
}

Im vorherigen Beispiel wird der Client mit einer globalen Funktion belastet. Einen besseren Ansatz für Produktions-Apps finden Sie unter JavaScript-Isolation in JavaScript-Modulen.

Synchrone JS-Interoperabilität in clientseitigen Komponenten

Dieser Abschnitt gilt nur für clientseitige Komponenten.

JS-Interoperabilitätsaufrufe sind asynchron, unabhängig davon, ob der aufgerufene Code synchron oder asynchron ist. Die Aufrufe sind asynchron, um sicherzustellen, dass die Komponenten mit den serverseitigen und clientseitigen Rendermodi kompatibel sind. Auf dem Server müssen alle JS-Interop-Aufrufe asynchron sein, da sie über eine Netzwerkverbindung gesendet werden.

Wenn Ihre Komponente ausschließlich in WebAssembly ausgeführt wird, können Sie sich für synchrone JS-Interop-Aufrufe entscheiden. Dies ist mit etwas weniger Mehraufwand verbunden als asynchrone Aufrufe und kann zu weniger Renderingzyklen führen, da es keinen Zwischenzustand gibt, während auf die Ergebnisse gewartet wird.

Um in einer clientseitigen Komponente einen synchronen Aufruf von .NET an JavaScript zu richten, wandeln Sie IJSRuntime in IJSInProcessRuntime um, um den JS-Interop-Aufruf auszuführen:

@inject IJSRuntime JS

...

@code {
    protected override void HandleSomeEvent()
    {
        var jsInProcess = (IJSInProcessRuntime)JS;
        var value = jsInProcess.Invoke<string>("javascriptFunctionIdentifier");
    }
}

Wenn Sie IJSObjectReference in clientseitigen Komponenten mit ASP.NET Core 5.0 oder höher verwenden, können Sie IJSInProcessObjectReference stattdessen synchron verwenden. IJSInProcessObjectReference implementiert IAsyncDisposable/IDisposable und sollte für die Garbage Collection verworfen werden, um Arbeitsspeicherverlust zu verhindern, wie das folgende Beispiel veranschaulicht:

@inject IJSRuntime JS
@implements IAsyncDisposable

...

@code {
    ...
    private IJSInProcessObjectReference? module;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            module = await JS.InvokeAsync<IJSInProcessObjectReference>("import", 
            "./scripts.js");
        }
    }

    ...

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            await module.DisposeAsync();
        }
    }
}

Im vorherigen Beispiel wird eine JSDisconnectedException nicht während der Modulentsorgung abgefangen, da es in einer Blazor WebAssembly App keine BlazorSignalR Schaltung gibt, die verloren gehen soll. Weitere Informationen finden Sie unter JavaScript-Interoperabilität von ASP.NET Core-Blazor (JS-Interop).

JavaScript-Speicherort

Laden Sie JavaScript (JS)-Code mithilfe eines der Ansätze, die im Artikel zum JavaScript-Speicherortbeschrieben werden:

• Laden eines Skripts im <head>-Markup (im Allgemeinen nicht empfohlen)
• Laden eines Skripts im <body>-Markup
• Laden eines Skripts aus einer externen JavaScript-Datei (.js), die mit einer Komponente verbunden ist
• Laden eines Skripts aus einer externen JavaScript-Datei (.js)
• Einfügen eines Skripts vor oder nach dem Start von Blazor

Informationen zum Isolieren von Skripts in JS-Modulen finden Sie im Abschnitt zur JavaScript-Isolation in JavaScript-Modulen.

Warnung

Platzieren Sie ein <script>-Tag nur in einer Komponentendatei (.razor), wenn die Komponente garantiert statisches serverseitiges Rendering (static sSR) verwendet, da das <script>-Tag nicht dynamisch aktualisiert werden kann.

JavaScript-Isolierung in JavaScript-Modulen

Blazor aktiviert die JavaScript-Isolation (JS) in JavaScript-Standardmodulen (ECMAScript-Spezifikation). Das Laden von JavaScript-Modulen funktioniert in Blazor genauso wie bei anderen Arten von Web-Apps, und Sie können die Definition von Modulen in Ihrer App anpassen. Eine Anleitung zur Verwendung von JavaScript-Modulen finden Sie in den MDN Web Docs: JavaScript modules.

JS-Isolierung bietet die folgenden Vorteile:

• Importiertes JS verschmutzt nicht mehr den globalen Namespace.
• Consumer einer Bibliothek und Komponenten müssen nicht das zugehörige JS importieren.

Dynamischer Import mit dem import()-Operator wird mit ASP.NET Core und Blazor unterstützt:

if ({CONDITION}) import("/additionalModule.js");

Im vorherigen Beispiel steht der Platzhalter {CONDITION} für eine bedingte Überprüfung, mit der festgestellt wird, ob das Modul geladen werden soll.

Informationen zur Browserkompatibilität finden Sie unter Can I use: JavaScript modules: dynamic import.

In serverseitigen Szenarien können Interopanrufe nicht ausgegeben werden, JS nachdem Blazordie SignalR Verbindung getrennt wurde. Ohne eine Verbindung während der Komponentenbereinigung oder zu jedem anderen Zeitpunkt, an dem keine Verbindung vorhanden ist, schlagen die folgenden Methodenaufrufe fehl und protokollieren eine Meldung, dass die Verbindung als JSDisconnectedException getrennt wurde:

• JS-Interopmethodenaufrufe
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync)
• Dispose/DisposeAsync ruft ein beliebiges IJSObjectReference-Element auf.

Um die Protokollierung JSDisconnectedException zu vermeiden oder benutzerdefinierte Informationen auf serverseitiger Seite Blazorzu protokollieren, erfassen Sie die Ausnahme in einer try-catch Anweisung.

Für das folgende Beispiel für Komponbereinigung gilt:

• Die serverseitige Komponente implementiert IAsyncDisposable.
• module ist ein IJSObjectReference Modul JS .
• JSDisconnectedException wird abgefangen und nicht protokolliert.
• Optional können Sie benutzerdefinierte Informationen in der catch-Anweisung auf beliebiger Protokollebene protokollieren. Im folgenden Beispiel werden keine benutzerdefinierten Informationen protokolliert. Der Code geht davon aus, dass sich der Entwickler nicht darum kümmert, wann oder wo Schaltkreise während der Komponentenentsorgung getrennt werden.

async ValueTask IAsyncDisposable.DisposeAsync()
{
    try
    {
        if (module is not null)
        {
            await module.DisposeAsync();
        }
    }
    catch (JSDisconnectedException)
    {
    }
}

Wenn Sie Ihre eigenen JS Objekte bereinigen oder anderen JS Code auf dem Client ausführen müssen, nachdem ein Schaltkreis in einer serverseitigen Blazor App verloren gegangen ist, verwenden Sie das MutationObserver Muster auf JS dem Client. Mit dem MutationObserver Muster können Sie Code ausführen JS , wenn ein Element aus dem DOM entfernt wird.

Weitere Informationen finden Sie in den folgenden Artikeln:

• ASP.NET Core Blazor JavaScript-Interoperabilität (JS Interoperabilität): Enthält ein Codebeispiel des MutationObserver Musters.
• Behandeln von Fehlern in ASP.NET Core Blazor-Apps: Im Abschnitt JavaScript-Interop wird die Fehlerbehandlung in JS-Interopszenarien erläutert.
• ASP.NET Core Razor-Komponentenlebenszyklus: Im Abschnitt Komponentenbereinigung mit IDisposable und IAsyncDisposable wird beschrieben, wie Bereinigungsmuster in Razor-Komponenten implementiert werden.

Das folgende JS Modul exportiert eine JS Funktion zum Anzeigen einer Browserfensteraufforderung. Platzieren Sie den folgenden JS-Code in einer externen JS-Datei.

wwwroot/scripts.js:

export function showPrompt(message) {
  return prompt(message, 'Type anything here');
}

Fügen Sie das obige JS-Modul als statisches Webobjekt zu einer App oder Klassenbibliothek im wwwroot-Ordner hinzu, und importieren Sie das Modul dann in den .NET-Code, indem Sie InvokeAsync für die IJSRuntime-Instanz aufrufen.

IJSRuntime importiert das Modul als IJSObjectReference, das einen Verweis auf ein JS-Objekt aus .NET-Code darstellt. Verwenden Sie IJSObjectReference, um exportierte JS-Funktionen aus dem Modul aufzurufen.

CallJs6.razor:

@page "/call-js-6"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>Call JS 6</PageTitle>

<h1>Call JS Example 6</h1>

<p>
    <button @onclick="TriggerPrompt">Trigger browser window prompt</button>
</p>

<p>
    @result
</p>

@code {
    private IJSObjectReference? module;
    private string? result;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./scripts.js");
        }
    }

    private async Task TriggerPrompt() => result = await Prompt("Provide text");

    public async ValueTask<string?> Prompt(string message) =>
        module is not null ? 
            await module.InvokeAsync<string>("showPrompt", message) : null;

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

Im vorherigen Beispiel:

• Per Konvention handelt es sich beim import-Bezeichner um einen besonderen Bezeichner, der spezifisch zum Importieren eines JS-Moduls verwendet wird.
• Geben Sie die externe JS-Datei des Moduls mithilfe des stabilen Pfads des statischen Webobjekts an: ./{SCRIPT PATH AND FILE NAME (.js)}. Dabei gilt Folgendes:
  • Das Pfadsegment für das aktuelle Verzeichnis (./) ist erforderlich, damit der korrekte Pfad zu statischen Objekten in der JS-Datei erstellt werden kann.
  • Der Platzhalter {SCRIPT PATH AND FILE NAME (.js)} entspricht dem Pfad und Dateinamen unter wwwroot.
• Dieser gibt die IJSObjectReference für die Garbage Collection in IAsyncDisposable.DisposeAsync zurück.

Das dynamische Importieren eines Moduls erfordert eine Netzwerkanforderung, sodass es nur asynchron durch Aufrufen von InvokeAsync erreicht werden kann.

IJSInProcessObjectReference steht für einen Verweis auf ein JS-Objekt, dessen Funktionen synchron in clientseitigen Komponenten aufgerufen werden können. Weitere Informationen finden Sie im Abschnitt Synchrone JS-Interoperabilität in clientseitigen Komponenten.

Hinweis

Wenn die externe JS-Datei von einer Razor-Klassenbibliothek bereitgestellt wird, geben Sie die JS-Datei des Moduls mithilfe des stabilen Pfads des statischen Webobjekts an: ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

• Das Pfadsegment für das aktuelle Verzeichnis (./) ist erforderlich, damit der korrekte Pfad zu statischen Objekten in der JS-Datei erstellt werden kann.
• Der Platzhalter {PACKAGE ID} ist diePaket-IDder Bibliothek. Die Paket-ID wird standardmäßig auf den Assemblynamen des Projekts festgelegt, wenn <PackageId> nicht in der Projektdatei angegeben ist. Im folgenden Beispiel lautet der Assemblyname der Bibliothek ComponentLibrary, und die Projektdatei der Bibliothek gibt <PackageId> nicht an.
• Der Platzhalter {SCRIPT PATH AND FILE NAME (.js)} entspricht dem Pfad und Dateinamen unter wwwroot. Im folgenden Beispiel wird die externe JS-Datei (script.js) im wwwroot-Ordner der Klassenbibliothek platziert.
• module ist eine private, Nullwerte zulassende IJSObjectReference-Schnittstelle der Komponentenklasse (private IJSObjectReference? module;).

module = await js.InvokeAsync<IJSObjectReference>(
    "import", "./_content/ComponentLibrary/scripts.js");

Weitere Informationen finden Sie unter Nutzen von ASP.NET Core Razor-Komponenten über eine Razor-Klassenbibliothek (RCL).

In der gesamten Blazor-Dokumentation wird in den Beispielen für Moduldateien die Dateierweiterung .js, nicht die neuere Dateierweiterung .mjs (RFC 9239) verwendet. Unsere Dokumentation verwendet weiterhin die Dateierweiterung .js aus denselben Gründen, aus denen die Dokumentation der Mozilla Foundation weiterhin die Dateierweiterung .js verwendet. Weitere Informationen finden Sie unter Aside – .mjs versus .js (Randnotiz – MJS im Vergleich zu JS, MDN-Dokumentation).

Erfassen von Verweisen auf Elemente

Einige JavaScript-Interop-Szenarios (JS) erfordern Verweise auf HTML-Elemente. Beispielsweise erfordert eine Benutzeroberflächenbibliothek möglicherweise einen Elementverweis für die Initialisierung, oder Sie müssen befehlsähnliche APIs für ein Element aufrufen, z. B. click oder play.

Erfassen Sie mithilfe des folgenden Ansatzes Verweise auf HTML-Elemente in einer Komponente:

• Fügen Sie ein @ref-Attribut zum HTML-Element hinzu.
• Definieren Sie ein Feld vom Typ ElementReference, dessen Name mit dem Wert des @ref-Attributs übereinstimmt.

Im folgenden Beispiel wird das Erfassen eines Verweises auf das username <input>-Element veranschaulicht:

<input @ref="username" ... />

@code {
    private ElementReference username;
}

Warnung

Verwenden Sie Elementverweise nur, um die Inhalte eines leeren Elements zu ändern, das nicht mit Blazor interagiert. Dieses Szenario ist nützlich, wenn eine Drittanbieter-API Inhalt für das Element bereitstellt. Da Blazor nicht mit dem Element interagiert, kann kein Konflikt zwischen der Darstellung von Blazor des Elements und dem DOM auftreten.

Im folgenden Beispiel ist es riskant, die Inhalte der unsortierten Liste (ul) mithilfe von MyList über JS-Interop zu ändern, weil Blazor mit dem DOM interagiert, um die Listenelemente (<li>) dieses Elements anhand des Todos-Objekts aufzufüllen:

<ul @ref="MyList">
    @foreach (var item in Todos)
    {
        <li>@item.Text</li>
    }
</ul>

Die Verwendung des MyList-Elementverweises zum bloßen Lesen von DOM-Inhalten oder Auslösen eines Ereignisses wird unterstützt.

Wenn ein JS-Interop-Aufruf die Inhalte des MyList-Elements ändert und Blazor versucht, Diff-Algorithmen auf das Element anzuwenden, stimmen diese nicht mit dem DOM überein. Das Ändern des Inhalts der Liste über JS-Interop mit dem MyList-Elementverweis wird nicht unterstützt.

Weitere Informationen finden Sie unter JavaScript-Interoperabilität von ASP.NET Core-Blazor (JS-Interop).

Eine ElementReference-Struktur wird über einen JS-Interop-Aufruf an den JS-Code übergeben. Der JS-Code empfängt eine HTMLElement-Instanz, die er mit normalen DOM-APIs verwenden kann. Im folgenden Code wird beispielsweise eine .NET-Erweiterungsmethode (TriggerClickEvent) definiert, die das Senden eines Mausklicks an ein Element ermöglicht.

Die JS-Funktion clickElement erstellt ein click-Ereignis an das übergebene HTML-Element (element):

window.interopFunctions = {
  clickElement : function (element) {
    element.click();
  }
}

Verwenden Sie JSRuntimeExtensions.InvokeVoidAsync, um eine JS-Funktion aufzurufen, die keinen Wert zurückgibt. Der folgende Code löst ein clientseitiges click-Ereignis aus, indem die vorherige JS-Funktion mit der erfassten ElementReference-Struktur aufgerufen wird:

@inject IJSRuntime JS

<button @ref="exampleButton">Example Button</button>

<button @onclick="TriggerClick">
    Trigger click event on <code>Example Button</code>
</button>

@code {
    private ElementReference exampleButton;

    public async Task TriggerClick()
    {
        await JS.InvokeVoidAsync(
            "interopFunctions.clickElement", exampleButton);
    }
}

Erstellen Sie eine statische Erweiterungsmethode, die die IJSRuntime-Instanz empfängt, um eine Erweiterungsmethode zu verwenden:

public static async Task TriggerClickEvent(this ElementReference elementRef, 
    IJSRuntime js)
{
    await js.InvokeVoidAsync("interopFunctions.clickElement", elementRef);
}

Die clickElement-Methode wird direkt für das Objekt aufgerufen. Im folgenden Beispiel wird davon ausgegangen, dass die TriggerClickEvent-Methode vom JsInteropClasses-Namespace verfügbar ist:

@inject IJSRuntime JS
@using JsInteropClasses

<button @ref="exampleButton">Example Button</button>

<button @onclick="TriggerClick">
    Trigger click event on <code>Example Button</code>
</button>

@code {
    private ElementReference exampleButton;

    public async Task TriggerClick()
    {
        await exampleButton.TriggerClickEvent(JS);
    }
}

Wichtig

Die exampleButton-Variable wird erst aufgefüllt, nachdem die Komponente gerendert wurde. Wenn eine aufgefüllte ElementReference-Struktur an JS-Code übergeben wird, empfängt der JS-Code einen null-Wert. Sie können Elementverweise bearbeiten, nachdem die Komponente das Rendering abgeschlossen hat, indem Sie die Lebenszyklusmethoden OnAfterRenderAsync oder OnAfterRender verwenden.

Verwenden Sie ValueTask<TResult>, wenn Sie mit generischen Typen arbeiten und einen Wert zurückgeben:

public static ValueTask<T> GenericMethod<T>(
        this ElementReference elementRef, IJSRuntime js) => 
    js.InvokeAsync<T>("{JAVASCRIPT FUNCTION}", elementRef);

Der Platzhalter {JAVASCRIPT FUNCTION} ist der Bezeichner für die JS-Funktion.

GenericMethod wird direkt für das Objekt mit einem Typ aufgerufen. Im folgenden Beispiel wird davon ausgegangen, dass die GenericMethod-Methode vom JsInteropClasses-Namespace verfügbar ist:

@inject IJSRuntime JS
@using JsInteropClasses

<input @ref="username" />

<button @onclick="OnClickMethod">Do something generic</button>

<p>
    returnValue: @returnValue
</p>

@code {
    private ElementReference username;
    private string? returnValue;

    private async Task OnClickMethod()
    {
        returnValue = await username.GenericMethod<string>(JS);
    }
}

Komponentenübergreifende Verweiselemente

Ein ElementReference kann aus folgenden Gründen nicht zwischen Komponenten übermittelt werden:

• Das Vorhandensein der Instanz ist nur nach dem Rendern der Komponente garantiert, das während oder nach der Ausführung der OnAfterRender/OnAfterRenderAsync-Methode einer Komponente erfolgt.
• Ein ElementReference ist ein struct, der nicht als Komponentenparameter übergeben werden kann.

Damit eine übergeordnete Komponente einen Elementverweis anderen Komponenten zur Verfügung stellen kann, kann die übergeordnete Komponente:

• zulassen, dass untergeordnete Komponenten Rückrufe registrieren.
• die registrierten Rückrufe während des OnAfterRender-Ereignisses mit dem übergebenen Elementverweis aufrufen. Dieser Ansatz ermöglicht untergeordneten Komponenten indirekt die Interaktion mit dem Elementverweis des übergeordneten Elements.

<style>
    .red { color: red }
</style>

<script>
  function setElementClass(element, className) {
    var myElement = element;
    myElement.classList.add(className);
  }
</script>

Hinweis

Allgemeine Anleitungen zu JS Standort und unseren Empfehlungen für Produktions-Apps finden Sie unter JavaScript-Speicherort in ASP.NET Core Blazor -Apps.

CallJs7.razor (übergeordnete Komponente):

@page "/call-js-7"

<PageTitle>Call JS 7</PageTitle>

<h1>Call JS Example 7</h1>

<h2 @ref="title">Hello, world!</h2>

Welcome to your new app.

<SurveyPrompt Parent="this" Title="How is Blazor working for you?" />

CallJs7.razor.cs:

using Microsoft.AspNetCore.Components;

namespace BlazorSample.Pages;

public partial class CallJs7 : 
    ComponentBase, IObservable<ElementReference>, IDisposable
{
    private bool disposing;
    private readonly List<IObserver<ElementReference>> subscriptions = [];
    private ElementReference title;

    protected override void OnAfterRender(bool firstRender)
    {
        base.OnAfterRender(firstRender);

        foreach (var subscription in subscriptions)
        {
            subscription.OnNext(title);
        }
    }

    public void Dispose()
    {
        disposing = true;

        foreach (var subscription in subscriptions)
        {
            try
            {
                subscription.OnCompleted();
            }
            catch (Exception)
            {
            }
        }

        subscriptions.Clear();

        // The following prevents derived types that introduce a
        // finalizer from needing to re-implement IDisposable.
        GC.SuppressFinalize(this);
    }

    public IDisposable Subscribe(IObserver<ElementReference> observer)
    {
        if (disposing)
        {
            throw new InvalidOperationException("Parent being disposed");
        }

        subscriptions.Add(observer);

        return new Subscription(observer, this);
    }

    private class Subscription(IObserver<ElementReference> observer,
        CallJs7 self) : IDisposable
    {
        public IObserver<ElementReference> Observer { get; } = observer;
        public CallJs7 Self { get; } = self;

        public void Dispose() => Self.subscriptions.Remove(Observer);
    }
}

Im vorherigen Beispiel ist BlazorSample der Namespace der App. Wenn Sie den Code lokal testen möchten, müssen Sie den Namespace ändern.

SurveyPrompt.razor (untergeordnete Komponente):

<div class="alert alert-secondary mt-4">
    <span class="oi oi-pencil me-2" aria-hidden="true"></span>
    <strong>@Title</strong>

    <span class="text-nowrap">
        Please take our
        <a target="_blank" class="font-weight-bold link-dark" href="https://go.microsoft.com/fwlink/?linkid=2186158">brief survey</a>
    </span>
    and tell us what you think.
</div>

@code {
    // Demonstrates how a parent component can supply parameters
    [Parameter]
    public string? Title { get; set; }
}

SurveyPrompt.razor.cs:

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorSample.Components;

public partial class SurveyPrompt : 
    ComponentBase, IObserver<ElementReference>, IDisposable
{
    private IDisposable? subscription = null;

    [Parameter]
    public IObservable<ElementReference>? Parent { get; set; }

    [Inject]
    public IJSRuntime? JS {get; set;}

    protected override void OnParametersSet()
    {
        base.OnParametersSet();

        subscription?.Dispose();
        subscription = Parent?.Subscribe(this);
    }

    public void OnCompleted() => subscription = null;

    public void OnError(Exception error) => subscription = null;

    public void OnNext(ElementReference value) =>
        _ = (JS?.InvokeAsync<object>("setElementClass", [value, "red"]));

    public void Dispose()
    {
        subscription?.Dispose();

        // The following prevents derived types that introduce a
        // finalizer from needing to re-implement IDisposable.
        GC.SuppressFinalize(this);
    }
}

Im vorherigen Beispiel ist BlazorSample der Namespace der App mit gemeinsamen Komponenten im Ordner Shared. Wenn Sie den Code lokal testen möchten, müssen Sie den Namespace ändern.

Festschreiben von JavaScript-Interop-Aufrufen

Dieser Abschnitt gilt nur für interaktive Serverkomponenten. Aber auch clientseitige Komponenten können JS-Interop-Timeouts festlegen, wenn dies aufgrund der Umstände angebracht ist.

In serverseitigen Apps mit Serverinteraktivität ist die JS-Interoperabilität (JavaScript) möglicherweise aufgrund von Netzwerkfehlern nicht erfolgreich und sollte daher als unzuverlässig betrachtet werden. Blazor-Anwendungen verwenden ein einminütiges Timeout für JS-Interop-Aufrufe. Wenn eine App ein engeres Timeout tolerieren kann, legen Sie das Timeout mit einem der folgenden Ansätze fest:

Legen Sie mit CircuitOptions.JSInteropDefaultCallTimeout ein globales Timeout in der Program.cs-Datei fest:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents(options => 
        options.JSInteropDefaultCallTimeout = {TIMEOUT});

Der Platzhalter {TIMEOUT} ist ein TimeSpan (z. B. TimeSpan.FromSeconds(80)).

Legen Sie im Komponentencode ein Timeout pro Aufruf fest. Das festgelegte Timeout überschreibt das globale Timeout, das von JSInteropDefaultCallTimeout festgelegt wird:

var result = await JS.InvokeAsync<string>("{ID}", {TIMEOUT}, new[] { "Arg1" });

Im vorherigen Beispiel:

• Der Platzhalter {TIMEOUT} ist ein TimeSpan (z. B. TimeSpan.FromSeconds(80)).
• Der Platzhalter {ID} ist der Bezeichner für die aufzurufende Funktion. Der Wert someScope.someFunction ruft beispielsweise die Funktion window.someScope.someFunction auf.

JS-Interop-Fehler sind zwar häufig auf Netzwerkfehler mit serverseitigen Komponenten zurückzuführen, es können jedoch Timeouts pro Aufruf für JS-Interop-Aufrufe für clientseitige Komponenten festgelegt werden. Obwohl keine Blazor-SignalR Schaltkreise für eine clientseitige Komponente vorhanden sind, JS können Interoperabilitätsaufrufe aus anderen Gründen fehlschlagen, die angewendet werden.

Weitere Informationen zur Ressourcenerschöpfung finden Sie unter Anleitung zur Bedrohungsabwehr für das interaktive serverseitige Rendering von ASP.NET Core Blazor.

Vermeiden von Objektzirkelbezügen

Objekte, die Zirkelbezüge enthalten, können auf dem Client für folgende Vorgänge nicht serialisiert werden:

• .NET-Methodenaufrufe.
• JavaScript-Methodenaufrufe von C#, wenn der Rückgabetyp Zirkelbezüge enthält.

JavaScript-Bibliotheken zum Rendern der Benutzeroberfläche

Manchmal möchten Sie vielleicht JavaScript-Bibliotheken (JS) verwenden, die sichtbare Benutzeroberflächenelemente innerhalb des Browser-DOM erstellen. Auf den ersten Blick scheint dies schwierig zu sein, da das Vergleichssystem von Blazor darauf beruht, die Kontrolle über die Struktur von DOM-Elementen zu haben. Außerdem treten Fehler auf, wenn externer Code die DOM-Struktur bearbeitet, was den Mechanismus für die Diff-Anwendung unmöglich macht. Dabei handelt es sich um keine Blazor-spezifische Einschränkung. Die gleiche Herausforderung stellt sich bei jedem anderen Diff-basierten Benutzeroberflächenframework.

Glücklicherweise ist es einfach, extern erstellte Benutzeroberflächenelemente innerhalb der Oberfläche einer Razor-Komponente zuverlässig einzubetten. Die hierfür empfohlene Methode besteht darin, den Code der Komponente (.razor-Datei) ein leeres Element erzeugen zu lassen. Im Vergleichssystem von Blazor ist das Element immer leer, der Renderer durchläuft das Element also nicht rekursiv, sondern berücksichtigt die Inhalte gar nicht. Dies führt dazu, dass das Auffüllen des Elements mit zufälligem extern verwalteten Inhalt sicher ist.

Das folgende Beispiel veranschaulicht das Konzept. Interagieren Sie mithilfe von JS außerhalb von Blazor mit unmanagedElement, wenn firstRender in der if-Anweisung den Wert true aufweist. Rufen Sie beispielsweise eine externe JS-Bibliothek auf, um das Element aufzufüllen. Blazor ignoriert die Inhalte des Elements, bis die Komponente entfernt wurde. Wenn die Komponente entfernt wird, wird die gesamte DOM-Unterstruktur der Komponente ebenfalls entfernt.

<h1>Hello! This is a Razor component rendered at @DateTime.Now</h1>

<div @ref="unmanagedElement"></div>

@code {
    private ElementReference unmanagedElement;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            ...
        }
    }
}

Betrachten Sie das folgende Beispiel, in dem eine interaktive Karte mithilfe der Open-Source-Mapbox-APIs gerendert wird.

Das folgende JS-Modul wird in der App platziert oder über eine Razor-Klassenbibliothek zur Verfügung gestellt.

Hinweis

Rufen Sie zum Erstellen der Mapbox-Karte ein Zugriffstoken von der Mapbox-Anmeldung ab, und geben Sie dieses an der Stelle an, an der sich im folgenden Code {ACCESS TOKEN} befindet.

wwwroot/mapComponent.js:

import 'https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.js';

mapboxgl.accessToken = '{ACCESS TOKEN}';

export function addMapToElement(element) {
  return new mapboxgl.Map({
    container: element,
    style: 'mapbox://styles/mapbox/streets-v11',
    center: [-74.5, 40],
    zoom: 9
  });
}

export function setMapCenter(map, latitude, longitude) {
  map.setCenter([longitude, latitude]);
}

Fügen Sie das folgende Formatvorlagentag zur HTML-Hostseite hinzu, um die korrekte Formatierung zu erzielen.

Fügen Sie das folgende Element <link> zum Markup des Elements <head> hinzu (Speicherort des <head>-Inhalts):

<link href="https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" 
    rel="stylesheet" />

CallJs8.razor:

@page "/call-js-8"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>Call JS 8</PageTitle>

<HeadContent>
    <link href="https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" 
        rel="stylesheet" />
</HeadContent>

<h1>Call JS Example 8</h1>

<div @ref="mapElement" style='width:400px;height:300px'></div>

<button @onclick="() => ShowAsync(51.454514, -2.587910)">Show Bristol, UK</button>
<button @onclick="() => ShowAsync(35.6762, 139.6503)">Show Tokyo, Japan</button>

@code
{
    private ElementReference mapElement;
    private IJSObjectReference? mapModule;
    private IJSObjectReference? mapInstance;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            mapModule = await JS.InvokeAsync<IJSObjectReference>(
                "import", "./mapComponent.js");
            mapInstance = await mapModule.InvokeAsync<IJSObjectReference>(
                "addMapToElement", mapElement);
        }
    }

    private async Task ShowAsync(double latitude, double longitude)
    {
        if (mapModule is not null && mapInstance is not null)
        {
            await mapModule.InvokeVoidAsync("setMapCenter", mapInstance, 
                latitude, longitude);
        }
    }

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (mapInstance is not null)
        {
            try
            {
                await mapInstance.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }

        if (mapModule is not null)
        {
            try
            {
                await mapModule.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

Im obigen Beispiel wird eine interaktive Kartenbenutzeroberfläche erzeugt. Der Benutzer verfügt über folgende Möglichkeiten:

• Ziehen der Karte zum Scrollen oder Zoomen
• Klicken von Schaltflächen zum Springen zu vordefinierten Standorten

Im vorherigen Beispiel:

• Für Blazor gilt, dass <div> mit @ref="mapElement" leer bleibt. Das mapbox-gl.js-Skript kann das Element sicher auffüllen und dessen Inhalte ändern. Sie können diese Vorgehensweise mit jeder beliebigen JS-Bibliothek verwenden, die eine Benutzeroberfläche rendert. Sie können Komponenten eines JS-SPA-Frameworks eines Drittanbieters in Razor-Komponenten einbetten, solange diese nicht versuchen, andere Teile der Seite zu ändern. Es ist nicht sicher, wenn externer JS-Code Elemente ändert, die Blazor nicht als leer betrachtet.
• Bei diesem Ansatz sind die Regeln zu beachten, nach denen Blazor DOM-Elemente beibehält oder vernichtet. Die Komponente verarbeitet Schaltflächen-Klickereignisse auf sichere Weise und aktualisiert die vorhandene Karteninstanz, weil DOM-Elemente standardmäßig beibehalten werden, wenn dies möglich ist. Wenn Sie eine Liste von Kartenelementen innerhalb einer @foreach-Schleife rendern, sollten Sie @key verwenden, um für die Beibehaltung der Komponenteninstanzen zu sorgen. Andernfalls könnten Änderungen der Listendaten dazu führen, dass Komponenteninstanzen den Status vorheriger Instanzen auf nicht gewünschte Weise beibehalten. Weitere Informationen finden Sie unter Verwenden des @key-Anweisungsattributs, um die Beziehung zwischen Elementen, Komponenten und Modellobjekten beizubehalten.
• Das Beispiel verkapselt JS-Logik und -Abhängigkeiten in einem JavaScript-Modul und lädt das Modul dynamisch unter Verwendung des import-Bezeichners. Weitere Informationen finden Sie unter JavaScript-Isolation in JavaScript-Modulen.

Bytearrayunterstützung

Blazor unterstützt optimiertes Bytearray-JavaScript (JS)-Interop, mit dem sich das Codieren/Decodieren von Bytearrays in Base64 vermeiden lässt. Im folgenden Beispiel wird JS-Interop verwendet, um ein Bytearray an JavaScript zu übergeben.

Stellen Sie eine receiveByteArrayJS-Funktion bereit. Die Funktion wird mit InvokeVoidAsync aufgerufen und gibt keinen Wert zurück:

<script>
  window.receiveByteArray = (bytes) => {
    let utf8decoder = new TextDecoder();
    let str = utf8decoder.decode(bytes);
    return str;
  };
</script>

Hinweis

Allgemeine Anleitungen zu JS Standort und unseren Empfehlungen für Produktions-Apps finden Sie unter JavaScript-Speicherort in ASP.NET Core Blazor -Apps.

CallJs9.razor:

@page "/call-js-9"
@inject IJSRuntime JS

<h1>Call JS Example 9</h1>

<p>
    <button @onclick="SendByteArray">Send Bytes</button>
</p>

<p>
    @result
</p>

<p>
    Quote &copy;2005 <a href="https://www.uphe.com">Universal Pictures</a>:
    <a href="https://www.uphe.com/movies/serenity-2005">Serenity</a><br>
    <a href="https://www.imdb.com/name/nm0821612/">Jewel Staite on IMDB</a>
</p>

@code {
    private string? result;

    private async Task SendByteArray()
    {
        var bytes = new byte[] { 0x45, 0x76, 0x65, 0x72, 0x79, 0x74, 0x68, 0x69,
            0x6e, 0x67, 0x27, 0x73, 0x20, 0x73, 0x68, 0x69, 0x6e, 0x79, 0x2c,
            0x20, 0x43, 0x61, 0x70, 0x74, 0x69, 0x61, 0x6e, 0x2e, 0x20, 0x4e,
            0x6f, 0x74, 0x20, 0x74, 0x6f, 0x20, 0x66, 0x72, 0x65, 0x74, 0x2e };

        result = await JS.InvokeAsync<string>("receiveByteArray", bytes);
    }
}

Streamen von .NET zu JavaScript

Blazor unterstützt das direkte Streamen von Daten von .NET an JavaScript (JS). Streams werden mithilfe von DotNetStreamReference erstellt.

DotNetStreamReference stellt einen .NET-Stream dar und verwendet die folgenden Parameter:

• stream: der an JS gesendete Stream
• leaveOpen: Legt fest, ob der Stream nach der Übertragung geöffnet bleibt. Wenn kein Wert angegeben wird, wird leaveOpen standardmäßig auf false festgelegt.

Verwenden Sie in JS einen Arraypuffer oder einen lesbaren Stream, um die Daten zu empfangen:

• Unter Verwendung von ArrayBuffer:

  async function streamToJavaScript(streamRef) {
    const data = await streamRef.arrayBuffer();
  }
  

• Unter Verwendung von ReadableStream:

  async function streamToJavaScript(streamRef) {
    const stream = await streamRef.stream();
  }
  

In C#-Code:

var streamRef = new DotNetStreamReference(stream: {STREAM}, leaveOpen: false);
await JS.InvokeVoidAsync("streamToJavaScript", streamRef);

Im vorherigen Beispiel:

• Der Platzhalter {STREAM} stellt den an JS gesendeten Stream dar.
• JS ist eine eingefügte IJSRuntime-Instanz.

Das Löschen einer DotNetStreamReference-Instanz ist in der Regel unnötig. Wenn leaveOpen auf den Standardwert false festgelegt ist, wird der zugrunde liegende Stream nach der Übertragung an JS automatisch gelöscht.

Wenn leaveOpen gleich true ist, wird durch das Verwerfen von DotNetStreamReference der zugrunde liegende Stream nicht verworfen. Der App-Code bestimmt, wann der zugrunde liegende Stream verworfen werden soll. Berücksichtigen Sie bei der Entscheidung, wie der zugrunde liegende Stream verworfen werden soll, Folgendes:

• Das Verwerfen von Stream während der Übertragung an JS wird als Anwendungsfehler betrachtet und kann zu einem Ausnahmefehler führen.
• Die Stream-Übertragung beginnt, sobald DotNetStreamReference als Argument an einen JS-Interopaufruf übergeben wird, unabhängig davon, ob der Stream tatsächlich in JS-Logik verwendet wird.

Angesichts dieser Merkmale wird empfohlen, den zugrunde liegenden Stream erst zu entfernen, nachdem er von JS vollständig verbraucht wurde (die von arrayBuffer oder stream zurückgegebene Zusage). Es folgt, dass DotNetStreamReference nur an JS übergeben werden sollte, wenn sie bedingungslos von JS-Logik genutzt werden soll.

Unter Aufrufen von .NET-Methoden über JavaScript-Funktionen in Blazor in ASP.NET Core wird der umgekehrte Vorgang behandelt, nämlich das Streamen aus JavaScript in .NET.

Unter Blazor-Dateidownloads in ASP.NET Core wird das Herunterladen einer Datei in Blazor behandelt.

Abfangen von JavaScript-Ausnahmen

Zum Abfangen von JS-Ausnahmen schließen Sie JS-Interop in einen try-catch-Block ein, und fangen Sie eine JSException ab.

Im folgenden Beispiel ist die JS-Funktion nonFunction nicht vorhanden. Wenn die Funktion nicht gefunden wird, wird die JSException mit einer Message abgefangen, die den folgenden Fehler angibt:

Could not find 'nonFunction' ('nonFunction' was undefined).

CallJs11.razor:

@page "/call-js-11"
@inject IJSRuntime JS

<PageTitle>Call JS 11</PageTitle>

<h1>Call JS Example 11</h1>

<p>
    <button @onclick="CatchUndefinedJSFunction">Catch Exception</button>
</p>

<p>
    @result
</p>

<p>
    @errorMessage
</p>

@code {
    private string? errorMessage;
    private string? result;

    private async Task CatchUndefinedJSFunction()
    {
        try
        {
            result = await JS.InvokeAsync<string>("nonFunction");
        }
        catch (JSException e)
        {
            errorMessage = $"Error Message: {e.Message}";
        }
    }
}

Abbrechen einer länger laufenden JavaScript-Funktion

Verwenden Sie einen JSAbortController mit einer CancellationTokenSource in der Komponente, um eine JavaScript-Funktion mit langer Ausführungszeit aus C#-Code abzubrechen.

Die folgende JSHelpers-Klasse enthält eine simulierte Funktion mit langer Ausführungszeit (longRunningFn), die kontinuierlich zählt, bis AbortController.signal angibt, dass AbortController.abort aufgerufen wurde. Die sleep-Funktion dient zu Demonstrationszwecken, um die langsame Ausführung der Funktion mit langer Ausführungszeit zu simulieren, und wäre im Produktionscode nicht vorhanden. Wenn eine Komponente stopFn aufruft, wird longRunningFn signalisiert, den Vorgang über die bedingte while-Schleifenüberprüfung für AbortSignal.aborted abzubrechen.

<script>
  class Helpers {
    static #controller = new AbortController();

    static async #sleep(ms) {
      return new Promise(resolve => setTimeout(resolve, ms));
    }

    static async longRunningFn() {
      var i = 0;
      while (!this.#controller.signal.aborted) {
        i++;
        console.log(`longRunningFn: ${i}`);
        await this.#sleep(1000);
      }
    }

    static stopFn() {
      this.#controller.abort();
      console.log('longRunningFn aborted!');
    }
  }

  window.Helpers = Helpers;
</script>

Hinweis

Allgemeine Anleitungen zu JS Standort und unseren Empfehlungen für Produktions-Apps finden Sie unter JavaScript-Speicherort in ASP.NET Core Blazor -Apps.

Die folgende -Komponente:

• Ruft bei Auswahl der Schaltfläche Start Task die JS-Funktion longRunningFn auf. Eine CancellationTokenSource wird verwendet, um die Ausführung der Funktion mit langer Ausführungsdauer zu verwalten. CancellationToken.Register legt einen JS-Interop-Aufrufdelegaten fest, um die JS-Funktion stopFn auszuführen, wenn CancellationTokenSource.Token abgebrochen wird.
• Wenn die Schaltfläche Cancel Task ausgewählt ist, wird CancellationTokenSource.Token mit einem Aufruf von Cancel abgebrochen.
• CancellationTokenSource wird in der Dispose-Methode verworfen.

CallJs12.razor:

@page "/call-js-12"
@inject IJSRuntime JS

<h1>Cancel long-running JS interop</h1>

<p>
    <button @onclick="StartTask">Start Task</button>
    <button @onclick="CancelTask">Cancel Task</button>
</p>

@code {
    private CancellationTokenSource? cts;

    private async Task StartTask()
    {
        cts = new CancellationTokenSource();
        cts.Token.Register(() => JS.InvokeVoidAsync("Helpers.stopFn"));

        await JS.InvokeVoidAsync("Helpers.longRunningFn");
    }

    private void CancelTask()
    {
        cts?.Cancel();
    }

    public void Dispose()
    {
        cts?.Cancel();
        cts?.Dispose();
    }
}

Die Konsole mit den Entwicklertools eines Browsers gibt die Ausführung der JS-Funktion mit langer Ausführungsdauer an, nachdem die Schaltfläche Start Task ausgewählt und die Funktion abgebrochen wurde, nachdem die Schaltfläche Cancel Task ausgewählt wurde:

longRunningFn: 1
longRunningFn: 2
longRunningFn: 3
longRunningFn aborted!

JavaScript-Interoperabilität mit [JSImport]/[JSExport]

Dieser Abschnitt gilt für clientseitige Komponenten.

Als Alternative zur Interaktion mit JavaScript (JS) in clientseitigen Komponenten, die den JS-Interop-Mechanismus von Blazor basierend auf der IJSRuntime-Schnittstelle verwenden, ist auch eine JS[JSImport]/[JSExport]-Interop-API für Apps verfügbar, die auf .NET 7 oder höher ausgerichtet sind.

Weitere Informationen finden Sie unter JavaScript-Interoperabilität durch JSImport/JSExport mit ASP.NET Core-Blazor.

JavaScript-Interop-Aufrufe mit rückgängig gemachtem Marshallen

Dieser Abschnitt gilt für clientseitige Komponenten.

Interop-Aufrufe ohne Marshalling mit der Schnittstelle IJSUnmarshalledRuntime sind veraltet und sollten durch JavaScript-Interop-Aufrufe [JSImport]/[JSExport] ersetzt werden.

Weitere Informationen finden Sie unter JavaScript-Interoperabilität durch JSImport/JSExport mit ASP.NET Core-Blazor.

Löschen von Objektverweisen bei JavaScript-Interoperabilität

Alle Beispiele im Artikel zur JavaScript-Interoperabilität (JS) veranschaulichen typische Muster zum Löschen von Objekten:

• Wenn Sie JS aus .NET aufrufen, wie in diesem Artikel beschrieben, löschen Sie alle erstellten IJSObjectReference/IJSInProcessObjectReference/JSObjectReference-Elemente entweder aus .NET oder aus JS, um JS-Arbeitsspeicherverluste zu vermeiden.

• Wenn Sie .NET aus JS aufrufen, wie unter Aufrufen von .NET-Methoden in JavaScript-Funktionen in ASP.NET Core Blazor beschrieben, löschen Sie alle erstellten DotNetObjectReference-Elemente entweder aus .NET oder aus JS, um .NET-Arbeitsspeicherverluste zu vermeiden.

Objektverweise bei JS-Interoperabilität werden als Zuordnung implementiert, die durch einen Bezeichner auf der Seite des JS-Interoperabilitätsaufrufs definiert ist, der den Verweis erstellt. Wenn die Objektlöschung von .NET oder JS aus initiiert wird, entfernt Blazor den Eintrag aus der Zuordnung, und das Objekt kann durch die Garbage Collection gelöscht werden, sofern kein anderer starker Verweis auf das Objekt vorhanden ist.

Sie sollten immer mindestens die auf .NET-Seite erstellten Objekte löschen, um Verluste im von .NET verwalteten Arbeitsspeicher zu vermeiden.

DOM-Bereinigungsvorgänge während der Beseitigung von Komponenten

Weitere Informationen finden Sie unter JavaScript-Interoperabilität von Blazor in ASP.NET Core (JS-Interoperabilität).

JavaScript-Interopaufrufe ohne Verbindung

Weitere Informationen finden Sie unter JavaScript-Interoperabilität von Blazor in ASP.NET Core (JS-Interoperabilität).

Zusätzliche Ressourcen

• Aufrufen von .NET-Methoden über JavaScript-Funktionen in Blazor in ASP.NET Core
• InteropComponent.razor-Beispiel (GitHub-Repository dotnet/AspNetCore, main-Branch): Der main-Branch entspricht der aktuellen Entwicklung der Produkteinheit für das nächste Release von ASP.NET Core. Zum Auswählen der Verzweigung für eine andere Version (z. B. wenn der Platzhalter die {VERSION} Releaseversion ist), verwenden Sie die Dropdownliste "Switch Branches" oder "Tags", release/{VERSION}um die Verzweigung auszuwählen. Verwenden Sie für einen Zweig, der nicht mehr vorhanden ist, die Registerkarte "Kategorien " zum Suchen der API (z. B v7.0.0. ).
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)
• Behandeln von Fehlern in ASP.NET Core Blazor-Apps (Abschnitt JavaScript-Interop)
• Bedrohungsminderung: Über .NET aufgerufene JavaScript-Funktionen