JavaScript 앱 및 SPA 프레임워크에서 구성 요소 사용 Razor

이 문서에서는 JavaScript에서 구성 요소를 렌더링 Razor 하고, 사용자 지정 요소를 사용하고 Blazor , Angular 및 React 구성 요소를 생성하는 방법을 설명합니다.

참고 항목

() 스크립트에 대한 blazor.web.js 더 나은 지원이 나중에 추가될 때까지 구성 요소를 기존 JavaScript 앱에 통합 Razor 할 때 () 및 blazor.webassembly.jsBlazor WebAssembly(Blazor Web App) 스크립트를 사용하는 blazor.server.jsBlazor Server것이 좋습니다. 자세한 내용은 RegisterCustomElement가 8(dotnet/aspnetcore#53920)에서 Blazor 작동 중지됨을 참조하세요.

Angular 샘플 앱

• CustomElementsBlazorSample(Blazor Server) (javiercn/CustomElementsBlazorSample, 분기: blazor-server): Blazor Server .NET 8에서 지원됩니다. 이 .NET 7 샘플을 .NET 8로 마이그레이션하려면 ASP.NET Core 7.0에서 8.0으로 마이그레이션을 참조 하세요.
• CustomElementsBlazorSample() (javiercn/CustomElementsBlazorSampleBlazor WebAssembly, 분기: blazor-wasm): 이 .NET 7 샘플을 .NET 8로 마이그레이션하려면 ASP.NET Core 7.0에서 8.0으로 마이그레이션을 참조하세요.

JavaScript에서 Razor 구성 요소 렌더링

Razor 구성 요소는 기존 JS 앱에 대한 JS(JavaScript)에서 동적으로 렌더링될 수 있습니다.

이 섹션의 예제에서는 JS를 통해 다음 Razor 구성 요소를 페이지로 렌더링합니다.

Quote.razor:

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

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

파일에서 Program 구성 요소의 위치에 대한 네임스페이스를 추가합니다.

앱의 루트 구성 요소 컬렉션을 호출 RegisterForJavaScript 하여 렌더링을 위한 JS 루트 구성 요소로 구성 요소를 등록 Razor 합니다.

RegisterForJavaScript에는 초기화 논리(javaScriptInitializer)를 실행하는 JS 함수의 이름을 허용하는 오버로드가 포함되어 있습니다. JS 함수는 Blazor 앱이 시작된 직후 및 구성 요소가 렌더링되기 직전에 구성 요소 등록당 한 번 호출됩니다. 이 함수는 HTML 사용자 지정 요소 또는 JS 기반 SPA 프레임워크와 같은 JS 기술과 통합하는 데 사용할 수 있습니다.

다른 구성 요소 등록에서 하나 이상의 이니셜라이저 함수를 만들고 호출할 수 있습니다. 일반적인 사용 사례는 이니셜라이저 함수가 사용자 지정 요소 또는 다른 JS 기반 SPA 프레임워크와의 통합을 구성하는 경우, 예상되는 여러 구성 요소에 대해 동일한 이니셜라이저 함수를 다시 사용하는 것입니다.

Important

RegisterForJavaScript의 javaScriptInitializer 매개 변수를 JavaScript 이니셜라이저와 혼동하지 마세요. 매개 변수 및 JS 이니셜라이저 기능의 이름은 일치합니다.

다음 예제에서는 식별자로 "quote"를 사용하여 이전 Quote 구성 요소의 동적 등록을 보여줍니다.

• 앱에서 Blazor Server 파일의 호출을 AddServerSideBlazor 수정합니다 Program .

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

• 앱에서 Blazor WebAssembly 클라이언트 쪽 Program 파일에서 호출 RegisterForJavaScript RootComponents 합니다.

  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 식별자)는 showQuote 함수가 호출될 때 quoteContainer 요소로 렌더링됩니다.
• Quote 문자열이 구성 요소의 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)를 배치합니다. 이 섹션의 데모에서는 단추가 showQuoteJS 함수를 호출하여 Quote 구성 요소 렌더링을 트리거합니다.

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

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

구성 요소를 렌더링하기 전에 초기화할 때, 브라우저의 개발자 도구 콘솔은 initializeComponent가 호출될 때 Quote 구성 요소의 식별자(name) 및 매개 변수(parameters)를 기록합니다.

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

Show Quote 단추를 선택하면 Quote 구성 요소가 표시된 Text에 저장된 Quote로 렌더링됩니다.

Quote ©1988-1999 Satellite of Love LLC: Mystery Science Theater 3000 (Trace Beaulieu (Crow))

참고 항목

rootComponents.add은 구성 요소의 인스턴스를 반환합니다. 인스턴스에서 dispose를 호출하여 릴리스합니다.

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

...

rootComponent.dispose();

위의 예제에서는 함수가 호출되면 루트 구성 요소를 showQuote()JS 동적으로 렌더링합니다. 시작할 때 Blazor 루트 구성 요소를 컨테이너 요소로 렌더링하려면 다음 예제와 같이 JavaScript 이니셜라이저를 사용하여 구성 요소를 렌더링합니다.

다음 예제에서는 구성 요소, 파일의 루트 구성 요소 등록 Program 및 초기화를 jsComponentInitializers.js사용하여 Quote 이전 예제를 기반으로 합니다. 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. 개체(대문자B)를 사용할 Blazor 때 등록이 유효하지만 매개 변수를 사용하는 것이 좋습니다.

추가 기능이 있는 고급 예제는 ASP.NET Core 참조 원본 BasicTestApp(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 사용자 지정 요소를 사용하여 Angular 또는 React 같은 다른 SPA 프레임워크에서 Razor 구성 요소를 동적으로 렌더링합니다.

Blazor 사용자 지정 요소:

• 표준 HTML 인터페이스를 사용하여 사용자 지정 HTML 요소를 구현합니다.
• JavaScript API를 사용하여 루트 Razor 구성 요소의 상태 및 수명 주기를 수동으로 관리할 필요가 없습니다.
• Razor 구성 요소를 다른 SPA 프레임워크로 작성된 기존 프로젝트에 점진적으로 도입하는 데 유용합니다.

사용자 지정 요소는 자식 콘텐츠 또는 템플릿 구성 요소를 지원하지 않습니다.

요소 이름

HTML 사양에 따라 사용자 지정 요소 태그 이름은 케밥 케이스를 채택해야 합니다.

❌올바르지 않음: mycounter
❌올바르지 않음: MY-COUNTER
❌올바르지 않음: MyCounter
✔️유효한: my-counter
✔️유효한: my-cool-counter

Package(패키지)

Microsoft.AspNetCore.Components.CustomElements에 대한 패키지 참조를 앱의 프로젝트 파일에 추가합니다.

참고 항목

.NET 앱에 패키지를 추가하는 방법에 대한 지침은 패키지 사용 워크플로에서 패키지 설치 및 관리의 문서(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");

등록된 사용자 지정 요소 사용

모든 웹 프레임워크에서 사용자 지정 요소를 사용합니다. 예를 들어, 앞의 앱의 Counter 구성 요소를 렌더링하는 my-counter 사용자 지정 HTML 요소는 다음 태그가 있는 React 앱에서 사용됩니다.

<my-counter></my-counter>

Blazor를 사용하여 사용자 지정 요소를 만드는 방법에 대한 전체 예제는 참조 원본의 CustomElementsComponent 구성 요소를 참조하세요.

참고 항목

.NET 참조 원본의 설명서 링크는 일반적으로 다음 릴리스의 .NET을 위한 현재 개발을 나타내는 리포지토리의 기본 분기를 로드합니다. 특정 릴리스를 위한 태그를 선택하려면 Switch branches or tags(분기 또는 태그 전환) 드롭다운 목록을 사용합니다. 자세한 내용은 ASP.NET Core 소스 코드(dotnet/AspNetCore.Docs #26205)의 버전 태그를 선택하는 방법을 참조하세요.

패스 매개 변수

매개 변수를 HTML 특성으로 또는 DOM 요소의 JavaScript 속성으로 Razor 구성 요소에 전달합니다.

다음 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 특성으로 전달합니다. 특성 이름은 케밥 케이스 구문을 채택합니다(IncrementAmount가 아닌 increment-amount).

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

또는, 요소 개체에서 매개 변수의 값을 JavaScript 속성으로 설정할 수 있습니다. 속성 이름은 낙타 케이스 구문을 채택합니다(IncrementAmount가 아닌 incrementAmount).

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

언제든지 특성 또는 속성 구문을 사용하여 매개 변수 값을 업데이트할 수 있습니다.

지원되는 매개 변수 형식:

• JavaScript 속성 구문을 사용하여 JSON 직렬화 가능 형식의 개체를 전달할 수 있습니다.
• HTML 특성을 사용하면 문자열, 부울 또는 숫자 형식의 개체를 전달하는 것으로 제한됩니다.

Angular 및 React 구성 요소 생성

Angular 또는 React와 같은 웹 프레임워크용 Razor 구성 요소에서 프레임워크별 JS(JavaScript) 구성 요소를 생성합니다. 이 기능은 .NET에는 포함되어 있지 않지만 JS에서 Razor 구성 요소를 렌더링 지원에 의해 활성화됩니다. GitHub의 JS 구성 요소 생성 샘플은 Razor 구성 요소에서 Angular 및 React 구성 요소를 생성하는 방법을 보여줍니다. 추가 정보는 GitHub 샘플 앱의 README.md 파일을 참조하세요.

Warning

Angular 및 React 구성 요소 기능은 현재 실험적이고 지원되지 않으며 언제든지 변경되거나 제거될 수 있습니다. 이 특정 접근 방식이 요구 사항을 얼마나 잘 충족하는지에 대한 피드백을 환영합니다.