ASP.NET Core 中的元件標記協助程式Component Tag Helper in ASP.NET Core

作者:Daniel RothLuke LathamBy Daniel Roth and Luke Latham

若要從頁面或視圖呈現元件,請使用元件標記協助程式。To render a component from a page or view, use the Component Tag Helper.

必要條件Prerequisites

請遵循<xref:blazor/integrate-components#prepare-the-app>文章的準備應用程式以使用頁面和 views 中的元件一節中的指導方針。Follow the guidance in the Prepare the app to use components in pages and views section of the <xref:blazor/integrate-components#prepare-the-app> article.

元件標記協助程式Component Tag Helper

下列元件標記協助程式會在Counter頁面或視圖中呈現元件:The following Component Tag Helper renders the Counter component in a page or view:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Pages

...

<component type="typeof(Counter)" render-mode="ServerPrerendered" />

上述範例假設Counter元件位於應用程式的Pages資料夾中。The preceding example assumes that the Counter component is in the app's Pages folder.

元件標記協助程式也可以將參數傳遞給元件。The Component Tag Helper can also pass parameters to components. 請考慮下列ColorfulCheckbox設定核取方塊標籤色彩和大小的元件:Consider the following ColorfulCheckbox component that sets the check box label's color and size:

<label style="font-size:@(Size)px;color:@Color">
    <input @bind="Value"
           id="survey" 
           name="blazor" 
           type="checkbox" />
    Enjoying Blazor?
</label>

@code {
    [Parameter]
    public bool Value { get; set; }

    [Parameter]
    public int Size { get; set; } = 8;

    [Parameter]
    public string Color { get; set; }

    protected override void OnInitialized()
    {
        Size += 10;
    }
}

元件Size標記int協助程式Color可以string設定()和()元件參數The Size (int) and Color (string) component parameters can be set by the Component Tag Helper:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Shared

...

<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered" 
    param-Size="14" param-Color="@("blue")" />

上述範例假設ColorfulCheckbox元件位於應用程式的共用資料夾中。The preceding example assumes that the ColorfulCheckbox component is in the app's Shared folder.

下列 HTML 會在頁面或視圖中呈現:The following HTML is rendered in the page or view:

<label style="font-size:24px;color:blue">
    <input id="survey" name="blazor" type="checkbox">
    Enjoying Blazor?
</label>

傳遞加上引號的字串需要明確的 Razor 運算式,如param-Color上述範例中所示。Passing a quoted string requires an explicit Razor expression, as shown for param-Color in the preceding example. string類型值的 Razor 剖析行為不適用於param-*屬性,因為屬性是object類型。The Razor parsing behavior for a string type value doesn't apply to a param-* attribute because the attribute is an object type.

參數類型必須是可序列化的 JSON,這通常表示該類型必須有預設的函式和可設定的屬性。The parameter type must be JSON serializable, which typically means that the type must have a default constructor and settable properties. 例如,您可以在上述範例中指定SizeColor的值, Size因為和Color的類型是基本類型(intstring),這是 JSON 序列化程式所支援的型別。For example, you can specify a value for Size and Color in the preceding example because the types of Size and Color are primitive types (int and string), which are supported by the JSON serializer.

在下列範例中,類別物件會傳遞至元件:In the following example, a class object is passed to the component:

MyClass.csMyClass.cs:

public class MyClass
{
    public MyClass()
    {
    }

    public int MyInt { get; set; } = 999;
    public string MyString { get; set; } = "Initial value";
}

類別必須有公用無參數的函式。The class must have a public parameterless constructor.

Shared/mycomponent 之下. razorShared/MyComponent.razor:

<h2>MyComponent</h2>

<p>Int: @MyObject.MyInt</p>
<p>String: @MyObject.MyString</p>

@code
{
    [Parameter]
    public MyClass MyObject { get; set; }
}

Pages/mypage.aspx. cshtmlPages/MyPage.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}
@using {APP ASSEMBLY}.Shared

...

@{
    var myObject = new MyClass();
    myObject.MyInt = 7;
    myObject.MyString = "Set by MyPage";
}

<component type="typeof(MyComponent)" render-mode="ServerPrerendered" 
    param-MyObject="@myObject" />

上述範例假設MyComponent元件位於應用程式的共用資料夾中。The preceding example assumes that the MyComponent component is in the app's Shared folder. MyClass位於應用程式的命名空間({APP ASSEMBLY})。MyClass is in the app's namespace ({APP ASSEMBLY}).

RenderMode設定元件是否:RenderMode configures whether the component:

  • 會資源清單到頁面中。Is prerendered into the page.
  • 會在頁面上轉譯為靜態 HTML,或包含從使用者代理程式啟動 Blazor 應用程式所需的資訊。Is rendered as static HTML on the page or if it includes the necessary information to bootstrap a Blazor app from the user agent.
轉譯模式Render Mode 說明Description
ServerPrerendered 將元件轉譯為靜態 HTML,並包含Blazor伺服器應用程式的標記。Renders the component into static HTML and includes a marker for a Blazor Server app. 當使用者代理程式啟動時,會使用此標記來啟動Blazor應用程式。When the user-agent starts, this marker is used to bootstrap a Blazor app.
Server 呈現Blazor伺服器應用程式的標記。Renders a marker for a Blazor Server app. 不包含來自元件的輸出。Output from the component isn't included. 當使用者代理程式啟動時,會使用此標記來啟動Blazor應用程式。When the user-agent starts, this marker is used to bootstrap a Blazor app.
Static 將元件轉譯為靜態 HTML。Renders the component into static HTML.

雖然頁面和視圖可以使用元件,但相反的情況並非如此。While pages and views can use components, the converse isn't true. 元件不能使用 view 和 page 特有的功能,例如部分視圖和區段。Components can't use view- and page-specific features, such as partial views and sections. 若要在元件中使用部分視圖的邏輯,請將部分視圖邏輯分解成元件。To use logic from a partial view in a component, factor out the partial view logic into a component.

不支援從靜態 HTML 網頁轉譯伺服器元件。Rendering server components from a static HTML page isn't supported.

其他資源Additional resources