daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/blazor/javascript-interoperability/location-of-javascript.md

8.7 KiB
Raw Blame History

title author description monikerRange ms.author ms.custom ms.date uid
JavaScript location in ASP.NET Core Blazor apps guardrex Learn where to place and how to load JavaScript in Blazor apps. >= aspnetcore-3.1 riande mvc 02/09/2024 blazor/js-interop/javascript-location

JavaScript location in ASP.NET Core Blazor apps

[!INCLUDE]

Load JavaScript (JS) code using any of the following approaches:

:::moniker range=">= aspnetcore-6.0"

:::moniker-end

:::moniker range="< aspnetcore-6.0"

:::moniker-end

:::moniker range=">= aspnetcore-8.0"

[!WARNING] Only place a <script> tag in a component file (.razor) if the component is guaranteed to adopt static server-side rendering (static SSR) because the <script> tag can't be updated dynamically.

:::moniker-end

:::moniker range="< aspnetcore-8.0"

[!WARNING] Don't place a <script> tag in a component file (.razor) because the <script> tag can't be updated dynamically.

:::moniker-end

:::moniker range=">= aspnetcore-5.0"

[!NOTE] Documentation examples usually place scripts in a <script> tag or load global scripts from external files. These approaches pollute the client with global functions. For production apps, we recommend placing JS into separate JS modules that can be imported when needed. For more information, see the JavaScript isolation in JavaScript modules section.

:::moniker-end

:::moniker range="< aspnetcore-5.0"

[!NOTE] Documentation examples place scripts into a <script> tag or load global scripts from external files. These approaches pollute the client with global functions. Placing JS into separate JS modules that can be imported when needed is not supported in Blazor earlier than ASP.NET Core 5.0. If the app requires the use of JS modules for JS isolation, we recommend using ASP.NET Core 5.0 or later to build the app. For more information, use the Version dropdown list to select a 5.0 or later version of this article and see the JavaScript isolation in JavaScript modules section.

:::moniker-end

Load a script in <head> markup

The approach in this section isn't generally recommended.

Place the JavaScript (JS) tags (<script>...</script>) in the <head> element markup:

<head>
    ...

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

Loading JS from the <head> isn't the best approach for the following reasons:

  • JS interop may fail if the script depends on Blazor. We recommend loading scripts using one of the other approaches, not via the <head> markup.
  • The page may become interactive slower due to the time it takes to parse the JS in the script.

Load a script in <body> markup

Place the JavaScript tags (<script>...</script>) inside the closing </body> element after the Blazor script reference:

<body>
    ...

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

In the preceding example, the {BLAZOR SCRIPT} placeholder is the Blazor script path and file name. For the location of the script, see xref:blazor/project-structure#location-of-the-blazor-script.

:::moniker range=">= aspnetcore-6.0"

Load a script from an external JavaScript file (.js) collocated with a component

[!INCLUDE]

For more information on RCLs, see xref:blazor/components/class-libraries.

:::moniker-end

Load a script from an external JavaScript file (.js)

Place the JavaScript (JS) tags (<script>...</script>) with a script source (src) path inside the closing </body> element after the Blazor script reference:

<body>
    ...

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

In the preceding example:

In the following example of the preceding <script> tag, the scripts.js file is in the wwwroot/js folder of the app:

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

You can also serve scripts directly from the wwwroot folder if you prefer not to keep all of your scripts in a separate folder under wwwroot:

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

When the external JS file is supplied by a Razor class library, specify the JS file using its stable static web asset path: ./_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

  • The path segment for the current directory (./) is required in order to create the correct static asset path to the JS file.
  • The {PACKAGE ID} placeholder is the library's package ID. The package ID defaults to the project's assembly name if <PackageId> isn't specified in the project file.
  • The {SCRIPT PATH AND FILE NAME (.js)} placeholder is the path and file name under wwwroot.
<body>
    ...

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

In the following example of the preceding <script> tag:

  • The Razor class library has an assembly name of ComponentLibrary, and a <PackageId> isn't specified in the library's project file.
  • The scripts.js file is in the class library's wwwroot folder.
<script src="./_content/ComponentLibrary/scripts.js"></script>

For more information, see xref:blazor/components/class-libraries.

:::moniker range=">= aspnetcore-6.0"

Inject a script before or after Blazor starts

To ensure scripts load before or after Blazor starts, use a JavaScript initializer. For more information and examples, see xref:blazor/fundamentals/startup#javascript-initializers.

:::moniker-end

:::moniker range="< aspnetcore-6.0"

Inject a script after Blazor starts

To inject a script after Blazor starts, chain to the Promise that results from a manual start of Blazor. For more information and an example, see xref:blazor/fundamentals/startup#inject-a-script-after-blazor-starts.

:::moniker-end

JavaScript isolation in JavaScript modules

Blazor enables JavaScript (JS) isolation in standard JS modules (ECMAScript specification).

JS isolation provides the following benefits:

  • Imported JS no longer pollutes the global namespace.
  • Consumers of a library and components aren't required to import the related JS.

For more information, see xref:blazor/js-interop/call-javascript-from-dotnet#javascript-isolation-in-javascript-modules.

Dynamic import with the import() operator is supported with ASP.NET Core and Blazor:

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

In the preceding example, the {CONDITION} placeholder represents a conditional check to determine if the module should be loaded.

For browser compatibility, see Can I use: JavaScript modules: dynamic import.