Condividi tramite

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

JavaScript inline non è consigliato per le app Blazor. Si consiglia di utilizzare JS posizione insieme ai moduli JS.

Posizione dei tag di <script>

Inserire un tag <script> in un file di componente (.razor) solo se è garantito che il componente adotti il rendering statico lato server (SSR statico) senza spostamento avanzato . L'inserimento di un tag <script> in un file di componente non genera un avviso o un errore in fase di compilazione, ma il comportamento di caricamento degli script potrebbe non corrispondere alle aspettative nei componenti che adottano una modalità di rendering interattiva o un SSR statico con spostamento avanzato.

Non inserire un <script> tag in un file di componente (.razor) perché il <script> tag non può essere aggiornato in modo dinamico. L'inserimento di un tag <script> in un file di componente genera un errore in fase di compilazione.

Nota

Gli esempi della documentazione in genere inseriscono gli script in un tag <script> o caricano script globali da file esterni. Questi approcci appesantiscono il client con funzioni globali. Per le app di produzione, è consigliabile inserire JS in moduli 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 cliente con funzioni globali. L'inserimento JS in moduli separatiJSche 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.

Inserisci i tag JavaScript () nell'elemento di markup .

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

Nel markup dei componenti, gli script possono essere caricati tramite un componente HeadContent con il consueto avvertimento che l'approccio rallenta il caricamento della pagina nel client, che è consigliabile evitare. Quando uno script viene caricato con un componente HeadContent in un'app Blazor Server, Blazor WebAssembly app o un Blazor Web App usando una modalità di rendering interattiva (SSR interattivo, CSR) o SSR statico con navigazione avanzata, lo spostamento dalla pagina del componente rimuove il tag <script> dal contenuto <head> renderizzato, ma non disattiva il codice JavaScript dello script, inclusi i gestori eventi registrati dallo script, le variabili esposte e i metodi forniti dallo script. Solo i Blazor Web Apps che utilizzano SSR statico senza navigazione avanzata scaricano il codice JavaScript quando l'utente lascia la pagina. In genere, è preferibile aggiungere tag <script> al contenuto fisico <head>, a meno che non si desideri esplicitamente mantenere tali riferimenti di script nei componenti che li utilizzano e non si preoccupi che il codice non venga scaricato durante gli eventi di navigazione.

Nel markup dei componenti, gli script possono essere caricati tramite un componente HeadContent con il consueto avvertimento che l'approccio rallenta il caricamento della pagina nel client, che è consigliabile evitare. Quando uno script viene caricato con un componente HeadContent, navigare via dalla pagina del componente rimuove il tag <script> dal contenuto reso <head>, ma non scarica il codice JavaScript dello script, inclusi i gestori di eventi registrati, le variabili esposte e i metodi forniti dallo script. In genere, è preferibile aggiungere tag <script> al contenuto fisico <head>, a meno che non si desideri esplicitamente mantenere tali riferimenti di script nei componenti che li utilizzano e non si preoccupi che il codice non venga scaricato durante gli eventi di navigazione.

Caricare uno script nel markup <body>

Inserisci i tag JavaScript () all'interno dell'elemento di chiusura dopo il 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, consultare la struttura del progetto ASP.NET Core.

Carica uno script da un file JavaScript esterno (.js) collocato insieme a 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. Lo smaltimento dei componenti, presente nel secondo esempio, viene trattato nel rilascio del componente Razor di ASP.NET Core.

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 Task ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

Il file collocato JS viene posizionato accanto al file componente JsCollocation1 con il nome del file JsCollocation1.razor.js. JsCollocation1 Nel componente viene fatto riferimento allo script nel percorso del file collocato. Nell'esempio seguente, la funzione showPrompt1 accetta il nome dell'utente da un Window prompt() e lo restituisce al componente JsCollocation1 per la 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 JsCollocation2 seguente carica un modulo JS in module, che è un'istanza della classe componente IJSObjectReference. 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 Task 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 in cui il circuito Blazor venga perso SignalR. Se il codice precedente viene usato in un'app Blazor WebAssembly, non c'è alcuna SignalR connessione da perdere, quindi è possibile rimuovere il try-catch blocco e lasciare la riga che libera il modulo (await module.DisposeAsync();). Per ulteriori informazioni, vedere ASP.NET Core interoperabilità JavaScript (interop).

{PATH}/JsCollocation2.razor.js:

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

Importante

Non inserire un tag <script> per JsCollocation2.razor.js dopo lo script Blazor perché il modulo viene caricato e memorizzato nella cache automaticamente quando viene richiamato il import() dinamico.

L'uso di script e moduli per la collocazione JS in una Razor libreria di classi (RCL) è supportato solo per il meccanismo di interoperabilità di BlazorJS basato sull'interfaccia IJSRuntime. Se stai implementando l'interoperabilità JavaScript [JSImport]/[JSExport], vedi JavaScript JSImport/JSExport interop 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 (./) è indispensabile per creare correttamente il percorso dell'asset statico al 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 () () con un percorso di origine script () all'interno dell'elemento di chiusura dopo il 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 struttura del progetto ASP.NET 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 Razor libreria di classi, 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 avvio di ASP.NET Core.

Inserire uno script dopo l'avvio di Blazor

Per inserire uno script dopo che Blazor è avviato, concatenare a Promise che risulta da un avvio manuale di Blazor. Per ulteriori informazioni e un esempio, vedere ASP.NET Core startup.

Isolamento di JavaScript nei moduli di JavaScript

abilita l'isolamento di JavaScript () nei moduli standard (specifica ECMAScript).

L'isolamento di JS offre i vantaggi seguenti:

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

Negli scenari lato server, intercetta sempre JSDisconnectedException nel caso in cui la perdita del circuito di Blazor impedisca a una chiamata di interoperabilità JS di eliminare un modulo, causando 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: