Aracılığıyla paylaş

ASP.NET Core Blazor uygulamalarında JavaScript konumu

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Aşağıdaki yaklaşımlardan herhangi birini kullanarak JavaScript (JS) kodunu yükleyin:

Blazor uygulamaları için satır içi JavaScript önerilmez. JS Eşdizim kullanmanızıJS modülleriyle birlikte öneririz.

<script> etiketlerinin konumu

<script> etiketini yalnızca, bileşenin .razorolmaksızın statik sunucu tarafı işleme (statik SSR) benimsemesi garanti edilmişse bir bileşen dosyasına () yerleştirin. bir bileşen dosyasına <script> etiketi yerleştirmek derleme zamanı uyarısı veya hatası oluşturmaz, ancak gelişmiş gezinti ile etkileşimli işleme modunu veya statik SSR'yi benimseyen bileşenlerde betik yükleme davranışı beklentilerinizle eşleşmeyebilir.

Etiket dinamik olarak güncelleştirilemediğinden <script> bir etiketi bileşen dosyasına (.razor) yerleştirmeyin<script>. <script> etiketinin bir bileşen dosyasına yerleştirilmesi derleme zamanı hatası oluşturur.

Not

Belge örneklerinde betikler genellikle <script> etiketine yerleştirilir veya dış dosyalardan genel betikler yüklenir. Bu yaklaşımlar istemcide genel işlevler kirliliğine neden olur. Üretim uygulamaları için, JS'ı gerektiğinde içeri aktarılabilir ayrı JS modüller olarak yerleştirmenizi öneririz. Daha fazla bilgi için JavaScript modüllerinde JavaScript yalıtımı bölümüne bakın.

Not

Belge örneklerinde betikler <script> etiketine yerleştirilir veya dış dosyalardan genel betikler yüklenir. Bu yaklaşımlar istemcide genel işlevler kirliliğine neden olur. JS Gerektiğinde içeri aktarılabilir ayrı JS modüllere yerleştirme işlemi .NET 5'ten önceki sürümlerde Blazor. Eğer uygulama, yalıtım için JS modüllerinin kullanılmasını gerektiriyorsa, uygulamayı derlemek için .NET 5 veya üzerini kullanmanızı öneririz. Daha fazla bilgi için Sürüm açılan listesini kullanarak bu makalenin .NET 5 veya sonraki bir sürümünü seçin ve JavaScript modüllerinde JavaScript yalıtımı bölümüne bakın.

<head> işaretlemesi içinde bir betik yükle

Bu bölümde açıklanan yaklaşım genel olarak önerilmez.

JavaScript () etiketlerini (JS<script>...</script>) öğe işaretlemesine <head>yerleştirin:

<head>
    ...

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

Aşağıdaki nedenlerle JS'yi <head> işaretlemesinden yüklemek en iyi yaklaşım değildir:

  • Betik JS'a bağımlıysa Blazor interop başarısız olabilir. Betiklerin <head> işaretlemesi yoluyla değil diğer yaklaşımlardan biri kullanılarak yüklenmesini öneririz.
  • Betikteki JS'nin ayrıştırılması zaman alacağından sayfanın etkileşimli çalışması yavaşlayabilir.

Bileşen işaretlemesinde, betikler bir HeadContent bileşen aracılığıyla yüklenebilir, ancak bu yaklaşımın istemcideki sayfa yükünü yavaşlatması eğilimi olduğu için bu yöntemi kullanmaktan kaçınmanızı öneririz. Bir betik bir HeadContentBlazor Server uygulamasına, Blazor WebAssembly uygulamasına veya etkileşimli işleme modu (etkileşimli SSR, CSR) veya gelişmiş gezintiye sahip statik SSR kullanan bir Blazor Web App ile yüklendiğinde, bileşenin sayfasından uzaklaşıldığında işlenen <script> içeriğinden <head> etiketi kaldırılır, ancak betiğin kaydedildiği olay işleyicileri de dahil olmak üzere betiğin JavaScript kodunu kaldırmaz, kullanıma sunulan değişkenler ve betiğin sağladığı yöntemler. Gelişmiş navigasyon olmadan statik SSR kullanan yalnızca Blazor Web App, kullanıcı sayfadan uzaklaştığında JavaScript kodunu devre dışı bırakır. Genellikle, bu tür betik başvurularını kullanan bileşenlerde açıkça saklamak istemiyorsanız ve kodun gezinme olaylarında kaldırılmaması sizi rahatsız etmiyorsa, fiziksel <script> içeriğine <head> etiketleri eklemek daha iyi olur.

Bileşen işaretlemesinde, betikler bir HeadContent bileşen aracılığıyla yüklenebilir, ancak bu yaklaşımın istemcideki sayfa yükünü yavaşlatması eğilimi olduğu için bu yöntemi kullanmaktan kaçınmanızı öneririz. Bir betik bir HeadContent bileşeniyle yüklendiğinde, bileşenin sayfasından uzaklaşıldığında, işlenen <script> içeriğinden <head> etiketi kaldırılır, ancak betiğin kaydeddiği olay işleyicileri, kullanıma sunulan değişkenler ve betiğin sağladığı yöntemler de dahil olmak üzere betiğin JavaScript kodunu kaldırmaz. Genellikle, bu tür betik başvurularını kullanan bileşenlerde açıkça saklamak istemiyorsanız ve kodun gezinme olaylarında kaldırılmaması sizi rahatsız etmiyorsa, fiziksel <script> içeriğine <head> etiketleri eklemek daha iyi olur.

<body> işaretlemesi içinde bir betik yükle

JavaScript etiketlerini <script>...</script>, betik referansından sonra kapanış </body> öğesinin içine yerleştirin:

<body>
    ...

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

Yukarıdaki örnekte, {BLAZOR SCRIPT} yer tutucu Blazor betik yolu ve dosya adıdır. Betiğin konumu için bkz. ASP.NET Core Blazor proje yapısı.

Bileşenle aynı konumda yer alan dış JavaScript dosyasından (.js) betik yükleme

Bileşenler için JS JavaScript (Razor) dosyalarının birlikte yerleştirilmesi, bir uygulamadaki betikleri düzenlemenin kullanışlı bir yoludur.

Razor Blazor uygulamaların bileşenleri JS uzantılı dosyaları .razor.js kullanarak konumlandırır ve projedeki dosyanın yolu kullanılarak herkese açık şekilde erişilebilir.

{PATH}/{COMPONENT}.razor.js

  • {PATH} yer tutucu, bileşenin dizinidir.
  • Yer tutucu {COMPONENT} bileşendir.

Uygulama yayımlandığında çerçeve betiği otomatik olarak web köküne taşır. Betikler bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js'e taşınır, burada yer tutucular bulunmaktadır:

Betiğin göreli URL'sinde değişiklik yapılması gerekmez, çünkü Blazor, JS dosyasını sizin için yayımlanmış statik varlıklara yerleştirir.

Bu bölüm ve aşağıdaki örnekler öncelikli olarak JS dosya yerleştirmeyi açıklamaya odaklanmaktadır. İlk örnek, sıradan bir JS işlevle birlikte konumlandırılmış JS bir dosyayı göstermektedir. İkinci örnekte, çoğu üretim uygulaması için önerilen yaklaşım olan bir işlevi yüklemek için modül kullanımı gösterilmektedir. .NET'ten JS çağrısı, ASP.NET Core'da Blazor başlıklı 'JavaScript Fonksiyonlarını .NET Metotlarından Çağırma' bölümünde tam olarak ele alınmıştır, burada Blazor API'si üzerinde ek örneklerle birlikte daha fazla açıklama yapılmaktadır. İkinci örnekte yer alan bileşen bertarafı, RazorASP.NET Core bileşen bertarafı konusunda ele alınmıştır.

Aşağıdaki JsCollocation1 bileşen, bir HeadContent bileşen aracılığıyla bir skript yükler ve JS ile bir IJSRuntime.InvokeAsync işlevi çağırır. {PATH} yer tutucu, bileşenin dizinidir.

Önemli

Test uygulamasında bir gösterim için aşağıdaki kodu kullanırsanız, yer tutucuyu {PATH} bileşenin yolu olarak değiştirin (örnek: Components/Pages .NET 8 veya sonraki sürümlerde ya da Pages .NET 7 veya önceki sürümlerinde). (.NET 8 veya sonraki bir Blazor Web App sürümde) bileşen, uygulamaya veya bileşen tanımına genel olarak uygulanmış etkileşimli bir işleme modu gerektirir.

Betiğin Blazor ardına, başlangıç betiğinin Blazor konumu sonrasında, aşağıdaki betiği ekleyin:

<script src="{PATH}/JsCollocation1.razor.js"></script>

JsCollocation1 bileşen ({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();
    }
}

JS dosyası, JsCollocation1 bileşen dosyasının yanına, JsCollocation1.razor.js dosya adıyla birlikte yerleştirilir. Bileşende JsCollocation1 betiğe, aynı konumdaki dosyanın yolunda başvurulur. Aşağıdaki örnekte, showPrompt1 işlevi Window prompt()'den kullanıcı adını alır ve görüntülenmesi için JsCollocation1 bileşenine geri döndürür.

{PATH}/JsCollocation1.razor.js:

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

Önceki yaklaşım, müşteriyi genel işlevlerle kirlettiğinden üretim uygulamalarında genel kullanım için önerilmez. Üretim uygulamaları için daha iyi bir yaklaşım, modülleri kullanmaktır JS . Bir sonraki örnekte gösterildiği gibi, birlikte bulunan JS bir JS dosyadan modül yüklemek için de aynı genel ilkeler geçerlidir.

Aşağıdaki JsCollocation2 bileşenin OnAfterRenderAsync yöntemi, bileşen sınıfının bir JS olan module içine bir IJSObjectReference modül yükler. module, showPrompt2 işlevini çağırmak için kullanılır. {PATH} yer tutucu, bileşenin dizinidir.

Önemli

Test uygulamasında bir gösterim için aşağıdaki kodu kullanırsanız, {PATH} yer tutucusunu bileşenin yolu ile değiştirin. (.NET 8 veya sonraki bir Blazor Web App sürümde) bileşen, uygulamaya veya bileşen tanımına genel olarak uygulanmış etkileşimli bir işleme modu gerektirir.

JsCollocation2 bileşen ({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)
            {
            }
        }
    }
}

Yukarıdaki örnekte, JSDisconnectedException bağlantı hattının kaybolması durumunda BlazorSignalR modülün imhası sırasında tuzağa düşürülecektir. Önceki kod bir Blazor WebAssembly uygulamada kullanılıyorsa, kaybedilecek bir SignalR bağlantı yoktur, bu nedenle bağlantı bloğunu kaldırabilir ve modülü atayan (try) satırı bırakabilirsiniz. Daha fazla bilgi için ASP.NET Core Blazor JavaScript birlikte çalışabilirliği (JS birlikte çalışma)'ya bakın.

{PATH}/JsCollocation2.razor.js:

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

Önemli

<script>'ten sonra JsCollocation2.razor.js için Blazor etiketini yerleştirmeyin, çünkü çağrıldığında modül otomatik olarak yüklenir ve önbelleğe alınır.

Sınıf kitaplığında (RCL) birlikte bulunan betiklerin ve modüllerin kullanımı, yalnızca JS arabirimine dayalı Razor'nin Blazor birlikte çalışma mekanizması için desteklenir. JavaScript ile birlikte çalışmayı [JSImport] JavaScript JSImport/JSExport ile ASP.NET Core / birlikte çalışma [JSExport] için bkz.

Razor-tabanlı IJSRuntime birlikte çalışmasını kullanarak JS sınıf kitaplığı (RCL) tarafından sağlanan betikler veya modüller için aşağıdaki yol kullanılır:

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js

  • ./ dosyasının doğru statik varlık yolunu oluşturabilmek için geçerli dizinin yol segmenti (JS) gereklidir.
  • {PACKAGE ID} yer tutucusu RCL'nin paket tanımlayıcısıdır (veya uygulama tarafından başvurulan bir sınıf kitaplığı için kitaplık adıdır).
  • {PATH} yer tutucu, bileşenin dizinidir. RCL'nin köküne bir Razor bileşeni yerleştirilirse, yol segmenti eklenmez.
  • Yer tutucu {COMPONENT} bileşen adıdır.
  • Yer tutucu {EXTENSION}, razor veya cshtml bileşenin uzantısıyla eşleşir.

Aşağıdaki Blazor uygulaması örneğinde:

  • RCL'nin paket tanımlayıcısı AppJS şeklindedir.
  • JsCollocation3 bileşeni (JsCollocation3.razor) için modülün betikleri yüklenir.
  • JsCollocation3 bileşeni, RCL'nin Components/Pages klasöründedir.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

RCL'ler hakkında daha fazla bilgi için bkz. Razor sınıf kitaplığından (RCL) ASP.NET Core Razor bileşenlerini kullanma.

Bir dış JavaScript dosyasından (.js) betik yükleme

JavaScript () etiketlerini (), betik kaynağı () yolu ile birlikte betik referansından sonra kapanış öğesi içine yerleştirin.

<body>
    ...

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

Önceki örnekte kullanılan yer tutucular için:

  • Yer {BLAZOR SCRIPT} yer tutucu, Blazor betik yolu ve dosya adıdır. Betiğin konumu için bkz. ASP.NET Core Blazor proje yapısı.
  • {SCRIPT PATH AND FILE NAME (.js)} yer tutucusu, wwwroot altındaki yol ve betik dosyası adıdır.

Yukarıdaki <script> etiketinin aşağıdaki örneğinde scripts.js dosyası uygulamanın wwwroot/js klasöründe yer alır:

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

Betiklerinizi wwwroot klasöründe tutmak istemiyorsanız, bunları wwwroot klasöründen doğrudan da çalıştırabilirsiniz.

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

Dış JS dosyası bir Razor sınıf kütüphanesi tarafından sağlandığında, JS dosyasını kararlı statik web varlığı yolu kullanılarak belirtin: _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

  • {PACKAGE ID} yer tutucusu, kitaplığın paket kimliğidir. Proje dosyasında <PackageId> belirtilmediyse varsayılan olarak projenin derleme adı paket kimliği olur.
  • {SCRIPT PATH AND FILE NAME (.js)} yer tutucusu, wwwroot altındaki yol ve dosya adıdır.
<body>
    ...

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

Yukarıdaki <script> etiketinin aşağıdaki örneğinde:

  • Razor sınıf kitaplığının derleme adı ComponentLibrary'dir ve kitaplığın proje dosyasında <PackageId> belirtilmez.
  • scripts.js dosyası sınıf kitaplığının wwwroot klasöründe yer alır.
<script src="_content/ComponentLibrary/scripts.js"></script>

Daha fazla bilgi için bkz. Razor sınıf kitaplığından (RCL) ASP.NET Core Razor bileşenlerini kullanma.

Blazor başlamadan önce veya sonra betik enjekte et.

Betiklerin başlamadan önce veya sonra Blazor yüklendiğinden emin olmak için bir JavaScript başlatıcısı kullanın. Daha fazla bilgi ve örnek için bkz . ASP.NET Core Blazor başlatma.

Blazor başlatıldıktan sonra betik ekleme

Blazor başladıktan sonra bir betik eklemek için, Promise'nin manuel olarak başlatılmasından elde edilen Blazor'ye zincirleyin. Daha fazla bilgi ve örnek için bkz . ASP.NET Core Blazor başlatma.

JavaScript modüllerinde JavaScript yalıtımı

Blazor, standart JS modüllerde (JS) JavaScript yalıtımını etkinleştirir (ECMAScript belirtimi).

JS yalıtımı aşağıdaki avantajları sağlar:

  • İçeri aktarılan JS artık genel ad alanını kirletmez.
  • Kitaplık ve bileşenleri kullananların ilgili JS'yi içeri aktarması gerekmez.

Sunucu tarafı senaryolarında, bir JSDisconnectedException modülünün yok edilmesine yönelik JSDisconnectedException birlikte çalışma çağrısının SignalR'in JS devre kaybı nedeniyle engellendiği durumlarda daima hatasını yakalayın. Bu, işlenmeyen bir istisnayla sonuçlanır. Blazor WebAssembly uygulamalar, SignalR birlikte çalışma sırasında JS bağlantısı kullanmaz, bu nedenle modül atma için JSDisconnectedException uygulamalarında Blazor WebAssembly yakalamaya gerek yoktur.

Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın: