Aracılığıyla paylaş

ASP.NET Core Blazor uygulamalarında JavaScript konumu

  • Makale

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 8 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:

Uyarı

Etiket dinamik olarak güncelleştirilemediğinden, yalnızca bileşenin statik sunucu tarafı işlemeyi (statik SSR) benimsemesi garanti edilirse bir bileşen dosyasına (.razor) etiket yerleştirin<script>.<script>

Uyarı

Etiket dinamik olarak güncelleştirilemediğinden <script> bir etiketi bileşen dosyasına (.razor) yerleştirmeyin<script>.

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 gerektiğinde içeri aktarılabilir ayrıJS modüllere yerleştirmenizi JS ö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ştirilmesi, ASP.NET Core 5.0'dan önceki sürümlerde Blazor desteklenmez. Uygulama JS yalıtımı için JS modüllerinin kullanılmasını gerektiriyorsa, uygulamayı oluştururken ASP.NET Core 5.0 veya üzerinin kullanılmasını öneririz. Daha fazla bilgi için Sürüm açılan listesini kullanarak bu makalenin 5.0 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 betik yükleme

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 Blazor'a bağımlıysa JS 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.

<body> işaretlemesi içinde betik yükleme

JavaScript etiketlerini (<script>...</script>) betik başvurusundan sonra kapanış </body> öğesinin Blazor içine yerleştirin:

<body>
    ...

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

Yukarıdaki örnekte, {BLAZOR SCRIPT} yer tutucu betik yolu ve dosya adıdır Blazor . 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 Razor JavaScript (JS) dosyalarının birlikte yerleştirilmesi, bir uygulamadaki betikleri düzenlemenin kullanışlı bir yoludur.

Razoruygulamaların bileşenleri Blazor uzantıyı .razor.js kullanarak dosyaları birlikte dağıtır JS ve projedeki dosyanın yolu kullanılarak genel olarak ele alınabilir:

{PATH}/{COMPONENT}.razor.js

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

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

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

Bu bölüm ve aşağıdaki örnekler öncelikli olarak dosya birlikte bulundurmayı açıklamaya JS odaklanmıştır. İlk örnekte, sıradan JS bir işlevle birlikte bulunan JS bir dosya gösterilmektedir. İ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 çağırma JS işlemi, api'nin ek örneklerle birlikte daha fazla açıklamasının BlazorJS bulunduğu ASP.NET Core'daki Blazor.NET yöntemlerinden JavaScript işlevlerini çağırma bölümünde tam olarak ele alınmıştır. İkinci örnekte yer alan bileşen elden çıkarma, ASP.NET Core Razor bileşen yaşam döngüsü kapsamındadır.

Aşağıdaki JsCollocation1 bileşen, bir HeadContent bileşen aracılığıyla bir betik yükler ve ile IJSRuntime.InvokeAsyncbir JS işlev çağırır. Yer {PATH} tutucu, bileşenin yoludur.

Ö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 arkasına Blazor aşağıdaki betiği ekleyin (başlangıç betiğininBlazor konumu):

<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 void ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

Birlikte bulunan JS dosya, dosya adıyla JsCollocation1.razor.jsbileşen dosyasının yanına JsCollocation1 yerleştirilir. Bileşende JsCollocation1 betik, birlikte bulunan dosyanın yolunda başvurulur. Aşağıdaki örnekte işlev, showPrompt1 kullanıcı adını ' Window prompt() den kabul eder ve görüntülemek üzere bileşenine JsCollocation1 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ından biri olan içine bir JS IJSObjectReference modül moduleyükler. module işlevi çağırmak showPrompt2 için kullanılır. Yer {PATH} tutucu, bileşenin yoludur.

Ö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. (.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 void 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)
        {
            await module.DisposeAsync();
        }
    }
}

{PATH}/JsCollocation2.razor.js:

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

Sınıf Razor kitaplığında (RCL) birlikte bulunan JS betiklerin ve modüllerin kullanımı yalnızca arabirimine dayalı IJSRuntime birlikte çalışma mekanizması için JS Blazordesteklenir. JavaScript[JSExport]/[JSImport] birlikte çalışma uyguluyorsanız bkz. JavaScript JSImport/JSExport ASP.NET Core Blazorile birlikte çalışma.

-tabanlı JS birlikte çalışma kullanılarak IJSRuntimebir Razor 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

  • JS dosyasının doğru statik varlık yolunu oluşturabilmek için geçerli dizinin yol segmenti (./) 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).
  • Yer {PATH} tutucu, bileşenin yoludur. RCL'nin köküne bir Razor bileşeni yerleştirilirse, yol segmenti eklenmez.
  • Yer {COMPONENT} tutucu bileşen adıdır.
  • Yer {EXTENSION} tutucu, razor veya cshtmlbileş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.

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

Betik başvurusundan sonra bir betik kaynağı (JS) yolu olan JavaScript () etiketlerini<script>...</script> (src) kapanış </body> öğesinin Blazor içine yerleştirin:

<body>
    ...

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

Yukarıdaki örnekte yer tutucular için:

  • Yer {BLAZOR SCRIPT} tutucu, betik yolu ve dosya adıdır Blazor . 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>

Betiklerinizin tümünü altında wwwrootayrı bir klasörde tutmak istemiyorsanız, betikleri doğrudan wwwroot klasöründen de kullanabilirsiniz:

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

Razor sınıf kitaplığı tarafından dış JS dosyası sağlandığında, JS dosyasını kararlı statik web varlığı yoluyla 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.

Başlamadan önce veya sonra Blazor betik ekleme

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

Başladıktan sonra Blazor bir betik eklemek için, el ile başlatmadan elde edilen sonuçlara Promise zincirleyin Blazor. Daha fazla bilgi ve örnek için bkz . ASP.NET Core Blazor başlatma.

JavaScript modüllerinde JavaScript yalıtımı

Blazorstandart JS modüllerde JavaScript (JS) 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şenlerin kullanıcılarının ilgili JS'yi içeri aktarması gerekmez.

Daha fazla bilgi için bkz. ASP.NET Core Blazor'da .NET yöntemlerinden JavaScript işlevlerini çağırma.

işleciyle import() dinamik içeri aktarma, ASP.NET Core ve Blazorile desteklenir:

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

Yukarıdaki örnekte yer tutucu, modülün {CONDITION} yüklenmesi gerekip gerekmediğini belirlemek için koşullu denetimi temsil eder.

Tarayıcı uyumluluğu için bkz . Kullanabilir miyim: JavaScript modülleri: dinamik içeri aktarma.