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ą, zapoznaj się z wersją tego artykułu platformy .NET 8.

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ą, zapoznaj się z wersją tego artykułu platformy .NET 8.

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 osobnychJSmoduł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ą HeadContentIJSRuntime.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). Blazor W aplikacji internetowej (.NET 8 lub nowszej) 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ż 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.OnAfterRenderAsyncJsCollocation2 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. Blazor W aplikacji internetowej (.NET 8 lub nowszej) 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)
        {
            await module.DisposeAsync();
        }
    }
}

{PATH}/JsCollocation2.razor.js:

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

W przypadku skryptów lub modułów udostępnianych przez bibliotekę Razor klas (RCL) używana jest następująca ścieżka:

_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.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 razorcshtml.

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 powyższym 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)}:

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

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

Importowanie dynamiczne za pomocą import() operatora jest obsługiwane w przypadku platformy ASP.NET Core i Blazor:

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

W poprzednim przykładzie symbol zastępczy reprezentuje sprawdzanie warunkowe, aby określić, {CONDITION} czy moduł powinien zostać załadowany.

Aby uzyskać informacje o zgodności przeglądarki, zobacz Czy mogę używać: moduły JavaScript: import dynamiczny.