Využívání komponent ASP.NET Core Razor z Razor knihovny tříd (RCL)

Komponenty je možné sdílet v knihovně Razor tříd (RCL) napříč projekty. Zahrnutí komponent a statických prostředků do aplikace z:

• Jiný projekt v řešení
• Odkazovaná knihovna .NET.
• Balíček NuGet.

Stejně jako součásti jsou běžné typy .NET, součásti poskytované seznamem RCL jsou normální sestavení .NET.

Vytvoření seznamu RCL

Visual Studio

1. Vytvoření nového projektu
2. V dialogovém okně Vytvořit nový projekt vyberte Razor v seznamu šablon projektů ASP.NET Core knihovnu tříd. Vyberte Další.
3. V dialogovém okně Konfigurovat nový projekt zadejte název projektu do pole Název projektu. Příklady v tomto tématu používají název ComponentLibraryprojektu . Vyberte Další.
4. V dialogovém okně Další informace nevybírejte stránky a zobrazení podpory. Vyberte Vytvořit.
5. Přidejte seznam RCL do řešení:
   1. Otevřete řešení.
   2. V Průzkumník řešení klikněte pravým tlačítkem na řešení. Vyberte Přidat>existující projekt.
   3. Přejděte do souboru projektu RCL.
   4. Vyberte soubor projektu RCL (.csproj).
6. Přidejte odkaz na seznam RCL z aplikace:
   1. Klikněte pravým tlačítkem na projekt aplikace. Vyberte Přidat>odkaz na projekt.
   2. Vyberte projekt RCL. Vyberte OK.

Visual Studio Code / .NET CLI

1. Razor Použijte šablonu projektu knihovny tříd (razorclasslib) s příkazem dotnet new v příkazovém prostředí. V následujícím příkladu se vytvoří seznam RCL a pojmenuje ComponentLibrary se pomocí -o|--output této možnosti. Při spuštění příkazu se automaticky vytvoří složka, která obsahuje ComponentLibrary :

   dotnet new razorclasslib -o ComponentLibrary
   

2. Pokud chcete přidat knihovnu do existujícího projektu, použijte dotnet add reference příkaz v příkazovém prostředí. V následujícím příkazu {PATH TO LIBRARY} je zástupným symbolem cesta ke složce projektu knihovny:

   dotnet add reference {PATH TO LIBRARY}
   

Razor Využívání komponenty z seznamu RCL

Pokud chcete využívat komponenty z seznamu RCL v jiném projektu, použijte některý z následujících přístupů:

• Použijte úplný název typu komponenty, který zahrnuje obor názvů seznamu RCL.
• Jednotlivé komponenty lze přidat podle názvu bez oboru názvů RCL, pokud Razordirektiva @using deklaruje obor názvů RCL. Použijte následující přístupy:
  • Přidejte direktivu @using k jednotlivým komponentám.
  • zahrnout direktivu @using do souboru nejvyšší úrovně _Imports.razor , aby byly komponenty knihovny k dispozici pro celý projekt. Přidejte direktivu do _Imports.razor souboru na libovolné úrovni, aby se obor názvů použil na jednu komponentu nebo sadu komponent v rámci složky. _Imports.razor Při použití souboru jednotlivé komponenty nevyžadují direktivu @using pro obor názvů RCL.

V následujícíchpříkladch ComponentLibrary Component1 Komponenta Component1 je ukázková komponenta automaticky přidaná do seznamu RCL vytvořeného ze šablony projektu RCL, která není vytvořená pro podporu stránek a zobrazení.

Component1.razor v seznamu ComponentLibrary RCL:

<div class="my-component">
    This component is defined in the <strong>ComponentLibrary</strong> package.
</div>

V aplikaci, která využívá seznam RCL, odkazujte na komponentu Component1 pomocí jejího oboru názvů, jak ukazuje následující příklad.

ConsumeComponent1.razor:

@page "/consume-component-1"

<h1>Consume component (full namespace example)</h1>

<ComponentLibrary.Component1 />

Alternativně přidejte direktivu @using a použijte komponentu bez jejího oboru názvů. Následující @using direktiva se může také zobrazit v libovolném _Imports.razor souboru v aktuální složce nebo nad aktuální složkou.

ConsumeComponent2.razor:

@page "/consume-component-2"
@using ComponentLibrary

<h1>Consume component (<code>@@using</code> example)</h1>

<Component1 />

U komponent knihovny, které používají izolaci šablon stylů CSS, se styly komponent automaticky zpřístupní pro aplikaci využívající. V aplikaci, která knihovnu využívá, není nutné ručně propojit ani importovat jednotlivé šablony stylů komponent nebo jeho soubor CSS, který knihovnu využívá. Aplikace používá importy šablon stylů CSS k odkazu na sbalené styly seznamu RCL. Seskupené styly se nepublikují jako statický webový prostředek aplikace, která knihovnu využívá. Pro knihovnu tříd pojmenovanou ClassLib a aplikaci s šablonou Blazor BlazorSample.styles.css stylů se šablona stylů seznamu RCL automaticky naimportuje v horní části šablony stylů aplikace v době sestavení:

@import '_content/ClassLib/ClassLib.bundle.scp.css';

V předchozích příkladech Component1je šablona stylů (Component1.razor.css) automaticky seskupována.

Component1.razor.css v seznamu ComponentLibrary RCL:

.my-component {
    border: 2px dashed red;
    padding: 1em;
    margin: 1em 0;
    background-image: url('background.png');
}

Obrázek pozadí je také součástí šablony projektu RCL a nachází se ve wwwroot složce seznamu RCL.

wwwroot/background.png v seznamu ComponentLibrary RCL:

Pokud chcete poskytnout další styly komponent knihovny ze šablon stylů ve složce knihovny wwwroot , přidejte značky šablon <link> stylů do příjemce seznamu RCL, jak ukazuje další příklad.

Důležité

Obecně platí, že komponenty knihovny používají izolaci šablon stylů CSS k balení a poskytování stylů komponent. Styly komponent, které spoléhají na izolaci šablon stylů CSS, se automaticky zpřístupní aplikaci, která používá seznam RCL. V aplikaci, která knihovnu využívá, není nutné ručně propojit ani importovat jednotlivé šablony stylů komponent nebo jeho soubor CSS, který knihovnu využívá. Následující příklad je určený pro poskytování globálních šablon stylů mimo izolaci šablon stylů CSS, což obvykle není požadavkem pro typické aplikace, které využívají seznamy RCLS.

Následující obrázek pozadí se používá v dalším příkladu. Pokud implementujete příklad zobrazený v této části, klikněte pravým tlačítkem myši na obrázek a uložte ho místně.

wwwroot/extra-background.png v seznamu ComponentLibrary RCL:

Přidejte novou šablonu stylů do seznamu RCL s extra-style třídou.

wwwroot/additionalStyles.css v seznamu ComponentLibrary RCL:

.extra-style {
    border: 2px dashed blue;
    padding: 1em;
    margin: 1em 0;
    background-image: url('extra-background.png');
}

Přidejte komponentu do seznamu RCL, který používá extra-style třídu.

ExtraStyles.razor v seznamu ComponentLibrary RCL:

<div class="extra-style">
    <p>
        This component is defined in the <strong>ComponentLibrary</strong> package.
    </p>
</div>

Přidejte stránku do aplikace, která používá komponentu ExtraStyles z seznamu RCL.

ConsumeComponent3.razor:

@page "/consume-component-3"
@using ComponentLibrary

<h1>Consume component (<code>additionalStyles.css</code> example)</h1>

<ExtraStyles />

Odkaz na šablonu stylů knihovny v kódu aplikace <head> (umístění <head> obsahu):

Blazor Web Apps:

<link href="@Assets["_content/ComponentLibrary/additionalStyles.css"]" rel="stylesheet">

Samostatné aplikace Blazor WebAssembly:

<link href="_content/ComponentLibrary/additionalStyles.css" rel="stylesheet">

Zpřístupnění směrovatelných komponent v seznamu RCL

Aby bylo možné směrovatelné komponenty v seznamu RCL zpřístupnit pro přímé požadavky, musí být sestavení seznamu RCL zpřístupněno směrovači aplikace.

Otevřete komponentu App aplikace (App.razor). Assembly Přiřaďte kolekci k AdditionalAssemblies parametru Router komponenty, který bude obsahovat sestavení seznamu RCL. V následujícím příkladu se komponenta ComponentLibrary.Component1 používá ke zjištění sestavení seznamu RCL.

AdditionalAssemblies="new[] { typeof(ComponentLibrary.Component1).Assembly }"

Další informace najdete v tématu ASP.NET Blazor Základní směrování a navigace.

Vytvoření seznamu RCL se statickými prostředky ve wwwroot složce

Statické prostředky seznamu RCL jsou dostupné pro všechny aplikace, které knihovnu využívají.

Umístěte statické prostředky do wwwroot složky seznamu RCL a odkazujte na statické prostředky s následující cestou v aplikaci: _content/{PACKAGE ID}/{PATH AND FILE NAME}. Zástupný symbol {PACKAGE ID} je ID balíčku knihovny. Pokud v souboru projektu není zadaný parametr <PackageId>, jako ID balíčku se ve výchozím nastavení použije název sestavení projektu. Zástupný {PATH AND FILE NAME} symbol je cesta a název souboru v části wwwroot. Tento formát cesty se také používá v aplikaci pro statické prostředky dodané balíčky NuGet přidané do seznamu RCL.

Následující příklad ukazuje použití statických prostředků RCL s názvem ComponentLibrary RCL a Blazor aplikací, která využívá seznam RCL. Aplikace obsahuje odkaz na projekt pro ComponentLibrary seznam RCL.

Následující obrázek Jeepu® se používá v příkladu této části. Pokud implementujete příklad zobrazený v této části, klikněte pravým tlačítkem myši na obrázek a uložte ho místně.

wwwroot/jeep-yj.png v seznamu ComponentLibrary RCL:

Do seznamu RCL přidejte následující JeepYJ komponentu.

JeepYJ.razor v seznamu ComponentLibrary RCL:

<h3>ComponentLibrary.JeepYJ</h3>

<p>
    <img alt="Jeep YJ&reg;" src="_content/ComponentLibrary/jeep-yj.png" />
</p>

Do aplikace, která využívá seznam RCL, přidejte následující Jeep komponentu ComponentLibrary . Komponenta Jeep používá:

• Obrázek Jeep YJ® ze ComponentLibrary složky seznamu RCL wwwroot .
• Komponenta JeepYJ z seznamu RCL.

Jeep.razor:

@page "/jeep"
@using ComponentLibrary

<div style="float:left;margin-right:10px">
    <h3>Direct use</h3>

    <p>
        <img alt="Jeep YJ&reg;" src="_content/ComponentLibrary/jeep-yj.png" />
    </p>
</div>

<JeepYJ />

<p>
    <em>Jeep</em> and <em>Jeep YJ</em> are registered trademarks of 
    <a href="https://www.stellantis.com">FCA US LLC (Stellantis NV)</a>.
</p>

Vykreslená komponenta Jeep :

Další informace najdete v tématu Opakovaně použitelné Razor uživatelské rozhraní v knihovnách tříd s ASP.NET Core.

Vytvoření seznamu RCL s kolacemi javascriptových souborů s komponentami

Umístění souborů JavaScriptu (JS) pro Razor komponenty je pohodlný způsob, jak uspořádat skripty v aplikaci.

RazorBlazor komponenty aplikací kompletují JS soubory pomocí .razor.js rozšíření a jsou veřejně adresovatelné pomocí cesty k souboru v projektu:

{PATH}/{COMPONENT}.razor.js

• Zástupný {PATH} symbol je cesta ke komponentě.
• Zástupný {COMPONENT} symbol je komponenta.

Když je aplikace publikovaná, architektura automaticky přesune skript do webového kořenového adresáře. Skripty se přesunou do umístění, kde bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.jsjsou zástupné symboly:

• {TARGET FRAMEWORK MONIKER}je moniker cílové architektury (TFM).
• {PATH} je cesta ke komponentě.
• {COMPONENT} je název komponenty.

Relativní adresa URL skriptu se nevyžaduje žádná změna, protože Blazor se postará o umístění JS souboru do publikovaných statických prostředků za vás.

Tato část a následující příklady se primárně zaměřují na vysvětlení JS kolkace souborů. První příklad ukazuje kompletovaný JS soubor s běžnou JS funkcí. Druhý příklad ukazuje použití modulu k načtení funkce, což je doporučený přístup pro většinu produkčních aplikací. Volání JS z .NET je plně pokryto voláním javascriptových funkcí z metod .NET v ASP.NET Core Blazor, kde existují další vysvětlení BlazorJS rozhraní API s dalšími příklady. Vyřazení komponent, které se nachází v druhém příkladu, se zabývá životním cyklem komponent ASP.NET CoreRazor.

Následující JsCollocation1 komponenta načte skript prostřednictvím HeadContent komponenty a volá JS funkci s IJSRuntime.InvokeAsync. Zástupný {PATH} symbol je cesta ke komponentě.

Důležité

Pokud pro ukázku v testovací aplikaci použijete následující kód, změňte {PATH} zástupný symbol na cestu komponenty (například Components/Pages v .NET 8 nebo novějším nebo Pages v .NET 7 nebo starším). Blazor Web App V prostředí (.NET 8 nebo novější) komponenta vyžaduje interaktivní režim vykreslení použitý globálně pro aplikaci nebo definici komponenty.

Za Blazor skript přidejte následující skript (umístění spouštěcího Blazor skriptu):

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

JsCollocation1 součást ({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();
    }
}

Kompletovaný JS soubor se umístí vedle JsCollocation1 souboru komponenty s názvem JsCollocation1.razor.jssouboru . V komponentě JsCollocation1 se na skript odkazuje na cestu kompletovaného souboru. V následujícím příkladu showPrompt1 funkce přijme jméno uživatele z a Window prompt() vrátí ho JsCollocation1 do komponenty pro zobrazení.

{PATH}/JsCollocation1.razor.js:

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

Předchozí přístup se nedoporučuje pro obecné použití v produkčních aplikacích, protože přístup znečišťuje klienta globálními funkcemi. Lepším přístupem pro produkční aplikace je použití JS modulů. Stejné obecné principy platí pro načtení JS modulu z kompletovaného JS souboru, jak ukazuje další příklad.

Metoda následující JsCollocation2 komponenty OnAfterRenderAsync načte JS modul module, který je součástí IJSObjectReference třídy komponent. module slouží k volání showPrompt2 funkce. Zástupný {PATH} symbol je cesta ke komponentě.

Důležité

Pokud pro ukázku v testovací aplikaci použijete následující kód, změňte {PATH} zástupný symbol na cestu komponenty. Blazor Web App V prostředí (.NET 8 nebo novější) komponenta vyžaduje interaktivní režim vykreslení použitý globálně pro aplikaci nebo definici komponenty.

JsCollocation2 součást ({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)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

V předchozím příkladu JSDisconnectedException je při vyřazení modulu zachycen v případě Blazorztráty okruhu SignalR . Pokud se předchozí kód použije v Blazor WebAssembly aplikaci, nedojde ke ztrátě připojeníSignalR, takže můžete odebrat blok a nechat řádek, který modul odstranícatch try-().await module.DisposeAsync(); Další informace najdete v tématu ASP.NET Interoperabilita Core Blazor JavaScriptu (JSinteroperabilita).

{PATH}/JsCollocation2.razor.js:

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

Použití skriptů a modulů pro kolaci JS v Razor knihovně tříd (RCL) je podporováno pouze pro BlazorJS mechanismus spolupráce založené na IJSRuntime rozhraní. Pokud implementujete interop JavaScriptu[JSImport]/[JSExport], prohlédni si javascriptový interop JSImport/JSExport s ASP.NET Core .Blazor

Pro skripty nebo moduly poskytované knihovnou tříd (RCL) využívající IJSRuntimeinteroperabilitu Razor založenou na protokolu JS RCL se používá následující cesta:

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

• K vytvoření správné cesty statického prostředku k souboru JS se vyžaduje segment cesty pro aktuální adresář (./).
• Zástupný symbol {PACKAGE ID} je identifikátor balíčku RCL (nebo název knihovny tříd, na kterou aplikace odkazuje).
• Zástupný {PATH} symbol je cesta ke komponentě. Pokud je komponenta Razor umístěná v kořenovém adresáři knihovny RCL, segment cesty není zahrnutý.
• Zástupný {COMPONENT} symbol je název komponenty.
• Zástupný {EXTENSION} symbol odpovídá rozšíření komponenty, buď razor nebo cshtml.

V následujícím příkladu aplikace Blazor:

• Identifikátor balíčku RCL je AppJS.
• Skripty modulu se načítají pro komponentu JsCollocation3 (JsCollocation3.razor).
• Komponenta JsCollocation3 je ve složce Components/Pages RCL.

module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

Analyzátor kompatibility prohlížeče na straně klienta

Aplikace na straně klienta cílí na celou plochu rozhraní .NET API, ale ne všechna rozhraní .NET API jsou podporována na WebAssembly kvůli omezením sandboxu prohlížeče. Při spuštění na WebAssembly dojde k vyvolání PlatformNotSupportedException nepodporovaných rozhraní API. Analyzátor kompatibility platformy upozorní vývojáře, když aplikace používá rozhraní API, která nejsou podporována cílovými platformami aplikace. U aplikací na straně klienta to znamená, že se v prohlížečích podporují rozhraní API. Přidávání poznámek rozhraní API rozhraní .NET Framework pro analyzátor kompatibility je probíhající proces, takže ne všechna rozhraní API rozhraní .NET Framework jsou aktuálně opatřena poznámkami.

Blazor Web Apps, které umožňují interaktivní komponenty WebAssembly, Blazor WebAssembly aplikace a projekty RCL automaticky povolit kontroly kompatibility prohlížeče přidáním browser jako podporované platformy s SupportedPlatform položkou MSBuild. Vývojáři knihoven můžou položku ručně přidat SupportedPlatform do souboru projektu knihovny, aby tuto funkci povolili:

<ItemGroup>
  <SupportedPlatform Include="browser" />
</ItemGroup>

Při vytváření knihovny uveďte, že konkrétní rozhraní API není v prohlížečích podporováno zadáním browser UnsupportedOSPlatformAttribute:

using System.Runtime.Versioning;

...

[UnsupportedOSPlatform("browser")]
private static string GetLoggingDirectory()
{
    ...
}

Další informace najdete v tématu Přidávání poznámek k rozhraním API jako nepodporovaných na konkrétních platformách (dotnet/designs úložiště GitHub.

Izolace JavaScriptu v modulech JavaScriptu

Blazor umožňuje izolaci JavaScriptu ve standardních modulech JavaScriptu. Izolace JavaScriptu poskytuje následující výhody:

• Importovaný JavaScript už znečišťuje globální obor názvů.
• Uživatelé knihovny a komponent nejsou potřeba k ručnímu importu souvisejícího JavaScriptu.

Další informace najdete v tématu Volání funkcí JavaScriptu z metod .NET v ASP.NET Core Blazor.

Vyhněte se oříznutí metod javascript-invokable .NET

Opětovné propojení modulu runtime oříznou instanci třídy JavaScript-invokable metod .NET, pokud nejsou explicitně zachovány. Další informace naleznete v tématu Volání metod .NET z funkcí JavaScriptu v ASP.NET Core Blazor.

Sestavení, balení a odeslání do NuGetu

Vzhledem k tomu Razor , že knihovny tříd, které obsahují Razor komponenty, jsou standardními knihovnami .NET, balení a jejich expedice do NuGetu se nijak neliší od balení a expedice jakékoli knihovny do NuGetu. Balení se provádí pomocí dotnet pack příkazu v příkazovém prostředí:

dotnet pack

Nahrajte balíček do NuGetu dotnet nuget push pomocí příkazu v příkazovém prostředí.

Ochranné známky

Jeep a Jeep YJ jsou registrované ochranné známky FCA US LLC (Stellantis NV).

Další materiály

• Opakovaně použitelné uživatelské rozhraní Razor v knihovnách tříd s využitím ASP.NET Core
• Použití rozhraní ASP.NET Core API v knihovně tříd
• Přidání konfiguračního souboru IL (XML Intermediate Language) Do knihovny
• Podpora izolace šablon stylů CSS s knihovnami Razor tříd