Współdziałanie języka JavaScript platformy ASP.NET Core Blazor (współdziałanie języka JS)

Aplikacja platformy Blazor może wywoływać funkcje języka JavaScript (JS) z metod platformy .NET oraz metody platformy.NET z funkcji języka JS. Te scenariusze są nazywane współdziałaniem języka JavaScript (współdziałaniem języka JS).

Dalsze wskazówki dotyczące współdziałania języka JS są dostępne w następujących artykułach:

• Wywoływanie funkcji języka JavaScript z metod platformy .NET na platformie ASP.NET Core Blazor
• Wywoływanie metod platformy .NET z funkcji języka JavaScript z na platformie ASP.NET Core Blazor

Uwaga

Interfejs API międzyoperacyjny języka JavaScript [JSImport]/[JSExport] jest dostępny dla składników po stronie klienta w programie ASP.NET Core na platformie .NET 7 lub nowszym.

Aby uzyskać więcej informacji, zobacz JavaScript Import/Export interop with ASP.NET Core (Importowanie/JSeksportowanie międzyoperacji języka JavaScript JSza pomocą programu ASP.NET CoreBlazor).

Abstrakcji międzyoperacyjnych i pakietów funkcji języka JavaScript

Pakiet @microsoft/dotnet-js-interop (npmjs.com) (Microsoft.JSInterop pakiet NuGet) udostępnia abstrakcję i funkcje między kodem .NET i JavaScript (JS). Źródło referencyjne jest dostępne w dotnet/aspnetcore repozytorium GitHub (/src/JSInterop folder). Aby uzyskać więcej informacji, zobacz plik repozytorium README.md GitHub.

Uwaga

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

Dodatkowe zasoby do pisania JS skryptów międzyoperacyjności w języku TypeScript:

• TypeScript
• Samouczek: tworzenie aplikacji ASP.NET Core za pomocą języka TypeScript w programie Visual Studio
• Zarządzanie pakietami npm w programie Visual Studio

Interakcja z dom

Zmutuj dom tylko przy użyciu języka JavaScript (JS), gdy obiekt nie wchodzi w interakcję z elementem Blazor. Platforma Blazor utrzymuje reprezentacje modelu DOM i współdziała bezpośrednio z obiektami modelu DOM. Jeśli element renderowany przez platformę Blazor jest modyfikowany zewnętrznie przy użyciu języka JS bezpośrednio lub przez współdziałanie języka JS, model DOM może być już niezgodny z wewnętrzną reprezentacją platformy Blazor, co może spowodować niezdefiniowane zachowanie. Niezdefiniowane zachowanie może tylko zakłócać prezentację elementów lub ich funkcji, ale może również powodować zagrożenia bezpieczeństwa dla aplikacji lub serwera.

Te wskazówki dotyczą nie tylko własnego kodu współdziałania języka JS, ale także wszystkich bibliotek języka JS używanych przez aplikację, w tym wszystkich elementów udostępnianych przez platformę innej firmy, takich jak Bootstrap JS i jQuery.

W kilku przykładach dokumentacji współdziałanie języka JS jest używane do modyfikowania elementu wyłącznie do celów demonstracyjnych w ramach przykładu. W takich przypadkach w tekście pojawia się ostrzeżenie.

Aby uzyskać więcej informacji, zobacz Wywoływanie funkcji języka JavaScript z metod platformy .NET na platformie ASP.NET Core Blazor.

Asynchroniczne wywołania języka JavaScript

Wywołania współdziałania języka JS są domyślnie asynchroniczne niezależnie od tego, czy wywoływany kod jest synchroniczny, czy asynchroniczny. Wywołania są domyślnie asynchroniczne, aby upewnić się, że składniki są zgodne z modelami renderowania po stronie serwera i po stronie klienta. Podczas wdrażania renderowania po stronie serwera wywołania międzyoperacyjne muszą być asynchroniczne, JS ponieważ są wysyłane za pośrednictwem połączenia sieciowego. W przypadku aplikacji, które korzystają wyłącznie z renderowania po stronie klienta, obsługiwane są synchroniczne JS wywołania międzyoperacji.

Aby uzyskać więcej informacji, zobacz następujące artykuły:

• Wywoływanie funkcji języka JavaScript z metod platformy .NET na platformie ASP.NET Core Blazor
• Wywoływanie metod platformy .NET z funkcji języka JavaScript z na platformie ASP.NET Core Blazor

Serializacja obiektów

Platforma Blazor używa obiektu System.Text.Json do serializacji z następującymi wymaganiami i zachowaniami domyślnymi:

• Typy muszą mieć konstruktor domyślny, metody dostępu get/set muszą być publiczne, a pola nigdy nie są serializowane.
• Globalna domyślna serializacja nie jest dostosowywalna, aby uniknąć przerywania istniejących bibliotek składników, wpływu na wydajność i bezpieczeństwo oraz zmniejszeń niezawodności.
• Serializowanie nazw elementów członkowskich platformy .NET powoduje stosowanie małych liter w nazwach kluczy kodu JSON.
• Kod JSON jest deserializowany jako wystąpienia obiektu JsonElement języka C#, które zezwalają na mieszaną wielkość liter. Wewnętrzne rzutowanie dla przypisań do właściwości modelu języka C# działa zgodnie z oczekiwaniami pomimo różnic w wielkościach liter między nazwami kluczy kodu JSON i nazwami właściwości języka C#.
• Złożone typy struktur, takie jak KeyValuePair, mogą zostać przycięte przez program IL Trimmer podczas publikowania i nie są obecne dla JS międzyoperamentu. Zalecamy tworzenie typów niestandardowych dla typów, które domyślnie przycina trymer IL.

Interfejs API JsonConverter jest dostępny na potrzeby serializacji niestandardowej. Właściwości można oznaczyć adnotacją za pomocą atrybutu [JsonConverter], aby zastąpić domyślną serializację dla istniejącego typu danych.

Aby uzyskać więcej informacji, zobacz następujące zasoby w dokumentacji platformy .NET:

• Serializacja i deserializacja kodu JSON (przeprowadzanie marshalingu i unmarshalingu) na platformie .NET
• Jak dostosować nazwy i wartości właściwości przy użyciu obiektu System.Text.Json
• Jak pisać niestandardowe konwertery dla serializacji kodu JSON (przeprowadzać marshaling) na platformie .NET

Platforma Blazor obsługuje zoptymalizowane współdziałanie języka JS na tablicy bajtów, które unika kodowania/dekodowania tablic bajtów w schemacie Base64. Aplikacja może stosować serializację niestandardową i przekazywać bajty wynikowe. Aby uzyskać więcej informacji, zobacz Wywoływanie funkcji języka JavaScript z metod platformy .NET na platformie ASP.NET Core Blazor.

Zadania oczyszczania modelu DOM podczas usuwania składników

Nie wykonuj JS kodu międzyoperajowego dla zadań oczyszczania MODELU DOM podczas usuwania składników. Zamiast tego użyj MutationObserver wzorca w języku JavaScript (JS) na kliencie z następujących powodów:

• Składnik mógł zostać usunięty z modelu DOM przez czas wykonywania kodu oczyszczania w pliku Dispose{Async}.
• Podczas renderowania Blazor po stronie serwera program renderujący mógł zostać usunięty przez strukturę przez czas wykonywania kodu oczyszczania w programie Dispose{Async}.

Wzorzec MutationObserver umożliwia uruchamianie funkcji po usunięciu elementu z modelu DOM.

W poniższym przykładzie DOMCleanup składnik:

• Zawiera element <div> z wartością cleanupDivid . Element <div> zostanie usunięty z modelu DOM wraz z resztą znacznika DOM składnika, gdy składnik zostanie usunięty z modelu DOM.
• Ładuje klasę DOMCleanupJS z DOMCleanup.razor.js pliku i wywołuje jego createObserver funkcję w celu skonfigurowania wywołania zwrotnego MutationObserver . Te zadania są wykonywane w metodzie OnAfterRenderAsynccyklu życia.

DOMCleanup.razor:

@page "/dom-cleanup"
@implements IAsyncDisposable
@inject IJSRuntime JS

<h1>DOM Cleanup Example</h1>

<div id="cleanupDiv"></div>

@code {
    private IJSObjectReference? module;

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

            await module.InvokeVoidAsync("DOMCleanup.createObserver");
        }
    }

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

W poniższym przykładzie wywołanie zwrotne jest wykonywane za każdym razem, MutationObserver gdy nastąpi zmiana MODELU DOM. Wykonaj kod oczyszczania, gdy if instrukcja potwierdza, że element docelowy (cleanupDiv) został usunięty (if (targetRemoved) { ... }). Ważne jest rozłączenie i usunięcie MutationObserver elementu , aby uniknąć przecieku pamięci po wykonaniu kodu oczyszczania.

DOMCleanup.razor.js umieszczony obok poprzedniego DOMCleanup składnika:

export class DOMCleanup {
  static observer;

  static createObserver() {
    const target = document.querySelector('#cleanupDiv');

    this.observer = new MutationObserver(function (mutations) {
      const targetRemoved = mutations.some(function (mutation) {
        const nodes = Array.from(mutation.removedNodes);
        return nodes.indexOf(target) !== -1;
      });

      if (targetRemoved) {
        // Cleanup resources here
        // ...

        // Disconnect and delete MutationObserver
        this.observer && this.observer.disconnect();
        delete this.observer;
      }
    });

    this.observer.observe(target.parentNode, { childList: true });
  }
}

window.DOMCleanup = DOMCleanup;

Wywołania międzyoperacyjne języka JavaScript bez obwodu

Ta sekcja dotyczy tylko aplikacji po stronie serwera.

Wywołania międzyoperacyjne języka JavaScript (JS) nie mogą być wystawiane po rozłączeniu obwodu SignalR . Bez obwodu podczas usuwania składników lub w dowolnym innym czasie, że obwód nie istnieje, następująca metoda wywołuje niepowodzenie i rejestruje komunikat, że obwód jest odłączony jako JSDisconnectedException:

• JS wywołania metody międzyoperacyjnej
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync)
• Dispose/DisposeAsync wywołuje każdą IJSObjectReferencemetodę .

Aby uniknąć rejestrowania lub rejestrowania JSDisconnectedException informacji niestandardowych, przechwyć wyjątek w instrukcji try-catch .

W poniższym przykładzie usuwania składników:

• Składnik implementuje interfejs IAsyncDisposable.
• objInstancejest .IJSObjectReference
• JSDisconnectedException jest złapany i nie jest rejestrowany.
• Opcjonalnie możesz rejestrować informacje niestandardowe w instrukcji catch na każdym preferowanym poziomie dziennika. Poniższy przykład nie rejestruje informacji niestandardowych, ponieważ zakłada, że deweloper nie dba o to, kiedy lub gdzie obwody są rozłączane podczas usuwania składników.

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

Jeśli musisz wyczyścić własne JS obiekty lub wykonać inny JS kod na kliencie po utracie obwodu, użyj MutationObserver wzorca w JS programie na kliencie. Wzorzec MutationObserver umożliwia uruchamianie funkcji po usunięciu elementu z modelu DOM.

Aby uzyskać więcej informacji, zobacz następujące artykuły:

• Obsługa błędów w aplikacjach ASP.NET CoreBlazor: w sekcji międzyoperacyjnej języka JavaScript omówiono obsługę błędów w JS scenariuszach międzyoperacyjności.
• ASP.NET Cykl życia składnika podstawowegoRazor: usuwanie składników wraz z sekcją IDisposable iIAsyncDisposablezawiera opis sposobu implementowania wzorców usuwania w Razor składnikach.

Buforowane pliki JavaScript

Pliki JavaScript (JS) i inne zasoby statyczne nie są zwykle buforowane na klientach podczas programowania w środowisku Development. Podczas programowania statyczne żądania zasobów zawierają nagłówek Cache-Control z wartością no-cache, max-age lub zero (0).

Podczas produkcji w środowisku Production pliki JS są zwykle buforowane przez klientów.

Aby wyłączyć buforowanie po stronie klienta w przeglądarkach, deweloperzy zwykle stosują jedną z następujących metod:

• Wyłącz buforowanie, gdy konsola narzędzi deweloperskich przeglądarki jest otwarta. Wskazówki można znaleźć w dokumentacji narzędzi deweloperskich każdego osoby odpowiedzialnej za przeglądarkę:
  • Zestaw Chrome DevTools
  • Narzędzia deweloperskie przeglądarki Firefox
  • Omówienie narzędzi deweloperskich przeglądarki Microsoft Edge
• Wykonaj ręczne odświeżanie przeglądarki dowolnej strony internetowej aplikacji platformy Blazor w celu ponownego załadowania plików JS z serwera. Oprogramowanie pośredniczące HTTP platformy ASP.NET Core zawsze honoruje prawidłowy nagłówek Cache-Control no-cache wysyłany przez klienta.

Aby uzyskać więcej informacji, zobacz:

• Środowiska platformy ASP.NET Core Blazor
• Buforowanie odpowiedzi na platformie ASP.NET Core

Limity rozmiaru wywołań międzyoperacyjności języka JavaScript

Ta sekcja dotyczy tylko składników interaktywnych w aplikacjach po stronie serwera. W przypadku składników po stronie klienta struktura nie nakłada limitu rozmiaru danych wejściowych i wyjściowych międzyoperacyjności języka JavaScript (JS).

W przypadku składników interaktywnych w aplikacjach JS po stronie serwera międzyoperacyjne wywołania przekazywania danych z klienta do serwera są ograniczone do maksymalnego rozmiaru komunikatów przychodzących SignalR dozwolonych dla metod centrum, które są wymuszane ( HubOptions.MaximumReceiveMessageSize domyślnie: 32 KB). JS do komunikatów platformy .NET SignalR większych niż MaximumReceiveMessageSize zgłasza błąd. Struktura nie nakłada limitu rozmiaru komunikatu SignalR z centrum na klienta. Aby uzyskać więcej informacji na temat limitu rozmiaru, komunikatów o błędach i wskazówek dotyczących obsługi limitów rozmiaru komunikatów, zobacz wskazówki dotyczące ASP.NET CoreBlazorSignalR.

Określanie, gdzie aplikacja jest uruchomiona

Jeśli aplikacja ma znaczenie, aby wiedzieć, gdzie działa kod na potrzeby JS wywołań międzyoperamentowych, użyj polecenia OperatingSystem.IsBrowser , aby określić, czy składnik jest wykonywany w kontekście przeglądarki w zestawie WebAssembly.