Volání javascriptových funkcí z metod .NET v ASP.NET Core Blazor

Tento článek vysvětluje, jak vyvolat funkce JavaScriptu (JS) z .NET.

Informace o tom, jak volat metody .NET z JS, naleznete v tématu Volání metod .NET z funkcí JavaScriptu v ASP.NET Core Blazor.

Vyvolání JS funkcí

IJSRuntime je registrován v Blazor rámci. Chcete-li volat JS z .NET, vložte IJSRuntime abstrakci a zavolejte jednu z následujících metod:

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

Pro předchozí metody .NET, které volají JS funkce:

• Identifikátor funkce (String) je relativní k globálnímu oboru (window). K volání window.someScope.someFunctionje identifikátor someScope.someFunction. Před zavolání funkce není potřeba registrovat.
• Předejte funkci libovolný počet serializovatelných argumentů Object[] JS JSON.
• TokenCancellationToken zrušení () rozšíří oznámení, že operace by měly být zrušeny.
• TimeSpan představuje časový limit pro JS operaci.
• Návratový TValue typ musí být také serializovatelný ve formátu JSON. TValue by se měl shodovat s typem .NET, který se nejlépe mapuje na vrácený typ JSON.
• Pro metody se vrátí InvokeAsync hodnota AJS Promise. InvokeAsync rozbalí Promise a vrátí hodnotu, kterou Promiseočekává .

U Blazor aplikací s povoleným předrenderováním, což je výchozí nastavení pro aplikace na straně serveru, není při předkreslování možné volání JS . Další informace najdete v části Prerendering .

Následující příklad je založen na dekodéru založeném JSna TextDecoder. Příklad ukazuje, jak vyvolat JS funkci z metody jazyka C#, která přesměruje požadavek z kódu vývojáře na existující JS rozhraní API. Funkce JS přijímá bajtové pole z metody C#, dekóduje pole a vrátí text do komponenty pro zobrazení.

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

Poznámka:

Obecné pokyny k JS umístění a doporučení pro produkční aplikace najdete v tématu o umístění JavaScriptu v aplikacích ASP.NET CoreBlazor.

Následující komponenta:

• convertArrayJS Vyvolá funkci InvokeAsync při výběru tlačítka (Convert Array).
• JS Po zavolání funkce se předané pole převede na řetězec. Řetězec se vrátí do komponenty pro zobrazení (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 omezené na gesta uživatelů

Tato část platí pro součásti na straně serveru.

Některá rozhraní API JavaScriptu (JS) prohlížeče se dají spouštět jenom v kontextu uživatelského gesta, jako je použití Fullscreen API (dokumentace k MDN). Tato rozhraní API se nedají volat prostřednictvím JS mechanismu vzájemné spolupráce v komponentách na straně serveru, protože zpracování událostí uživatelského rozhraní se provádí asynchronně a obecně už není v kontextu gesta uživatele. Aplikace musí zpracovat událost uživatelského rozhraní kompletně v JavaScriptu, takže místo atributu direktivy @onclick použijte onclick Blazor.

Vyvolání javascriptových funkcí bez čtení vrácené hodnoty (InvokeVoidAsync)

Použít InvokeVoidAsync , když:

• .NET se nevyžaduje ke čtení výsledku volání JavaScriptu (JS).
• JS funkce vrací void(0)/void 0 nebo nedefinované.

displayTickerAlert1JS Zadejte funkci. Funkce se volá a InvokeVoidAsync nevrací hodnotu:

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

Poznámka:

Obecné pokyny k JS umístění a doporučení pro produkční aplikace najdete v tématu o umístění JavaScriptu v aplikacích ASP.NET CoreBlazor.

Příklad komponenty (.razor) (InvokeVoidAsync)

TickerChanged volá metodu handleTickerChanged1 v následující komponentě.

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

Příklad třídy (.cs) (InvokeVoidAsync)

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 volá metodu handleTickerChanged1 v následující komponentě.

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

Vyvolání funkcí JavaScriptu a načtení vrácené hodnoty (InvokeAsync)

Použijte InvokeAsync , když má .NET přečíst výsledek volání JavaScriptu (JS).

displayTickerAlert2JS Zadejte funkci. Následující příklad vrátí řetězec pro zobrazení volajícím:

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

Poznámka:

Obecné pokyny k JS umístění a doporučení pro produkční aplikace najdete v tématu o umístění JavaScriptu v aplikacích ASP.NET CoreBlazor.

Příklad komponenty (.razor) (InvokeAsync)

TickerChanged volá metodu handleTickerChanged2 a zobrazí vrácený řetězec v následující komponentě.

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

Příklad třídy (.cs) (InvokeAsync)

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 volá metodu handleTickerChanged2 a zobrazí vrácený řetězec v následující komponentě.

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

Scénáře generování dynamického obsahu

Pro generování dynamického [Inject] obsahu pomocí BuildRenderTree použijte atribut:

[Inject]
IJSRuntime JS { get; set; }

Předkreslování

Tato část se týká aplikací na straně serveru, které prerenderovat Razor komponenty. Prerendering je pokrytý komponentami Prerender ASP.NET CoreRazor.

Poznámka:

Interní navigace pro interaktivní směrování Blazor Web Appnezahrnuje vyžádání nového obsahu stránky ze serveru. Proto u interních požadavků na stránku nedojde k předběžnému provedení. Pokud aplikace přijme interaktivní směrování, proveďte opětovné načtení celé stránky pro příklady komponent, které demonstrují chování předběžného formátování. Další informace naleznete v tématu Prerender ASP.NET Základní Razor komponenty.

Během předřazení není volání do JavaScriptu (JS) možné. Následující příklad ukazuje, jak používat JS interoperabilitu jako součást inicializační logiky komponenty způsobem, který je kompatibilní s předdeenderingem.

scrollElementIntoView Následující funkce:

• Posune se k předaným elementu s příponou scrollIntoView.
• Vrátí hodnotu vlastnosti elementu top getBoundingClientRect z metody.

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

Kde IJSRuntime.InvokeAsync volá JS funkci v kódu komponenty, je použita pouze v OnAfterRenderAsync a ne v žádné dřívější metodě životního cyklu, ElementReference protože neexistuje žádný prvek HTML DOM, dokud se komponenta nevykreslí.

StateHasChanged(referenční zdroj) je volána k vytvoření fronty součásti s novým stavem získaným z JS volání zprostředkovatele komunikace (další informace najdete v tématu o vykreslování komponent ASP.NET CoreRazor). Nekonečná smyčka se nevytvořila, protože StateHasChanged je volána pouze tehdy, když scrollPosition je null.

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

Předchozí příklad znečišťuje klienta globální funkcí. Lepší přístup v produkčních aplikacích najdete v tématu Izolace JavaScriptu v modulech JavaScriptu.

Synchronní JS spolupráce v komponentách na straně klienta

Tato část se týká pouze komponent na straně klienta.

JS interop volání jsou asynchronní, bez ohledu na to, zda je volaný kód synchronní nebo asynchronní. Volání jsou asynchronní, aby se zajistilo, že komponenty jsou kompatibilní napříč režimy vykreslování na straně serveru a na straně klienta. Na serveru musí být všechna JS volání zprostředkovatele komunikace asynchronní, protože se odesílají přes síťové připojení.

Pokud víte, že vaše komponenta běží jenom na WebAssembly, můžete se rozhodnout provádět synchronní JS volání interopu. To má o něco menší režii než provádění asynchronních volání a může vést k menšímu počtu cyklů vykreslování, protože při čekání na výsledky neexistuje žádný přechodný stav.

Pokud chcete v komponentě na straně klienta provést synchronní volání z .NET do JavaScriptu, přetypujte IJSRuntime hoJS, aby IJSInProcessRuntime bylo volání zprostředkovatele komunikace:

@inject IJSRuntime JS

...

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

Při práci s komponentami IJSObjectReference na straně klienta ASP.NET Core 5.0 nebo novějším můžete místo toho použít IJSInProcessObjectReference synchronně. IJSInProcessObjectReference implementuje IAsyncDisposable/IDisposable a měla by být uvolněna pro uvolňování paměti, aby se zabránilo nevracení paměti, jak ukazuje následující příklad:

@inject IJSRuntime JS
@implements IDisposable

...

@code {
    ...
    private IJSInProcessObjectReference? module;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            var jsInProcess = (IJSInProcessRuntime)JS;
            module = await jsInProcess.Invoke<IJSInProcessObjectReference>("import", 
                "./scripts.js");
            var value = module.Invoke<string>("javascriptFunctionIdentifier");
        }
    }

    ...

    void IDisposable.Dispose()
    {
        if (module is not null)
        {
            await module.Dispose();
        }
    }
}

V předchozím příkladu JSDisconnectedException není při vyřazení modulu zachycený, protože v Blazor WebAssembly aplikaci není žádný Blazorokruh,SignalR který by se ztratil. Další informace najdete v tématu ASP.NET Interoperabilita Core Blazor JavaScriptu (JSinteroperabilita).

Umístění JavaScriptu

Načtěte kód JavaScriptu (JS) pomocí některého z přístupů popsaných v článku o umístění JavaScriptu:

• Načtení skriptu ve značce <head> (obecně se nedoporučuje)
• Načtení skriptu ve značce <body>
• Načtení skriptu z externího souboru JavaScriptu (.js) umístěného stejně jako komponenta
• Načtení skriptu z externího souboru JavaScriptu (.js)
• Vložení skriptu před nebo po Blazor spuštění

Informace o izolování skriptů v JS modulech najdete v části Věnované izolaci JavaScriptu v modulech JavaScriptu.

Upozorňující

Značku umístěte <script> do souboru komponenty (.razor) pouze v případě, že je zaručeno přijetí statického vykreslování na straně serveru (statické SSR), protože <script> značku nelze dynamicky aktualizovat.

Izolace JavaScriptu v modulech JavaScriptu

Blazor umožňuje izolaci JavaScriptu (JS) ve standardních modulech JavaScriptu (specifikace ECMAScript). Načítání modulu JavaScriptu funguje stejně jako Blazor u jiných typů webových aplikací a můžete si přizpůsobit, jak se moduly definují ve vaší aplikaci. Průvodce používáním modulů JavaScriptu najdete v tématu MDN Web Docs: Moduly JavaScriptu.

Izolace JS poskytuje následující výhody:

• Import JS už znečišťuje globální obor názvů.
• Uživatelé knihovny a komponent už nemusí importovat související JS.

Dynamický import s operátorem import() se podporuje s ASP.NET Core aBlazor:

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

V předchozím příkladu {CONDITION} zástupný symbol představuje podmíněnou kontrolu, která určuje, jestli se má modul načíst.

Informace o kompatibilitě prohlížeče najdete v tématu Je možné použít: moduly JavaScriptu: dynamický import.

Ve scénářích JS na straně serveru není možné po odpojení okruhu vydat BlazorSignalR volání zprostředkovatele komunikace. Bez okruhu během odstraňování součástí nebo v jakémkoli jiném okamžiku, kdy okruh neexistuje, následující volání metody selžou a zapíše zprávu, že okruh je odpojen jako JSDisconnectedException:

• JS volání metod vzájemné spolupráce
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync)
• Dispose/DisposeAsync zavolá na libovolnou IJSObjectReference.

Aby se zabránilo protokolování JSDisconnectedException nebo protokolování vlastních informací na straně Blazorserveru, zachyťte výjimku v try-catch příkazu.

Příklad vyřazení z následujících součástí:

• Komponenta na straně serveru implementuje IAsyncDisposable.
• module je pro IJSObjectReference JS modul.
• JSDisconnectedException je zachycen a nezaprotokolován.
• Volitelně můžete vlastní informace v catch příkazu protokolovat na libovolné úrovni protokolu, kterou dáváte přednost. Následující příklad nezapíše vlastní informace. Kód předpokládá, že vývojář nezajímá, kdy nebo kde jsou okruhy odpojeny během vyřazení komponent.

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

Pokud po ztrátě okruhu v aplikaci na straně Blazor serveru musíte vyčistit vlastní JS objekty nebo na klientovi spustit jiný JS kód, použijte MutationObserver v klientovi vzorJS. Vzor MutationObserver umožňuje spustit JS kód při odebrání elementu z MODELU DOM.

Další informace najdete v následujících článcích:

• Blazor ASP.NET základní interoperabilita JavaScriptu (JSinterop):: Obsahuje příklad MutationObserver kódu vzoru.
• Zpracování chyb v aplikacích ASP.NET CoreBlazor: Část interoperability JavaScriptu popisuje zpracování chyb ve JS scénářích spolupráce.
• životní cyklus komponent ASP.NET CoreRazor: Vyřazení komponent a IDisposable IAsyncDisposable část popisuje, jak implementovat vzory odstranění v Razor komponentách.

Následující JS modul exportuje JS funkci pro zobrazení výzvy okna prohlížeče. Do externího JS souboru umístěte následující JS kód.

wwwroot/scripts.js:

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

Přidejte předchozí JS modul do aplikace nebo knihovny tříd jako statický webový prostředek ve wwwroot složce a pak modul naimportujte do kódu .NET voláním InvokeAsync instance IJSRuntime .

IJSRuntime importuje modul jako objekt IJSObjectReference, který představuje odkaz na JS objekt z kódu .NET. Použijte k IJSObjectReference vyvolání exportovaných JS funkcí z modulu.

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)
            {
            }
        }
    }
}

V předchozím příkladu:

• Podle konvence import je identifikátor speciální identifikátor používaný speciálně pro import JS modulu.
• Zadejte externí JS soubor modulu pomocí stabilní cesty statického webového prostředku: ./{SCRIPT PATH AND FILE NAME (.js)}, kde:
  • K vytvoření správné cesty statického prostředku k souboru JS se vyžaduje segment cesty pro aktuální adresář (./).
  • Zástupný symbol {SCRIPT PATH AND FILE NAME (.js)} je cesta a název souboru v části wwwroot.
• Vyhazuje IJSObjectReference pro uvolňování paměti v IAsyncDisposable.DisposeAsync.

Dynamické importování modulu vyžaduje požadavek na síť, takže jej lze dosáhnout pouze asynchronně voláním InvokeAsync.

IJSInProcessObjectReference představuje odkaz na JS objekt, jehož funkce lze vyvolat synchronně v komponentách na straně klienta. Další informace naleznete v synchronní JS interoperabilitě v části Součásti na straně klienta.

Poznámka:

Pokud externí JS soubor poskytuje Razor knihovna tříd, zadejte soubor modulu JS pomocí stabilní cesty k statickému webovému prostředku: ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}

• K vytvoření správné cesty statického prostředku k souboru JS se vyžaduje segment cesty pro aktuální adresář (./).
• Zástupný symbol {PACKAGE ID} je ID balíčku knihovny. Pokud v souboru projektu není zadaný parametr <PackageId>, jako ID balíčku se ve výchozím nastavení použije název sestavení projektu. V následujícím příkladu je ComponentLibrary název sestavení knihovny a soubor projektu knihovny nezadá <PackageId>.
• Zástupný symbol {SCRIPT PATH AND FILE NAME (.js)} je cesta a název souboru v části wwwroot. V následujícím příkladu se externí JS soubor (script.js) umístí do složky knihovny wwwroot tříd.
• module je privátní nullable IJSObjectReference třídy komponenty (private IJSObjectReference? module;).

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

Další informace najdete v tématu Využívání komponent ASP.NET Core Razor z knihovny tříd Razor (RCL).

V celé Blazor dokumentaci používají příklady příponu .js souboru pro soubory modulů, nikoli novější .mjs příponu souboru (RFC 9239). Naše dokumentace nadále používá příponu .js souboru ze stejných důvodů, proč dokumentace k Mozilla Foundation nadále používá příponu .js souboru. Další informace naleznete v tématu Doplňování – .mjs versus .js (dokumentace MDN).

Zachycení odkazů na prvky

Některé scénáře spolupráce javascriptu (JS) vyžadují odkazy na elementy HTML. Například knihovna uživatelského rozhraní může vyžadovat odkaz na element pro inicializaci nebo možná budete muset volat rozhraní API podobná příkazům v elementu, například click nebo play.

Pomocí následujícího přístupu zachyťte odkazy na elementy HTML v komponentě:

• @ref Přidejte atribut do elementu HTML.
• Definujte pole typu ElementReference , jehož název odpovídá hodnotě atributu @ref .

Následující příklad ukazuje zachycení odkazu na username <input> element:

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

@code {
    private ElementReference username;
}

Upozorňující

Odkaz na prvek použijte pouze ke ztlumení obsahu prázdného elementu, který s ním nekomuaguje Blazor. Tento scénář je užitečný, když rozhraní API třetí strany dodává obsah prvku. Vzhledem k tomu Blazor , že s prvkem nepracuje, neexistuje žádná možnost konfliktu mezi Blazorreprezentací elementu a modelu DOM.

V následujícím příkladu je nebezpečné ztlumit obsah neuspořádaného seznamu (ul) pomocí JS MyList vzájemné spolupráce, protože Blazor komunikuje s objektem DOM a naplní položky seznamu tohoto prvku (<li>) z objektuTodos:

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

Použití odkazu na MyList element pouze ke čtení obsahu MODELU DOM nebo k aktivaci události je podporována.

Pokud JS interop ztlumí obsah elementu MyList a Blazor pokusí se použít rozdíly u elementu, rozdíly nebudou odpovídat objektu DOM. Úprava obsahu seznamu prostřednictvím JS vzájemné spolupráce s odkazem na MyList element není podporována.

Další informace najdete v tématu ASP.NET Interoperabilita Core Blazor JavaScriptu (JSinteroperabilita).

Kód ElementReference se předává JS prostřednictvím JS zprostředkovatele komunikace. Kód JS obdrží HTMLElement instanci, kterou může používat s normálními rozhraními API DOM. Například následující kód definuje metodu rozšíření .NET (TriggerClickEvent), která umožňuje odeslat kliknutí myší na prvek.

Funkce JS clickElement vytvoří click událost u předaného elementu HTML (element):

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

Chcete-li volat funkci, která nevrací JS hodnotu, použijte JSRuntimeExtensions.InvokeVoidAsync. Následující kód aktivuje událost na straně click klienta voláním předchozí JS funkce s zachyceným ElementReferencekódem:

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

Pokud chcete použít metodu rozšíření, vytvořte statickou metodu IJSRuntime rozšíření, která obdrží instanci:

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

Metoda clickElement je volána přímo na objektu. Následující příklad předpokládá, že TriggerClickEvent metoda je k dispozici z JsInteropClasses oboru názvů:

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

Důležité

Proměnná exampleButton se vyplní až po vykreslení komponenty. Pokud se do kódu předá nepopsaný ElementReference kód, JS obdrží kód hodnotu null.JS Chcete-li manipulovat s odkazy na elementy po dokončení vykreslování komponenty, použijte OnAfterRenderAsync metody životního cyklu součásti.OnAfterRender

Při práci s obecnými typy a vrácení hodnoty použijte ValueTask<TResult>:

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

Zástupný {JAVASCRIPT FUNCTION} symbol je JS identifikátor funkce.

GenericMethod je volána přímo na objektu s typem. Následující příklad předpokládá, že GenericMethod je k dispozici z JsInteropClasses oboru názvů:

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

Referenční prvky napříč komponentami

Mezi ElementReference komponentami nelze předávat výraz, protože:

• Instance je zaručena pouze po vykreslení komponenty, která je během nebo po spuštění metody komponenty OnAfterRender/OnAfterRenderAsync .
• An ElementReference je parametr struct, který nelze předat jako parametr komponenty.

Aby nadřazená komponenta zpřístupnit prvek jiným komponentám, může nadřazená komponenta:

• Povolte podřízeným komponentám registraci zpětných volání.
• Vyvolá registrované zpětné volání během OnAfterRender události s předaným odkazem na element. Nepřímo tento přístup umožňuje podřízeným komponentám interakci s odkazem na element nadřazeného objektu.

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

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

Poznámka:

Obecné pokyny k JS umístění a doporučení pro produkční aplikace najdete v tématu o umístění JavaScriptu v aplikacích ASP.NET CoreBlazor.

CallJs7.razor (nadřazená součást):

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

V předchozím příkladu je BlazorSampleobor názvů aplikace . Pokud kód testujete místně, aktualizujte obor názvů.

SurveyPrompt.razor (podřízená součást):

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

V předchozím příkladu je BlazorSample obor názvů aplikace se sdílenými komponentami ve Shared složce. Pokud kód testujete místně, aktualizujte obor názvů.

Posílení volání zprostředkovatele komunikace JavaScriptu

Tato část platí jenom pro součásti interaktivního serveru, ale komponenty na straně klienta můžou také nastavit JS časové limity spolupráce, pokud to podmínky vyžadují.

V aplikacích na straně serveru s interaktivitou serveru může interop JavaScriptu (JS) selhat kvůli chybám sítě a měl by být považován za nespolehlivý. Blazor aplikace používají časový limit jedné minuty pro JS volání zprostředkovatele komunikace. Pokud aplikace dokáže tolerovat agresivnější časový limit, nastavte časový limit pomocí jednoho z následujících přístupů.

Nastavte globální časový limit v :Program.cs CircuitOptions.JSInteropDefaultCallTimeout

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

Zástupný {TIMEOUT} symbol je ( TimeSpan například TimeSpan.FromSeconds(80)).

Nastavte časový limit volání v kódu komponenty. Zadaný časový limit přepíše globální časový limit nastavený pomocí JSInteropDefaultCallTimeout:

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

V předchozím příkladu:

• Zástupný {TIMEOUT} symbol je ( TimeSpan například TimeSpan.FromSeconds(80)).
• Zástupný {ID} symbol je identifikátor funkce, která se má vyvolat. Například hodnota someScope.someFunction vyvolá funkci window.someScope.someFunction.

I když běžnou příčinou JS selhání interoperability jsou selhání sítě se součástmi na straně serveru, časové limity volání na straně serveru je možné nastavit pro JS volání zprostředkovatele pro součásti na straně klienta. I když ne Blazor–SignalR okruh existuje pro komponentu na straně klienta, JS volání vzájemné spolupráce může selhat z jiných důvodů, které platí.

Další informace o vyčerpání prostředků najdete v doprovodných materiálech ke zmírnění hrozeb pro ASP.NET interaktivní vykreslování na straně serveru coreBlazor.

Vyhněte se cyklických odkazům na objekty.

Objekty, které obsahují cyklický odkaz, nelze serializovat v klientovi pro:

• Volání metody .NET
• Volání javascriptové metody z jazyka C#, pokud návratový typ obsahuje cyklický odkaz.

Knihovny JavaScriptu, které vykreslují uživatelské rozhraní

Někdy můžete chtít použít knihovny JavaScriptu (JS), které vytvářejí viditelné prvky uživatelského rozhraní v modelu DOM prohlížeče. Na první pohled se to může zdát obtížné, protože Blazorsystém rozdílů spoléhá na kontrolu nad stromem prvků DOM a dochází k chybám, pokud nějaký externí kód ztlumí strom DOM a zneplatní jeho mechanismus použití rozdílů. Nejedná se o Blazorkonkrétní omezení. K stejné výzvě dochází u jakékoli architektury uživatelského rozhraní založeného na rozdílech.

Naštěstí je snadné vložit externě generované uživatelské rozhraní do Razor uživatelského rozhraní komponent spolehlivě. Doporučená technika spočívá v tom, že kód komponenty (.razor soubor) vytvoří prázdný prvek. Pokud jde Blazoro diffingový systém, prvek je vždy prázdný, takže renderer se do prvku nezapočítá a místo toho ponechá jeho obsah sám. Díky tomu je bezpečné naplnit prvek libovolným externě spravovaným obsahem.

Následující příklad ukazuje koncept. V rámci příkazu if , kdy firstRender je true, interagujte s unmanagedElement vnějškem Blazor použití JS zprostředkovatele komunikace. Můžete například volat externí JS knihovnu pro naplnění elementu. Blazor ponechá obsah elementu sám, dokud se tato komponenta neodebere. Když je komponenta odebrána, odebere se také celý podstrom DOM komponenty.

<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)
        {
            ...
        }
    }
}

Představte si následující příklad, který vykreslí interaktivní mapu pomocí opensourcových rozhraní API Mapboxu.

Následující JS modul se umístí do aplikace nebo zpřístupní knihovně Razor tříd.

Poznámka:

Pokud chcete vytvořit mapu Mapbox , získejte přístupový token z přihlášení k Mapboxu a zadejte ho tam, kde {ACCESS TOKEN} se zobrazí v následujícím kódu.

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

Chcete-li vytvořit správný styl, přidejte na stránku HTML hostitele následující značku šablony stylů.

Do značky elementu <head> (umístění <head> obsahu) přidejte následující <link> prvek:

<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)
            {
            }
        }
    }
}

Předchozí příklad vytvoří interaktivní uživatelské rozhraní mapy. Uživatel:

• Lze přetáhnout a posunout nebo zvětšit.
• Výběrem tlačítek přejdete na předdefinovaná umístění.

V předchozím příkladu:

• Co se týče toho, co se týče, je sousy <div> @ref="mapElement" prázdné Blazor . Skript mapbox-gl.js může bezpečně naplnit prvek a upravit jeho obsah. Tuto techniku použijte s libovolnou JS knihovnou, která vykresluje uživatelské rozhraní. Komponenty z architektury SPA třetí strany JS můžete vkládat do Razor komponent, pokud se nepokouší kontaktovat a upravit jiné části stránky. Externí kód není bezpečný pro JS úpravu prvků, které Blazor se nepovažují za prázdné.
• Při použití tohoto přístupu mějte na paměti pravidla týkající Blazor se zachování nebo zničení prvků DOM. Komponenta bezpečně zpracovává události kliknutí na tlačítko a aktualizuje existující instanci mapování, protože prvky MODELU DOM jsou zachovány tam, kde je to možné. Pokud jste vykreslovali seznam prvků mapy ze @foreach smyčky, chcete použít @key k zajištění zachování instancí součástí. Jinak by změny v datech seznamu mohly způsobit, že instance součástí zachovají stav předchozích instancí nežádoucím způsobem. Další informace najdete v tématu použití atributu @key direktivy k zachování vztahu mezi prvky, komponentami a objekty modelu.
• Příklad zapouzdřuje JS logiku a závislosti v modulu JavaScriptu a načte modul dynamicky pomocí identifikátoru import . Další informace najdete v tématu Izolace JavaScriptu v modulech JavaScriptu.

Podpora bajtového pole

Blazor podporuje optimalizovanou bajtůovou matici JavaScriptu (JS), která zabraňuje kódování a dekódování bajtových polí do Base64. Následující příklad používá JS zprostředkovatele komunikace k předání pole bajtů do JavaScriptu.

receiveByteArrayJS Zadejte funkci. Funkce se volá a InvokeVoidAsync nevrací hodnotu:

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

Poznámka:

Obecné pokyny k JS umístění a doporučení pro produkční aplikace najdete v tématu o umístění JavaScriptu v aplikacích ASP.NET CoreBlazor.

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

Streamování z .NET do JavaScriptu

Blazor podporuje streamování dat přímo z .NET do JavaScriptu (JS). Datové proudy se vytvářejí pomocí .DotNetStreamReference

DotNetStreamReference představuje datový proud .NET a používá následující parametry:

• stream: Stream odeslaný do JS.
• leaveOpen: Určuje, zda je datový proud po přenosu otevřen. Pokud není zadaná hodnota, leaveOpen výchozí hodnota je false.

Pro JSpříjem dat použijte vyrovnávací paměť pole nebo čitelný datový proud:

• Pomocí funkce ArrayBuffer:

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

• ReadableStreamPomocí funkce :

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

V kódu jazyka C#:

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

V předchozím příkladu:

• Zástupný {STREAM} symbol představuje odeslanou Stream hodnotu JS.
• JS je vložená IJSRuntime instance.

Vystavení DotNetStreamReference instance je obvykle zbytečné. Je-li leaveOpen nastavena na výchozí hodnotu false, podklad Stream je automaticky uvolněn po přenosu do JS.

Pokud leaveOpen je true, pak odstranění DotNetStreamReference neodloží jeho základní Stream. Kód aplikace určuje, kdy má být podkladový objekt Streamuvolněn. Při rozhodování o tom, jak odstranit podkladové Streampoložky, zvažte následující:

• Odstranění Stream během přenosu JS se považuje za chybu aplikace a může způsobit neošetřenou výjimku.
• Stream přenos začíná, jakmile DotNetStreamReference se předá jako argument volání JS zprostředkovatele komunikace bez ohledu na to, jestli se datový proud skutečně používá v JS logice.

Vzhledem k těmto charakteristikám doporučujeme odstranit podkladový kód Stream až po jeho plném využití JS (příslib vrácený arrayBuffer nebo stream vyřešený). Z toho vyplývá, že by měla být předána JS pouze v případě, že DotNetStreamReference ji nepodmíněně bude využívat logikaJS.

Volání metod .NET z funkcí JavaScriptu v ASP.NET Core Blazor pokrývá zpětnou operaci streamování z JavaScriptu do .NET.

ASP.NET soubory core Blazor ke stažení popisuje, jak stáhnout soubor v Blazor.

Zachycení výjimek JavaScriptu

Chcete-li zachytit JS výjimky, zabalte interoperabilitu -trycatch JS do bloku a zachyťte .JSException

V následujícím příkladu nonFunctionJS funkce neexistuje. Pokud se funkce nenajde, JSException je schycená s chybou Message , která označuje následující chybu:

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

Přerušení dlouhotrvající funkce JavaScriptu

JSPomocí AbortController s komponentou CancellationTokenSource můžete přerušit dlouho běžící funkci JavaScriptu z kódu jazyka C#.

Následující JSHelpers třída obsahuje simulovanou dlouho běžící funkci, která počítá nepřetržitě, longRunningFndokud AbortController.signal nebylo uvedeno, že AbortController.abort se volala. Funkce sleep je určená pro demonstrační účely k simulaci pomalého spuštění dlouhotrvající funkce a nebyla by přítomna v produkčním kódu. Při volání stopFnkomponenty je longRunningFn signalizovat přerušení prostřednictvím podmíněné kontroly AbortSignal.abortedsmyčky while .

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

Poznámka:

Obecné pokyny k JS umístění a doporučení pro produkční aplikace najdete v tématu o umístění JavaScriptu v aplikacích ASP.NET CoreBlazor.

Následující komponenta:

• JS Vyvolá funkci longRunningFn při Start Task výběru tlačítka. A CancellationTokenSource slouží ke správě provádění dlouhotrvající funkce. CancellationToken.Register nastaví delegáta JS volání zprostředkovatele, který spustí JS funkci stopFn při CancellationTokenSource.Token zrušení.
• Cancel Task Když je tlačítko vybráno, CancellationTokenSource.Token zruší se voláním Cancel.
• Metoda CancellationTokenSource se vyřadí Dispose .

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

Konzola vývojářských nástrojů prohlížeče označuje spuštění dlouhotrvající JS funkce po Start Task výběru tlačítka a přerušení funkce po Cancel Task výběru tlačítka:

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

Interoperabilita JavaScriptu [JSImport]/[JSExport]

Tato část se týká komponent na straně klienta.

Jako alternativu k interakci s JavaScriptem (JS) v komponentách na straně klienta pomocí JS Blazormechanismu vzájemné spolupráce založeného na IJSRuntime rozhraní/JS[JSImport][JSExport] je k dispozici rozhraní API vzájemné spolupráce pro aplikace, které cílí na .NET 7 nebo novější.

Další informace naleznete v tématu JavaScript JSImport/JSExport interop s ASP.NET Core Blazor.

Nezřetězení interoperability JavaScriptu

Tato část se týká komponent na straně klienta.

Neposkládaný interoperabilita používající IJSUnmarshalledRuntime rozhraní je zastaralá a měla by být nahrazena javascriptovou [JSImport]/[JSExport] interoperabilitou.

Další informace naleznete v tématu JavaScript JSImport/JSExport interop s ASP.NET Core Blazor.

Vyřazení odkazů na objekty zprostředkovatele komunikace JavaScriptu

Příklady v článcích interoperability JavaScriptu (JS) ukazují typické vzory odstranění objektů:

• Při volání JS z .NET, jak je popsáno v tomto článku, vyřaďte všechny vytvořené/IJSInProcessObjectReference/JSObjectReference IJSObjectReferencez .NET nebo JS z důvodu zabránění úniku JS paměti.

• Při volání rozhraní .NET z JS, jak je popsáno v volání metod .NET z javascriptových funkcí v ASP.NET CoreBlazor , odstraňte vytvořené DotNetObjectReference z .NET nebo zJS, aby nedošlo k úniku paměti .NET.

JS odkazy na objekty vzájemné spolupráce jsou implementovány jako mapované pomocí identifikátoru na straně JS volání zprostředkovatele komunikace, který vytvoří odkaz. Když je odstranění objektu inicializováno z rozhraní .NET nebo JS ze strany, Blazor odebere položku z mapy a objekt může být uvolněn z paměti, pokud neexistuje žádný jiný silný odkaz na objekt.

Minimálně vždy odstraňte objekty vytvořené na straně .NET, aby nedošlo k úniku spravované paměti .NET.

Úlohy čištění DOM během odstraňování komponent

Další informace najdete v tématu ASP.NET Interoperabilita Core Blazor JavaScriptu (JSinteroperabilita).

Volání zprostředkovatele komunikace JavaScriptu bez okruhu

Další informace najdete v tématu ASP.NET Interoperabilita Core Blazor JavaScriptu (JSinteroperabilita).

Další materiály

• Volání metod .NET z funkcí JavaScriptu v ASP.NET Core Blazor
• InteropComponent.razor example (dotnet/AspNetCore GitHub repository main branch): Větev main představuje aktuální vývoj produktové jednotky pro příští verzi ASP.NET Core. Pokud chcete vybrat větev pro jinou verzi (například release/{VERSION}, kde {VERSION} zástupný symbol je verze verze), vyberte větev pomocí rozevíracího seznamu Přepnout větve nebo značky . Pro větev, která již neexistuje, pomocí karty Značky vyhledejte rozhraní API (například v7.0.0).
• Blazorukázky úložiště GitHub () (dotnet/blazor-samplespostup stažení)
• Zpracování chyb v aplikacích ASP.NET Core Blazor (oddíl interoperability JavaScriptu)
• Zmírnění hrozeb: Funkce JavaScriptu vyvolané z .NET