JavaScript uygulamalarında ve SPA çerçevelerinde bileşenleri kullanma Razor

Bu makalede JavaScript'ten bileşenleri işleme Razor , özel öğeler kullanma Blazor ve Angular ve React bileşenleri oluşturma işlemleri anlatılmıştır.

Angular örnek uygulamalar

• CustomElementsBlazorÖrneği () (javiercn/CustomElementsBlazorSampleBlazor Server, dal: blazor-server): Blazor Server .NET 8'de desteklenir. Bu .NET 7 örneğini .NET 8'e geçirmek için bkz . ASP.NET Core 7.0'dan 8.0'a geçirme.
• CustomElementsBlazorÖrneği () (javiercn/CustomElementsBlazorSampleBlazor WebAssembly, dal: blazor-wasm): Bu .NET 7 örneğini .NET 8'e geçirmek için bkz. ASP.NET Core 7.0'dan 8.0'a geçirme.

JavaScript'ten Razor bileşenlerini işleme

Razor bileşenleri mevcut JS uygulamaları için JavaScript'ten (JS) dinamik olarak işlenebilir.

Bu bölümdeki örnek, aracılığıyla JSaşağıdaki Razor bileşeni bir sayfaya işler.

Quote.razor:

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

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

Program dosyasında, bileşenin konumu için ad alanını ekleyin.

Bir bileşeni işleme için kök bileşen olarak kaydetmek Razor için JS uygulamanın kök bileşen koleksiyonunda çağrısı RegisterForJavaScript yapın.

RegisterForJavaScriptbaşlatma mantığını (javaScriptInitializer) yürüten bir işlevin adını kabul eden bir JS aşırı yükleme içerir. İşlev JS , uygulama başlatıldıktan hemen sonra Blazor ve herhangi bir bileşen işlenmeden önce bileşen kaydı başına bir kez çağrılır. Bu işlev, HTML özel öğeleri veya tabanlı SPA JSçerçevesi gibi teknolojilerle JS tümleştirme için kullanılabilir.

Farklı bileşen kayıtları tarafından bir veya daha fazla başlatıcı işlevi oluşturulabilir ve çağrılabilir. Tipik kullanım örneği, başlatıcı işlevinin özel öğelerle veya başka bir tabanlı SPA çerçevesiyle tümleştirmeyi yapılandırıyorsa beklenen birden çok bileşen için aynı başlatıcı işlevini yeniden JSkullanmaktır.

Önemli

parametresini javaScriptInitializer RegisterForJavaScript JavaScript başlatıcılarıyla karıştırmayın. Parametrenin adı ve JS başlatıcılar özelliği tesadüfidir.

Aşağıdaki örnek, önceki Quote bileşenin tanımlayıcı olarak "quote" ile dinamik kaydını gösterir.

• Blazor Web Uygulamasında, sunucu tarafı Program dosyasında çağrısında AddInteractiveServerComponents değişiklik yapma:

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

• Bir Blazor WebAssembly uygulamada, istemci tarafı Program dosyasında şu çağrıyı açın RegisterForJavaScript RootComponents:

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

başlatıcı işlevini name ve parameters işlev parametrelerini nesnesine window ekleyin. Gösterim amacıyla, aşağıdaki initializeComponent işlev kayıtlı bileşenin adını ve parametrelerini günlüğe kaydeder.

wwwroot/jsComponentInitializers.js:

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

Bileşen JS parametrelerini gerektiği gibi geçirerek kayıtlı tanımlayıcıyı kullanarak bileşenini bir kapsayıcı öğesinde işleyin.

Aşağıdaki örnekte:

• Quote bileşen (quotetanımlayıcı) işlevi çağrıldığında öğesinde quoteContainer showQuote işlenir.
• Bileşenin Text parametresine bir tırnak dizesi geçirilir.

wwwroot/scripts.js:

async function showQuote() {
  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.'"
  });
}

Blazor Betik yüklendikten sonra, önceki betikleri JS uygulamaya yükleyin:

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

Yukarıdaki örnekte yer {BLAZOR SCRIPT} tutucu betiktir Blazor .

HTML'de hedef kapsayıcı öğesini (quoteContainer yerleştirin). Bu bölümdeki tanıtım için bir düğme, işlevi çağırarak bileşenin Quote işlenmesini showQuoteJS tetikler:

<button onclick="showQuote()">Show Quote</button>

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

Herhangi bir bileşen işlenmeden önce başlatma sırasında, tarayıcının geliştirici araçları konsolu şu çağrıldığında initializeComponent bileşenin Quote tanımlayıcısını (name) ve parametrelerini (parameters) günlüğe kaydeder:

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

Show Quote Düğme seçildiğinde bileşen, Quote içinde depolanan Text alıntıyla işlenir:

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

Not

rootComponents.add bileşenin bir örneğini döndürür. dispose Örneği serbest bırakmak için çağrısı:

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

...

rootComponent.dispose();

Yukarıdaki örnek, işlev çağrıldığında showQuote()JS kök bileşeni dinamik olarak işler. Başlangıç sırasında Blazor bir kök bileşeni kapsayıcı öğesinde işlemek için, aşağıdaki örnekte gösterildiği gibi bileşeni işlemek için javascript başlatıcısını kullanın.

Aşağıdaki örnek, önceki örnekte bileşeni, dosyadaki Program kök bileşen kaydını ve başlatmasını kullanarak Quote derlenirjsComponentInitializers.js. showQuote() İşlev (ve script.js dosyası) kullanılmaz.

HTML'de hedef kapsayıcı öğesini yerleştirin, quoteContainer2 örneğin:

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

JavaScript başlatıcısı kullanarak kök bileşeni hedef kapsayıcı öğesine ekleyin.

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

Web Blazor Uygulaması için:

export function afterWebStarted(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.'"
    });
}

Bir Blazor Server veya Blazor WebAssembly uygulaması için:

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.'"
    });
}

Not

çağrısı içinrootComponents.add, başlangıç olayı tarafından Blazor sağlanan parametresini (küçük harfb) kullanınblazor. Nesne (büyük harfB) kullanılırken Blazor kayıt geçerli olsa da, tercih edilen yaklaşım parametresini kullanmaktır.

Ek özellikler içeren gelişmiş bir örnek için ASP.NET Core başvuru kaynağındaki (dotnet/aspnetcoreGitHub deposu) örneğe BasicTestApp bakın:

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

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürümün etiketini seçmek için Dalları veya etiketleri değiştir açılan listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

Blazor özel öğeleri

Angular veya React gibi diğer SPA çerçevelerindeki bileşenleri dinamik olarak işlemek Razor için özel öğeleri kullanınBlazor.

Blazor özel öğeler:

• Özel HTML öğelerini uygulamak için standart HTML arabirimlerini kullanın.
• JavaScript API'lerini kullanarak kök Razor bileşenlerin durumunu ve yaşam döngüsünü el ile yönetme gereksinimini ortadan kaldırın.
• Bileşenleri diğer SPA çerçevelerinde yazılmış mevcut projelere aşamalı olarak tanıtmak Razor için kullanışlıdır.

Özel öğeler alt içeriği veya şablonlu bileşenleri desteklemez.

Öğe adı

HTML belirtimi gereği, özel öğe etiketi adları kebap büyük/küçük harflerini benimsemelidir:

❌Geçersiz: mycounter
❌Geçersiz: MY-COUNTER
❌Geçersiz: MyCounter
✔️Geçerli: my-counter
✔️Geçerli: my-cool-counter

Paket

Uygulamanın proje dosyasına için Microsoft.AspNetCore.Components.CustomElements bir paket başvurusu ekleyin.

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri) paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

Örnek bileşen

Aşağıdaki örnekler proje şablonundaki Counter bileşeni Blazor temel alır.

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 Web Uygulaması kaydı

Bir kök bileşeni Bir Web Uygulamasına özel öğe Blazor olarak kaydetmek için aşağıdaki adımları uygulayın.

Ad alanını Microsoft.AspNetCore.Components.Web sunucu tarafı Program dosyasının en üstüne ekleyin:

using Microsoft.AspNetCore.Components.Web;

Uygulamanın bileşenleri için bir ad alanı ekleyin. Aşağıdaki örnekte, uygulamanın ad alanıdır BlazorSample ve bileşenler klasörde bulunur Components/Pages :

using BlazorSample.Components.Pages;

Bağlantı hattı seçeneğinde ile RegisterCustomElement özel öğeyi belirtmek için AddInteractiveServerComponents çağrısında RootComponents öğesini değiştirin. Aşağıdaki örnek, bileşeni özel HTML öğesiyle my-counterkaydederCounter:

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

Blazor WebAssembly kayıt

Bir kök bileşeni bir uygulamaya özel öğe Blazor WebAssembly olarak kaydetmek için aşağıdaki adımları uygulayın.

Ad alanını Microsoft.AspNetCore.Components.Web dosyanın en üstüne Program ekleyin:

using Microsoft.AspNetCore.Components.Web;

Uygulamanın bileşenleri için bir ad alanı ekleyin. Aşağıdaki örnekte, uygulamanın ad alanıdır BlazorSample ve bileşenler klasörde bulunur Pages :

using BlazorSample.Pages;

üzerinde RootComponentsarayınRegisterCustomElement. Aşağıdaki örnek, bileşeni özel HTML öğesiyle my-counterkaydederCounter:

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

Kayıtlı özel öğeyi kullanma

Özel öğeyi herhangi bir web çerçevesiyle kullanın. Örneğin, uygulamanın Counter bileşenini işleyen önceki my-counter özel HTML öğesi react uygulamasında aşağıdaki işaretlemeyle kullanılır:

<my-counter></my-counter>

ile Blazorözel öğelerin nasıl oluşturulacağını gösteren tam bir örnek için başvuru kaynağındaki bileşene bakınCustomElementsComponent.

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürümün etiketini seçmek için Dalları veya etiketleri değiştir açılan listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

Parametre geçirme

Bileşenlerinize Razor PARAMETRELERI HTML öznitelikleri olarak veya DOM öğesinde JavaScript özellikleri olarak geçirin.

Aşağıdaki Counter bileşen, düğmenin artım miktarını Click me ayarlamak için bir IncrementAmount parametre kullanır.

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 Bileşeni özel öğeyle işleyin ve parametreye IncrementAmount HTML özniteliği olarak bir değer geçirin. Öznitelik adı kebab-case söz dizimini (increment-amountdeğil IncrementAmount) benimser:

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

Alternatif olarak, parametrenin değerini öğe nesnesinde JavaScript özelliği olarak ayarlayabilirsiniz. Özellik adı, camel case söz dizimini (incrementAmountdeğil):IncrementAmount

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

Parametre değerlerini istediğiniz zaman öznitelik veya özellik söz dizimi kullanarak güncelleştirebilirsiniz.

Desteklenen parametre türleri:

• JavaScript özellik söz dizimini kullanarak, herhangi bir JSON-serializable türündeki nesneleri geçirebilirsiniz.
• HTML özniteliklerini kullanarak dize, boole veya sayısal türlerdeki nesneleri geçirmekle sınırlısınız.

Angular ve React bileşenleri oluşturma

Angular veya React gibi web çerçeveleri için Razor bileşenlerinden çerçeveye özgü JavaScript (JS) bileşenleri oluşturun. Bu özellik .NET'e dahil değildir, ancak bileşeni işleme Razor JSdesteği tarafından etkinleştirilir. GitHub'da JS bileşeni oluşturma örneği, Razor bileşenlerinden Angular ve React bileşenleri oluşturmayı gösterir. Ek bilgi için GitHub örnek uygulamasının README.md dosyasına bakın.

Uyarı

Angular ve React bileşeni özellikleri şu anda deneyseldir, desteklenmemektedir ve herhangi bir anda değiştirilebilir. Bu belirli yaklaşımın gereksinimlerinizi ne kadar karşıladığına ilişkin geri bildirimlerinizi bekliyoruz.