Condividi tramite

Percorso JavaScript nelle app ASP.NET Core Blazor

  • Articolo

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere i criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Caricare il codice JavaScript (JS) usando uno degli approcci seguenti:

Avviso

Inserire un <script> tag in un file di componente (.razor) solo se il componente deve adottare il rendering statico lato server (SSR statico) perché il <script> tag non può essere aggiornato in modo dinamico.

Avviso

Non inserire un <script> tag in un file di componente (.razor) perché il <script> tag non può essere aggiornato in modo dinamico.

Nota

Gli esempi della documentazione in genere inseriscono gli script in un tag <script> o caricano script globali da file esterni. Questi approcci inquinano il client con funzioni globali. Per le app di produzione, è consigliabile inserire JS in moduli separati JS che possono essere importati quando necessario. Per altre informazioni, vedere la sezione Isolamento di JavaScript nei moduli JavaScript.

Nota

Gli esempi della documentazione inseriscono gli script in un tag <script> o caricano script globali da file esterni. Questi approcci inquinano il client con funzioni globali. L'inserimento JS in moduli separatiJS che possono essere importati quando necessario non è supportato in Blazor versioni precedenti a ASP.NET Core 5.0. Se l'app richiede l'uso di moduli JS per l'isolamento di JS, è consigliabile usare ASP.NET Core 5.0 o versione successiva per compilare l'app. Per altre informazioni, usare l'elenco a discesa Versione per selezionare la versione 5.0 o successiva di questo articolo e vedere la sezione Isolamento di JavaScript nei moduli di JavaScript.

Caricare uno script nel markup <head>

L'approccio descritto in questa sezione in genere non è consigliato.

Inserire i tag JavaScript () (<script>...</script>) nel markup dell'elemento<head>:JS

<head>
    ...

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

Il caricamento di JS da <head> non è l'approccio migliore per i motivi seguenti:

  • L'interoperabilità JS può avere esito negativo se lo script dipende da Blazor. È consigliabile caricare gli script usando uno degli altri approcci, non tramite il markup <head>.
  • La pagina potrebbe diventare interattiva più lentamente a causa del tempo necessario per analizzare il codice JS nello script.

Caricare uno script nel markup <body>

Inserire i tag JavaScript (<script>...</script>) all'interno dell'elemento di chiusura </body> dopo il Blazor riferimento allo script:

<body>
    ...

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

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere ASP.NET Struttura del progetto CoreBlazor.

Caricare uno script da un file JavaScript esterno (.js) con il percorso condiviso con un componente

La collocazione dei file JavaScript (JS) per Razor i componenti è un modo pratico per organizzare gli script in un'app.

Razor i componenti delle Blazor app collocano JS i file usando l'estensione .razor.js e sono indirizzabili pubblicamente usando il percorso del file nel progetto:

{PATH}/{COMPONENT}.razor.js

  • Il {PATH} segnaposto è il percorso del componente.
  • Il {COMPONENT} segnaposto è il componente.

Quando l'app viene pubblicata, il framework sposta automaticamente lo script nella radice Web. Gli script vengono spostati in bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js, dove i segnaposto sono:

Non è necessaria alcuna modifica all'URL relativo dello script, in quanto Blazor si occupa di inserire automaticamente il JS file in asset statici pubblicati.

Questa sezione e gli esempi seguenti sono incentrati principalmente sulla spiegazione della collocazione JS dei file. Il primo esempio illustra un file collocato JS con una funzione comune JS . Il secondo esempio illustra l'uso di un modulo per caricare una funzione, che è l'approccio consigliato per la maggior parte delle app di produzione. La chiamata JS da .NET è descritta in Chiamare le funzioni JavaScript dai metodi .NET in ASP.NET Core Blazor, dove sono disponibili altre spiegazioni dell'API BlazorJS con altri esempi. L'eliminazione dei componenti, presente nel secondo esempio, è descritta in ASP.NET ciclo di vita del componente CoreRazor.

Il componente seguente JsCollocation1 carica uno script tramite un HeadContent componente e chiama una JS funzione con IJSRuntime.InvokeAsync. Il {PATH} segnaposto è il percorso del componente.

Importante

Se si usa il codice seguente per una dimostrazione in un'app di test, modificare il {PATH} segnaposto nel percorso del componente , ad esempio Components/Pages in .NET 8 o versione successiva o Pages in .NET 7 o versioni precedenti. In ( Blazor Web App .NET 8 o versione successiva), il componente richiede una modalità di rendering interattiva applicata a livello globale all'app o alla definizione del componente.

Aggiungere lo script seguente dopo lo Blazor script (percorso dello Blazor script iniziale):

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

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

Il file collocato JS viene posizionato accanto al file del JsCollocation1 componente con il nome JsCollocation1.razor.jsdel file . JsCollocation1 Nel componente viene fatto riferimento allo script nel percorso del file collocato. Nell'esempio seguente la showPrompt1 funzione accetta il nome dell'utente da un Window prompt() oggetto e la restituisce al componente per la JsCollocation1 visualizzazione.

{PATH}/JsCollocation1.razor.js:

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

L'approccio precedente non è consigliato per l'uso generale nelle app di produzione perché l'approccio inquina il client con funzioni globali. Un approccio migliore per le app di produzione consiste nell'usare JS i moduli. Gli stessi principi generali si applicano al caricamento di un JS modulo da un file collocato JS , come illustrato nell'esempio seguente.

Il metodo del componente seguente JsCollocation2 carica un JS modulo in module, che è un IJSObjectReference elemento della classe OnAfterRenderAsync componente. module viene usato per chiamare la showPrompt2 funzione . Il {PATH} segnaposto è il percorso del componente.

Importante

Se si usa il codice seguente per una dimostrazione in un'app di test, modificare il {PATH} segnaposto nel percorso del componente. In ( Blazor Web App .NET 8 o versione successiva), il componente richiede una modalità di rendering interattiva applicata a livello globale all'app o alla definizione del componente.

JsCollocation2 componente ({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)
            {
            }
        }
    }
}

Nell'esempio precedente, JSDisconnectedException viene intrappolato durante l'eliminazione del modulo nel caso Blazorin cui il circuito venga SignalR perso. Se il codice precedente viene usato in un'appBlazor WebAssembly, non c'è alcuna SignalR connessione da perdere, quindi è possibile rimuovere ilcatch try-blocco e lasciare la riga che elimina il modulo ().await module.DisposeAsync(); Per altre informazioni, vedere ASP.NET Core JavaScript interoperabilità (interoperabilità).For more information, see ASP.NET Core Blazor JavaScript interoperability (JS interop).

{PATH}/JsCollocation2.razor.js:

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

L'uso di script e moduli per la collocazione JS in una Razor libreria di classi (RCL) è supportato solo per Blazoril meccanismo di JS interoperabilità basato sull'interfaccia IJSRuntime . Se si implementa l'interoperabilità JavaScript, vedere Interoperabilità JAVAScript [JSImport][JSExport]/JSImport/JSExport con ASP.NET Core.Blazor

Per gli script o i moduli forniti da una Razor libreria di classi (RCL) usando IJSRuntimel'interoperabilità basata su JS , viene usato il percorso seguente:

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

  • Il segmento di percorso per la directory corrente (./) è necessario per creare il percorso dell'asset statico corretto del file JS.
  • Il segnaposto {PACKAGE ID} è l'identificatore del pacchetto della libreria RCL (o il nome della libreria per una libreria di classi a cui fa riferimento l'app).
  • Il {PATH} segnaposto è il percorso del componente. Se un componente Razor si trova nella radice della libreria RCL, il segmento di percorso non è incluso.
  • Il {COMPONENT} segnaposto è il nome del componente.
  • Il {EXTENSION} segnaposto corrisponde all'estensione del componente, razor o cshtml.

Nell'esempio di app Blazor seguente:

  • L'identificatore del pacchetto della libreria RCL è AppJS.
  • Gli script di un modulo vengono caricati per il componente JsCollocation3 (JsCollocation3.razor).
  • Il componente JsCollocation3 si trova nella cartella Components/Pages della libreria RCL.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

Per altre informazioni sulle librerie RCL, vedere Utilizzare i componenti ASP.NET Core Razor di una libreria di classi Razor (RCL).

Caricare uno script da un file JavaScript esterno (.js)

Inserire i tag JavaScript () (<script>...</script>JS) con un percorso di origine script (src) all'interno dell'elemento di chiusura </body> dopo il Blazor riferimento allo script:

<body>
    ...

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

Per i segnaposto nell'esempio precedente:

  • Il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere ASP.NET Struttura del progetto CoreBlazor.
  • Il segnaposto {SCRIPT PATH AND FILE NAME (.js)} corrisponde al percorso e al nome del file di script in wwwroot.

Nell'esempio seguente del tag <script> precedente, il file scripts.js si trova nella cartella wwwroot/js dell'app:

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

È anche possibile gestire gli script direttamente dalla wwwroot cartella se si preferisce non mantenere tutti gli script in una cartella wwwrootseparata in :

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

Quando il file JS esterno viene fornito da una libreria di classi Razor, specificare il file JS usando il percorso dell'asset Web statico stabile: _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

  • Il segnaposto {PACKAGE ID} è l'ID pacchetto della libreria. Per impostazione predefinita, l'ID pacchetto è il nome dell'assembly del progetto, se <PackageId> non è specificato nel file di progetto.
  • Il segnaposto {SCRIPT PATH AND FILE NAME (.js)} corrisponde al percorso e al nome del file in wwwroot.
<body>
    ...

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

Nell'esempio seguente del tag <script> precedente:

  • La libreria di classi Razor ha il nome assembly ComponentLibrary e nel file di progetto della libreria l'elemento <PackageId> non è specificato.
  • Il file scripts.js si trova nella cartella wwwroot della libreria di classi.
<script src="_content/ComponentLibrary/scripts.js"></script>

Per altre informazioni, vedere Utilizzare i componenti ASP.NET Core Razor di una libreria di classi Razor (RCL).

Inserire uno script prima o dopo Blazor l'avvio

Per assicurarsi che gli script vengano caricati prima o dopo Blazor l'avvio, usare un inizializzatore JavaScript. Per altre informazioni ed esempi, vedere ASP.NET avvio di CoreBlazor.

Inserire uno script dopo l'avvio di Blazor

Per inserire uno script dopo Blazor l'avvio, concatenare l'oggetto Promise risultante da un inizio manuale di Blazor. Per altre informazioni e un esempio, vedere ASP.NET avvio di CoreBlazor.

Isolamento di JavaScript nei moduli di JavaScript

Blazorabilita l'isolamento JavaScript (JS) nei moduli standard JS (specifica ECMAScript).

L'isolamento di JS offre i vantaggi seguenti:

  • Il codice JS importato non inquina più lo spazio dei nomi globale.
  • I consumer di una libreria e dei componenti non devono importare il codice JS correlato.

Negli scenari lato server, intercettare JSDisconnectedException sempre in caso di perdita del Blazorcircuito impedisce SignalR a una JS chiamata di interoperabilità di eliminare un modulo, che comporta un'eccezione non gestita. Blazor WebAssembly le app non usano una SignalR connessione durante JS l'interoperabilità, quindi non è necessario intercettare JSDisconnectedException le Blazor WebAssembly app per l'eliminazione dei moduli.

Per ulteriori informazioni, vedi le seguenti risorse: