Udostępnij za pośrednictwem

Lokalizacja języka JavaScript w aplikacjach ASP.NET Core Blazor

  • Artykuł

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Załaduj kod języka JavaScript (JS) przy użyciu dowolnej z następujących metod:

Ostrzeżenie

Umieść <script> tag tylko w pliku składnika (.razor), jeśli składnik ma gwarancję wdrożenia statycznego renderowania po stronie serwera (statyczny SSR), ponieważ <script> tag nie może być aktualizowany dynamicznie.

Ostrzeżenie

Nie umieszczaj tagu <script> w pliku składnika (.razor), ponieważ <script> tag nie może być aktualizowany dynamicznie.

Uwaga

W przykładach w dokumentacji zwykle skrypty są umieszczane w tagu <script> lub są ładowane skrypty globalne z plików zewnętrznych. Te metody powodują zanieczyszczenie klienta funkcjami globalnymi. W przypadku aplikacji produkcyjnych zalecamy umieszczenie JS ich w osobnych JS modułach , które można zaimportować w razie potrzeby. Aby uzyskać więcej informacji, zobacz sekcję Izolacja języka JavaScript w modułach języka JavaScript.

Uwaga

W przykładach w dokumentacji skrypty są umieszczane w tagu <script> lub są ładowane skrypty globalne z plików zewnętrznych. Te metody powodują zanieczyszczenie klienta funkcjami globalnymi. Umieszczanie JS w osobnychJS modułach, które można zaimportować, jeśli jest to konieczne, nie jest obsługiwane wcześniej Blazor niż ASP.NET Core 5.0. Jeśli aplikacja wymaga użycia modułów języka JS do izolacji języka JS, zalecamy kompilowanie aplikacji przy użyciu platformy ASP.NET Core 5.0 lub nowszej. Aby uzyskać więcej informacji, użyj listy rozwijanej Wersja w celu wybrania wersji 5.0 lub nowszej tego artykułu i zobacz sekcję Izolacja języka JavaScript w modułach języka JavaScript.

Ładowanie skryptu w znaczniku <head>

Metoda przedstawiona w tej sekcji na ogół nie jest zalecana.

Umieść tagi JavaScript () (JS<script>...</script>) w znaczniku <head>elementu:

<head>
    ...

    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</head>

Ładowanie języka JS ze znacznika <head> nie jest najlepszą metodą z następujących powodów:

  • Współdziałanie języka JS może zakończyć się niepowodzeniem, jeśli skrypt zależy od platformy Blazor. Zalecamy ładowanie skryptów przy użyciu jednej z pozostałych metod, a nie za pośrednictwem znacznika <head>.
  • Interakcja ze stroną może być powolniejsza ze względu na czas potrzebny na analizowanie języka JS w skrypcie.

Ładowanie skryptu w znaczniku <body>

Umieść tagi JavaScript (<script>...</script>) wewnątrz elementu zamykającego </body> po odwołaniu do skryptuBlazor:

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

W poprzednim przykładzie {BLAZOR SCRIPT} symbol zastępczy to ścieżka skryptu Blazor i nazwa pliku. Aby uzyskać informacje o lokalizacji skryptu, zobacz ASP.NET Core project structure (Struktura projektu ASP.NET CoreBlazor).

Ładowanie skryptu z zewnętrznego pliku JavaScript (.js) znajdującego się w tej samej lokalizacji co składnik

Kolokacja plików JavaScript (JS) dla Razor składników to wygodny sposób organizowania skryptów w aplikacji.

RazorBlazor składniki aplikacji składają JS pliki przy użyciu .razor.js rozszerzenia i są publicznie dostępne przy użyciu ścieżki do pliku w projekcie:

{PATH}/{COMPONENT}.razor.js

  • Symbol {PATH} zastępczy to ścieżka do składnika.
  • Symbol {COMPONENT} zastępczy jest składnikiem.

Po opublikowaniu aplikacji struktura automatycznie przenosi skrypt do katalogu głównego sieci Web. Skrypty są przenoszone do bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.jsobiektu , gdzie symbole zastępcze to:

  • {TARGET FRAMEWORK MONIKER} to target framework Moniker (TFM).
  • {PATH} to ścieżka do składnika.
  • {COMPONENT} to nazwa składnika.

Nie trzeba zmieniać względnego adresu URL skryptu, ponieważ Blazor dba o umieszczenie JS pliku w opublikowanych zasobach statycznych.

W tej sekcji i poniższych przykładach skupiono się głównie na objaśnieniu JS kolokacji pliku. W pierwszym przykładzie pokazano poskładany JS plik ze zwykłą JS funkcją. W drugim przykładzie pokazano użycie modułu do załadowania funkcji, co jest zalecanym podejściem dla większości aplikacji produkcyjnych. Wywoływanie JS z platformy .NET jest w pełni omówione w temacie Wywoływanie funkcji JavaScript z metod platformy .NET w programie ASP.NET CoreBlazor, gdzie istnieją dalsze wyjaśnienia interfejsu BlazorJS API z dodatkowymi przykładami. Usuwanie składników, które znajduje się w drugim przykładzie, jest objęte cyklem życia składników ASP.NET CoreRazor.

Poniższy JsCollocation1 składnik ładuje skrypt za pośrednictwem składnika i wywołuje JS funkcję za pomocą HeadContent IJSRuntime.InvokeAsyncpolecenia . Symbol {PATH} zastępczy to ścieżka do składnika.

Ważne

Jeśli używasz następującego kodu do pokazu w aplikacji testowej, zmień {PATH} symbol zastępczy na ścieżkę składnika (na przykład Components/Pages w programie .NET 8 lub nowszym lub Pages na platformie .NET 7 lub starszej). W programie Blazor Web App (.NET 8 lub nowszym) składnik wymaga interaktywnego trybu renderowania stosowanego globalnie do aplikacji lub definicji składnika.

Dodaj następujący skrypt po Blazor skryscie (lokalizacja skryptu uruchamianiaBlazor):

<script src="{PATH}/JsCollocation1.razor.js"></script>

JsCollocation1 component ({PATH}/JsCollocation1.razor):

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

<PageTitle>JS Collocation 1</PageTitle>

<h1>JS Collocation Example 1</h1>

<button @onclick="ShowPrompt">Call showPrompt1</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private string? result;

    public async void ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

Skomponowany plik jest umieszczany JS obok JsCollocation1 pliku składnika o nazwie JsCollocation1.razor.js. W składniku JsCollocation1 skrypt jest przywoływane w ścieżce posadzonego pliku. W poniższym przykładzie showPrompt1 funkcja akceptuje nazwę użytkownika z obiektu Window prompt() i zwraca ją do składnika do wyświetlania JsCollocation1 .

{PATH}/JsCollocation1.razor.js:

function showPrompt1(message) {
  return prompt(message, 'Type your name here');
}

Powyższe podejście nie jest zalecane do użytku ogólnego w aplikacjach produkcyjnych, ponieważ podejście zanieczyszcza klienta za pomocą funkcji globalnych. Lepszym podejściem dla aplikacji produkcyjnych jest użycie JS modułów. Te same ogólne zasady dotyczą ładowania modułu JS ze s collocated JS pliku, jak pokazano w następnym przykładzie.

Metoda następującego składnika ładuje JS moduł do moduleklasy , która jest klasą IJSObjectReference składników.OnAfterRenderAsync JsCollocation2 module służy do wywoływania showPrompt2 funkcji. Symbol {PATH} zastępczy to ścieżka do składnika.

Ważne

Jeśli używasz następującego kodu do pokazu w aplikacji testowej, zmień {PATH} symbol zastępczy na ścieżkę składnika. W programie Blazor Web App (.NET 8 lub nowszym) składnik wymaga interaktywnego trybu renderowania stosowanego globalnie do aplikacji lub definicji składnika.

JsCollocation2 component ({PATH}/JsCollocation2.razor):

@page "/js-collocation-2"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>JS Collocation 2</PageTitle>

<h1>JS Collocation Example 2</h1>

<button @onclick="ShowPrompt">Call showPrompt2</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

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

    protected async override Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            /*
                Change the {PATH} placeholder in the next line to the path of
                the collocated JS file in the app. Examples:

                ./Components/Pages/JsCollocation2.razor.js (.NET 8 or later)
                ./Pages/JsCollocation2.razor.js (.NET 7 or earlier)
            */
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./{PATH}/JsCollocation2.razor.js");
        }
    }

    public async void ShowPrompt()
    {
        if (module is not null)
        {
            result = await module.InvokeAsync<string>(
                "showPrompt2", "What's your name?");
            StateHasChanged();
        }
    }

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

W poprzednim przykładzie JSDisconnectedException jest uwięziony podczas usuwania modułu w przypadku Blazorutraty obwodu SignalR . Jeśli poprzedni kod jest używany w Blazor WebAssembly aplikacji, nie ma SignalR połączenia do utraty, więc możesz usunąćcatch try-blok i pozostawić wiersz, który usuwa moduł ().await module.DisposeAsync(); Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor JavaScript interoperability (JS interop).

{PATH}/JsCollocation2.razor.js:

export function showPrompt2(message) {
  return prompt(message, 'Type your name here');
}

Używanie skryptów i modułów do sortowania JS w bibliotece klas (RCL) jest obsługiwane tylko dla BlazorJS mechanizmu międzyoperacyjności opartego na interfejsie IJSRuntime Razor. Jeśli wdrażasz międzyoperację języka JavaScript[JSExport]/[JSImport], zobacz Międzyoperacja javaScript JSImport/JSExport z ASP.NET Core.Blazor

W przypadku skryptów lub modułów udostępnianych przez bibliotekę Razor klas (RCL) przy użyciu IJSRuntimemiędzyoperacyjności opartej na JS technologii jest używana następująca ścieżka:

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js

  • Segment ścieżki dla bieżącego katalogu (./) jest wymagany w celu utworzenia poprawnej statycznej ścieżki zasobów do pliku JS.
  • Symbol zastępczy {PACKAGE ID} to identyfikator pakietu biblioteki RCL (lub nazwa biblioteki dla biblioteki klas, do której odwołuje się aplikacja).
  • Symbol {PATH} zastępczy to ścieżka do składnika. Jeśli składnik Razor znajduje się w katalogu głównym biblioteki RCL, segment ścieżki nie jest uwzględniany.
  • Symbol {COMPONENT} zastępczy to nazwa składnika.
  • Symbol {EXTENSION} zastępczy pasuje do rozszerzenia składnika lub razor cshtml.

W poniższym przykładzie aplikacji platformy Blazor:

  • Identyfikator pakietu biblioteki RCL to AppJS.
  • Skrypty modułu są ładowane dla składnika JsCollocation3 (JsCollocation3.razor).
  • Składnik JsCollocation3 znajduje się w folderze Components/Pages biblioteki RCL.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

Aby uzyskać więcej informacji na temat bibliotek RCL, zobacz Korzystanie ze składników platformy ASP.NET Core Razor z biblioteki klas Razor (RCL).

Ładowanie skryptu z zewnętrznego pliku JavaScript (.js)

Umieść tagi Języka JavaScript (JS<script>...</script>) ze ścieżką źródłową skryptu (src) wewnątrz elementu zamykającego </body> po odwołaniu skryptuBlazor:

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

W przypadku symboli zastępczych w poprzednim przykładzie:

  • Symbol {BLAZOR SCRIPT} zastępczy to ścieżka skryptu Blazor i nazwa pliku. Aby uzyskać informacje o lokalizacji skryptu, zobacz ASP.NET Core project structure (Struktura projektu ASP.NET CoreBlazor).
  • Symbol zastępczy {SCRIPT PATH AND FILE NAME (.js)} to ścieżka i nazwa pliku skryptu w folderze wwwroot.

W poniższym przykładzie poprzedniego tagu <script> plik scripts.js znajduje się w folderze wwwroot/js aplikacji:

<script src="js/scripts.js"></script>

Skrypty można również udostępniać bezpośrednio z wwwroot folderu, jeśli nie chcesz przechowywać wszystkich skryptów w osobnym folderze w wwwrootobszarze :

<script src="scripts.js"></script>

Gdy plik zewnętrzny JS jest dostarczany przez bibliotekę klas Razor, określ plik JS przy użyciu stabilnej statycznej ścieżki zasobów internetowych: _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

  • Symbol zastępczy {PACKAGE ID} to identyfikator pakietu biblioteki. Identyfikator pakietu domyślnie określa nazwę zestawu projektu, jeśli tag <PackageId> nie jest określony w pliku projektu.
  • Symbol zastępczy {SCRIPT PATH AND FILE NAME (.js)} to ścieżka i nazwa pliku w folderze wwwroot.
<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

W poniższym przykładzie poprzedniego tagu <script>:

  • Biblioteka klas Razor ma nazwę zestawu ComponentLibrary, a element <PackageId> nie jest określony w pliku projektu biblioteki.
  • Plik scripts.js znajduje się w folderze wwwroot biblioteki klas.
<script src="_content/ComponentLibrary/scripts.js"></script>

Aby uzyskać więcej informacji, zobacz Korzystanie ze składników platformy ASP.NET Core Razor z biblioteki klas Razor (RCL).

Wstrzykiwanie skryptu przed uruchomieniem lub po Blazor nim

Aby upewnić się, że skrypty są ładowane przed rozpoczęciem lub po Blazor jego uruchomieniu, użyj inicjatora języka JavaScript. Aby uzyskać więcej informacji i przykładów, zobacz ASP.NET Core Blazor startup.

Wstrzykiwanie skryptu po uruchomieniu platformy Blazor

Aby wstrzyknąć skrypt po Blazor uruchomieniu, utwórz łańcuch do Promise tego wyniku z ręcznego Blazoruruchomienia . Aby uzyskać więcej informacji i przykład, zobacz ASP.NET Core Blazor startup.

Izolacja języka JavaScript w modułach języka JavaScript

Blazor umożliwia izolację języka JavaScript (JS) w JS standardowych modułach (specyfikacja ECMAScript).

Izolacja języka JS zapewnia następujące korzyści:

  • Zaimportowany kod JS nie zanieczyszcza już globalnej przestrzeni nazw.
  • Użytkownicy biblioteki i składników nie są zobowiązani do zaimportowania powiązanego kodu JS.

W scenariuszach po stronie serwera zawsze pułapka JSDisconnectedException w przypadku utraty obwodu Blazoruniemożliwia SignalR JS wywołanie międzyoperacyjne z dysponowania modułu, co powoduje nieobsługiwany wyjątek. Blazor WebAssembly aplikacje nie używają SignalR połączenia podczas JS międzyoperacjności, więc nie ma potrzeby pułapki JSDisconnectedException w Blazor WebAssembly aplikacjach do usuwania modułów.

Aby uzyskać więcej informacji, zobacz następujące zasoby: