ASP.NET Core 中的元件標記協助程式
元件標記協助程式會在 Razor 頁面或 MVC 檢視中轉譯 Razor 元件。
必要條件
請遵循將 ASP.NET Core Razor 元件整合到 ASP.NET Core 應用程式中一文的在頁面或檢視中使用不可路由傳送的元件一節中的指引。
請遵循以下任一項的 [設定] 區段中的指引:
- Blazor Server:將可路由和不可路由的 Razor 元件整合到 Razor 頁面和 MVC 應用程式中。
- Blazor WebAssembly:將託管 Blazor WebAssembly 解決方案中的 Razor 元件整合到 Razor 頁面和 MVC 應用程式中。
請遵循預先轉譯和整合 ASP.NET Core Razor 元件一文中組態一節中的指導。
元件標籤協助程式
若要從頁面或檢視轉譯元件,請使用元件標記協助程式 (<component>
標記)。
注意
將 Razor 元件整合到託管 Blazor WebAssembly 應用程式中的 Razor 頁面和 MVC 應用程式,在 .NET 5.0 或更新版本的 ASP.NET Core 中受支援。
RenderMode 設定元件:
- 預先轉譯至頁面。
- 在頁面上轉譯為靜態 HTML,或包含從使用者代理程式啟動 Blazor 應用程式所需的資訊。
Blazor WebAssembly 應用程式轉譯模式會顯示在下表中。
轉譯模式 | 描述 |
---|---|
WebAssembly |
轉譯 Blazor WebAssembly 應用程式的標記,以在瀏覽器中載入時用來包含互動式元件。 元件不會預先轉譯。 此選項可讓您更輕鬆地在不同的頁面上轉譯不同的 Blazor WebAssembly 元件。 |
WebAssemblyPrerendered |
將元件預先轉譯為靜態 HTML,並包含 Blazor WebAssembly 應用程式的標記,以供稍後在瀏覽器中載入時,讓元件成為互動式元件。 |
轉譯模式會顯示在下表中。
轉譯模式 | 描述 |
---|---|
ServerPrerendered | 將元件轉譯為靜態 HTML,並包含伺服器端 Blazor 應用程式的標記。 當使用者代理程式啟動時,此標記是用來啟動 Blazor 應用程式。 |
Server | 轉譯伺服器端 Blazor 應用程式的標記。 不包含元件的輸出。 當使用者代理程式啟動時,此標記是用來啟動 Blazor 應用程式。 |
Static | 將元件轉譯為靜態 HTML。 |
應用程式轉譯模式會顯示在下表中。
轉譯模式 | 描述 |
---|---|
ServerPrerendered | 將元件轉譯為靜態 HTML,並包含伺服器端 Blazor 應用程式的標記。 當使用者代理程式啟動時,此標記是用來啟動 Blazor 應用程式。 |
Server | 轉譯伺服器端 Blazor 應用程式的標記。 不包含元件的輸出。 當使用者代理程式啟動時,此標記是用來啟動 Blazor 應用程式。 |
Static | 將元件轉譯為靜態 HTML。 |
其他特性包括:
- 允許多個元件標記協助程式轉譯多個 Razor 元件。
- 應用程式啟動之後,無法動態轉譯元件。
- 雖然頁面和檢視可以使用元件,但是反之則不成立。 元件無法使用檢視和頁面特定功能,例如部分檢視和區段。 若要從元件中的部分檢視使用邏輯,請將部分檢視邏輯分解成元件。
- 不支援從靜態 HTML 頁面轉譯伺服器元件。
下列元件標記協助程式會使用 ServerPrerendered
在伺服器端 Blazor 應用程式中的頁面或檢視中轉譯 EmbeddedCounter
元件:
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components
...
<component type="typeof(EmbeddedCounter)" render-mode="ServerPrerendered" />
上述範例假設 EmbeddedCounter
元件位於應用程式的 Components
資料夾中。 預留位置 {APP ASSEMBLY}
是應用程式的組件名稱 (例如 @using BlazorSample.Components
)。
元件標記協助程式也可以將參數傳遞至元件。 請考慮下列 ColorfulCheckbox
元件,可設定核取方塊標籤的色彩和大小。
Components/ColorfulCheckbox.razor
:
<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
) 元件參數 可由元件標記協助程式設定:
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components
...
<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered"
param-Size="14" param-Color="@("blue")" />
上述範例假設 ColorfulCheckbox
元件位於 Components
資料夾中。 預留位置 {APP ASSEMBLY}
是應用程式的組件名稱 (例如 @using BlazorSample.Components
)。
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Shared
...
<component type="typeof(EmbeddedCounter)" render-mode="ServerPrerendered" />
上述範例假設 EmbeddedCounter
元件位於應用程式的 Shared
資料夾中。 預留位置 {APP ASSEMBLY}
是應用程式的組件名稱 (例如託管 Blazor 解決方案中的 @using BlazorSample.Shared
或 @using BlazorSample.Client.Shared
)。
元件標記協助程式也可以將參數傳遞至元件。 請考慮下列 ColorfulCheckbox
元件,可設定核取方塊標籤的色彩和大小。
Shared/ColorfulCheckbox.razor
:
<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
) 元件參數 可由元件標記協助程式設定:
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Shared
...
<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered"
param-Size="14" param-Color="@("blue")" />
上述範例假設 ColorfulCheckbox
元件位於 Shared
資料夾中。 預留位置 {APP ASSEMBLY}
是應用程式的組件名稱 (例如 @using BlazorSample.Shared
)。
下列 HTML 會在頁面或檢視中轉譯:
<label style="font-size:24px;color:blue">
<input id="survey" name="blazor" type="checkbox">
Enjoying Blazor?
</label>
傳遞引號字串需要明確 Razor 運算式,如上述範例針對 param-Color
所示。 針對 string
類型值的 Razor 剖析行為不會套用至 param-*
屬性,因為屬性的類型是 object
。
支援所有類型的參數,下列項目除外:
- 泛型參數。
- 不可序列化的參數。
- 集合參數中的繼承。
- 類型是在 Blazor WebAssembly 應用程式外部或延遲載入組件內定義的參數。
- 用於接收子系內容的
RenderFragment
委派 (例如param-ChildContent="..."
)。 在此案例中,建議您建立一個 Razor 元件 (.razor
),參考您想要以您想要傳遞的子系內容轉譯的元件,然後使用元件標記協助程式從頁面或檢視叫用 Razor 元件。
參數類型必須是 JSON 可序列化,這通常表示類型必須具有預設建構函式和可設定的屬性。 例如,您可以在上述範例中指定 Size
和 Color
的值,因為 Size
和 Color
的類型是基本類型 (int
和 string
),受 JSON 序列化程式支援。
在下列範例中,類別物件會傳遞至元件:
MyClass.cs
:
public class MyClass
{
public MyClass()
{
}
public int MyInt { get; set; } = 999;
public string MyString { get; set; } = "Initial value";
}
類別必須有公用無參數建構函式。
Components/ParameterComponent.razor
:
<h2>ParameterComponent</h2>
<p>Int: @MyObject?.MyInt</p>
<p>String: @MyObject?.MyString</p>
@code
{
[Parameter]
public MyClass? MyObject { get; set; }
}
Pages/MyPage.cshtml
:
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}
@using {APP ASSEMBLY}.Components
...
@{
var myObject = new MyClass();
myObject.MyInt = 7;
myObject.MyString = "Set by MyPage";
}
<component type="typeof(ParameterComponent)" render-mode="ServerPrerendered"
param-MyObject="@myObject" />
上述範例假設 ParameterComponent
元件位於應用程式的 Components
資料夾中。 預留位置 {APP ASSEMBLY}
是應用程式的組件名稱 (例如 @using BlazorSample
和 @using BlazorSample.Components
)。 MyClass
位於應用程式的命名空間中。
Shared/ParameterComponent.razor
:
<h2>ParameterComponent</h2>
<p>Int: @MyObject?.MyInt</p>
<p>String: @MyObject?.MyString</p>
@code
{
[Parameter]
public MyClass? MyObject { get; set; }
}
Pages/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(ParameterComponent)" render-mode="ServerPrerendered"
param-MyObject="@myObject" />
上述範例假設 ParameterComponent
元件位於應用程式的 Shared
資料夾中。 預留位置 {APP ASSEMBLY}
是應用程式的組件名稱 (例如 @using BlazorSample
和 @using BlazorSample.Shared
)。 MyClass
位於應用程式的命名空間中。