Использование Razor компонентов в приложениях JavaScript и платформах SPA

В этой статье описывается, как отрисовка Razor компонентов из JavaScript, использование Blazor пользовательских элементов и создание компонентов Angular и React.

Примечание.

Мы рекомендуем использовать blazor.server.js скрипты (Blazor Server) и blazor.webassembly.js (Blazor WebAssembly) при интеграции Razor компонентов в существующее приложение JavaScript, пока не будет добавлена поддержка blazor.web.js скрипта (Blazor Web App) в будущем. Дополнительные сведения см. в статье RegisterCustomElement, остановленной в Blazor 8 (dotnet/aspnetcore No 53920).

Примеры приложений Angular

• CustomElementsBlazorSample (Blazor Serverjaviercn/CustomElementsBlazorSample, branch: blazor-server): Blazor Server поддерживается в .NET 8/9. Сведения о переносе этого примера .NET 7 см. в разделе "Миграция с ASP.NET Core 7.0 на 8.0 " и переход с ASP.NET Core в .NET 8 на ASP.NET Core в .NET 9.
• CustomElementsBlazorSample (Blazor WebAssembly) (javiercn/CustomElementsBlazorSample, branch: blazor-wasm): Чтобы перенести этот пример .NET 7, см. раздел "Миграция с ASP.NET Core 7.0 на 8.0 " и переход с ASP.NET Core в .NET 8 на ASP.NET Core в .NET 9.

Отрисовка компонентов Razor из JavaScript

Компоненты Razor можно динамически отрисовать из JavaScript (JS) для существующих приложений JS.

Пример в этом разделе отображает следующий Razor компонент на странице.JS

Quote.razor:

<div class="m-5 p-5">
    <h2>Quote</h2>
    <p>@Text</p>
</div>

@code {
    [Parameter]
    public string? Text { get; set; }
}

Program В файле добавьте пространство имен для расположения компонента.

Вызовите RegisterForJavaScript корневую Razor коллекцию компонентов приложения, чтобы зарегистрировать компонент в качестве корневого компонента для JS отрисовки.

RegisterForJavaScript включает перегрузку, которая принимает имя JS функции, выполняющей логику инициализации (javaScriptInitializer). Функция JS вызывается один раз на каждую регистрацию компонента сразу после Blazor запуска приложения и перед отображением всех компонентов. Эту функцию можно использовать для интеграции с JS технологиями, такими как пользовательские элементы HTML или JSплатформа SPA на основе HTML.

Одну или несколько функций инициализатора можно создавать и вызывать различными регистрациями компонентов. Типичным вариантом использования является повторное использование одной функции инициализатора для нескольких компонентов, которое ожидается, если функция инициализатора настраивает интеграцию с пользовательскими элементами или другой JSплатформой SPA.

Внимание

Не путайте javaScriptInitializer параметр RegisterForJavaScript с инициализаторами JavaScript. Имя параметра и функция инициализаторов JS совпадает.

В следующем примере показана динамическая регистрация предыдущего Quote компонента с "quote" в качестве идентификатора.

• Blazor Server В приложении измените вызов AddServerSideBlazor в Program файле:

  builder.Services.AddServerSideBlazor(options =>
  {
      options.RootComponents.RegisterForJavaScript<Quote>(identifier: "quote", 
          javaScriptInitializer: "initializeComponent");
  });
  

• Blazor WebAssembly В приложении вызовите RegisterForJavaScript RootComponents в клиентском Program файле:

  builder.RootComponents.RegisterForJavaScript<Quote>(identifier: "quote", 
      javaScriptInitializer: "initializeComponent");
  

Подключите функцию инициализатора с name параметрами функции и parameters параметров функции к объекту window . Для демонстрационных целей следующая initializeComponent функция регистрирует имя и параметры зарегистрированного компонента.

wwwroot/jsComponentInitializers.js:

window.initializeComponent = (name, parameters) => {
  console.log({ name: name, parameters: parameters });
}

Отрисовка компонента в JS элемент контейнера с помощью зарегистрированного идентификатора, передавая параметры компонента по мере необходимости.

В следующем примере :

• Компонент Quote (quote идентификатор) отображается в quoteContainer элементе при вызове showQuote функции.
• Строка кавычки передается параметру компонента Text .

wwwroot/scripts.js:

window.showQuote = async () => {
  let targetElement = document.getElementById('quoteContainer');
  await Blazor.rootComponents.add(targetElement, 'quote', 
  {
    text: "Crow: I have my doubts that this movie is actually 'starring' " +
      "anybody. More like, 'camera is generally pointed at.'"
  });
}

const btn = document.querySelector("#showQuoteBtn");
btn.addEventListener("click", showQuote);

После загрузки скрипта Blazor загрузите предыдущие скрипты в JS приложение:

<script src="_framework/{BLAZOR SCRIPT}"></script>
<script src="jsComponentInitializers.js"></script>
<script src="scripts.js"></script>

В предыдущем примере {BLAZOR SCRIPT} заполнитель — Blazor это скрипт.

В HTML поместите целевой элемент контейнера (quoteContainer). Для демонстрации в этом разделе кнопка активирует отрисовку Quote компонента, вызвав функцию showQuoteJS :

<button id="showQuoteBtn">Show Quote</button>

<div id="quoteContainer"></div>

При инициализации перед отображением всех компонентов консоль средств разработчика браузера регистрирует Quote идентификатор компонента (name) и параметры (parameters) при initializeComponent вызове:

Object { name: "quote", parameters: (1) […] }
  name: "quote"
  parameters: Array [ {…} ]
    0: Object { name: "Text", type: "string" }
    length: 1

Show Quote При выборе кнопки компонент отображается с кавычками, Quote хранящимися в Text отображении:

Цитата ©1988-1999 Спутник любви LLC: Тайна научного театра 3000 (Трасса Beaulieu (ворона))

Примечание.

rootComponents.add возвращает экземпляр компонента. Вызовите dispose экземпляр, чтобы освободить его:

const rootComponent = await window.Blazor.rootComponents.add(...);

...

rootComponent.dispose();

В предыдущем примере динамически отрисовывает корневой компонент при вызове showQuote()JS функции. Чтобы отобразить корневой компонент в элемент контейнера при Blazor запуске, используйте инициализатор JavaScript для отрисовки компонента, как показано в следующем примере.

Следующий пример основан на предыдущем примере, используя Quote компонент, регистрацию корневого компонента в Program файле и инициализацию jsComponentInitializers.js. Функция showQuote() (и script.js файл) не используются.

В HTML поместите целевой элемент контейнера в quoteContainer2 следующем примере:

<div id="quoteContainer2"></div>

С помощью инициализатора JavaScript добавьте корневой компонент в целевой элемент контейнера.

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js:

export function afterStarted(blazor) {
  let targetElement = document.getElementById('quoteContainer2');
  blazor.rootComponents.add(targetElement, 'quote',
    {
      text: "Crow: I have my doubts that this movie is actually 'starring' " +
          "anybody. More like, 'camera is generally pointed at.'"
    });
}

Примечание.

Для вызова rootComponents.addиспользуйте blazor параметр (нижний регистр b), предоставленный событием Blazor начала. Хотя регистрация допустима при использовании Blazor объекта (в верхнем регистре B), предпочтительный подход — использовать параметр.

Дополнительные примеры с дополнительными функциями см. в примере в BasicTestApp источнике ссылок ASP.NET Core (dotnet/aspnetcore репозиторий GitHub):

• JavaScriptRootComponents.razor
• wwwroot/js/jsRootComponentInitializers.js
• wwwroot/index.html

Примечание.

По ссылкам в документации на справочные материалы по .NET обычно загружается ветвь репозитория по умолчанию, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для определенного выпуска, используйте раскрывающийся список Switch branches or tags (Переключение ветвей или тегов). Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Пользовательские элементы Blazor

Используйте Blazor настраиваемые элементы для динамической отрисовки Razor компонентов из других платформ SPA, таких как Angular или React.

Blazor настраиваемые элементы:

• Используйте стандартные HTML-интерфейсы для реализации пользовательских ЭЛЕМЕНТОВ HTML.
• Исключите необходимость вручную управлять состоянием и жизненным циклом корневых Razor компонентов с помощью API JavaScript.
• Полезны для постепенного внедрения Razor компонентов в существующие проекты, написанные на других платформах SPA.

Пользовательские элементы не поддерживают дочерний контент или компоненты шаблонов.

Имя элемента

В спецификации HTML имена тегов пользовательских элементов должны принимать регистр kebab:

❌Недопустимый: mycounter
❌Недопустимый: MY-COUNTER
❌Недопустимый: MyCounter
✔️Действительный: my-counter
✔️Действительный: my-cool-counter

Пакет

Добавьте ссылку на пакет Microsoft.AspNetCore.Components.CustomElements в файл проекта приложения.

Примечание.

Рекомендации по добавлению пакетов в приложения .NET см. в разделе Способы установки пакетов NuGet в статье Рабочий процесс использования пакета (документация по NuGet). Проверьте правильность версий пакета на сайте NuGet.org.

Пример компонента

Следующие примеры основаны на Counter компоненте Blazor из шаблона проекта.

Counter.razor:

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

Blazor Server регистрация

Выполните следующие действия, чтобы зарегистрировать корневой компонент в качестве пользовательского Blazor Server элемента в приложении.

Microsoft.AspNetCore.Components.Web Добавьте пространство имен в начало Program файла:

using Microsoft.AspNetCore.Components.Web;

Добавьте пространство имен для компонентов приложения. В следующем примере пространство имен приложения находится BlazorSample в папке Pages .

using BlazorSample.Pages;

Измените вызов AddServerSideBlazor. Укажите пользовательский элемент с RegisterCustomElement параметром RootComponents канала. В следующем примере компонент регистрируется Counter с помощью пользовательского HTML-элемента my-counter:

builder.Services.AddServerSideBlazor(options =>
{
    options.RootComponents.RegisterCustomElement<Counter>("my-counter");
});

Blazor WebAssembly регистрация

Выполните следующие действия, чтобы зарегистрировать корневой компонент в качестве пользовательского Blazor WebAssembly элемента в приложении.

Microsoft.AspNetCore.Components.Web Добавьте пространство имен в начало Program файла:

using Microsoft.AspNetCore.Components.Web;

Добавьте пространство имен для компонентов приложения. В следующем примере пространство имен приложения находится BlazorSample в папке Pages .

using BlazorSample.Pages;

RootComponentsЗвонокRegisterCustomElement. В следующем примере компонент регистрируется Counter с помощью пользовательского HTML-элемента my-counter:

builder.RootComponents.RegisterCustomElement<Counter>("my-counter");

Использование зарегистрированного пользовательского элемента

Используйте пользовательский элемент на любой веб-платформе. Например, предыдущий my-counter пользовательский HTML-элемент, отображающий компонент приложения Counter , используется в приложении React со следующей разметкой:

<my-counter></my-counter>

Полный пример создания пользовательских элементов с Blazorпомощью см CustomElementsComponent . в компоненте в справочном источнике.

Примечание.

По ссылкам в документации на справочные материалы по .NET обычно загружается ветвь репозитория по умолчанию, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для определенного выпуска, используйте раскрывающийся список Switch branches or tags (Переключение ветвей или тегов). Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Передача параметров

Передайте параметры компоненту Razor как атрибуты HTML, так и как свойства JavaScript в элементе DOM.

Counter Следующий компонент использует IncrementAmount параметр для задания добавочного количества кнопкиClick me.

Counter.razor:

@page "/counter"

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    [Parameter]
    public int IncrementAmount { get; set; } = 1;

    private void IncrementCount()
    {
        currentCount += IncrementAmount;
    }
}

Отрисуйте Counter компонент с помощью пользовательского элемента и передайте значение IncrementAmount параметру в качестве атрибута HTML. Имя атрибута принимает синтаксис kebab-case (increment-amountне IncrementAmount):

<my-counter increment-amount="10"></my-counter>

Кроме того, можно задать значение параметра в качестве свойства JavaScript в объекте элемента. Имя свойства принимает синтаксис регистра верблюда (incrementAmountне IncrementAmount):

const elem = document.querySelector("my-counter");
elem.incrementAmount = 10;

Значения параметров можно обновлять в любое время с помощью синтаксиса атрибута или свойства.

Поддерживаемые типы параметров:

• С помощью синтаксиса свойств JavaScript можно передавать объекты любого сериализуемого типа JSON.
• Использование атрибутов HTML ограничивается передачей объектов строк, логических или числовых типов.

Создание компонентов Angular и React

Создавать компоненты JavaScript (JS), характерные для платформы, можно из компонентов Razor для веб-платформ, таких как Angular или React. Эта возможность не включена в .NET, но включена в поддержку компонентов отрисовкиRazor.JS В примере создания компонента JS в GitHub демонстрируется создание компонентов Angular и React из компонентов Razor. Дополнительные сведения см. в файле README.md примера приложения на GitHub.

Предупреждение

Сейчас функции компонентов Angular и React являются экспериментальными, неподдерживаемыми и могут быть в любое время изменены или удалены. Мы ждем ваших отзывов о том, насколько этот подход соответствует вашим требованиям.