8.ASP.NET Core MVC标记帮助程序

1.标记帮助程序

1.1@addTagHelper指令

@addTagHelper 指令指定程序集中要加载的标记帮助程序对于 Views 目录或子目录中的所有视图文件均可用。

@addTagHelper 后第一个参数指定程序集中要加载的的标记帮助程序的范围，第二个参数指定包含标记帮助程序的程序集。

//指定程序集(Microsoft.AspNetCore.Mvc.TagHelpers)中的所有标记帮助程序。
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

//使用完全限定名称(fully qualified name,FQN)指定程序集(AuthoringTagHelpers)中的EmailTagHelper
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers

//完全限定名称(fully qualified name,FQN)和通配符(*)配套使用
@addTagHelper AuthoringTagHelpers.TagHelpers.E*, AuthoringTagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.Email*, AuthoringTagHelpers

1.2@removeTagHelper指令

@removeTagHelper 与 @addTagHelper 具有相同的两个参数，它会删除之前添加的标记帮助程序。

1.3@tagHelperPrefix指令

@tagHelperPrefix 指令可指定一个标记前缀字符串，以启用标记帮助程序支持并明确标记帮助程序用途。

@tagHelperPrefix th:

标记帮助程序前缀设置为 th:，所以只有使用前缀 th: 的元素才支持标记帮助程序。<label> 和 <input> 元素具有标记帮助程序前缀，可使用标记帮助程序，而 <span> 元素则相反。

<div class="form-group">
    <th:label asp-for="Password" class="col-md-2"></th:label>
    <div class="col-md-10">
        <th:input asp-for="Password" class="form-control" />
        <span asp-validation-for="Password" class="text-danger"></span>   
    </div>
</div>

1.4标记帮助程序选择退出字符(!)

须将标记帮助程序选择退出字符应用于开始和结束标记。

例如，使用标记帮助程序选择退出字符在 <span> 中禁用 Email 验证：

<!span asp-validation-for="Email" class="text-danger"></!span>

1.5标记帮助程序属性中的C#

通常，@ 运算符插入表达式的文本表示形式到呈现的 HTML 标记中。但是，当表达式的计算结果为逻辑 false时，框架会改为删除该属性。在下面的示例中，如果Model或LicenseId为 null，则会删除disabled属性。

<input asp-for="LastName" 
       disabled="@(Model?.LicenseId == null)" />

1.6标记帮助程序与HTML帮助程序的比较

并非每个 HTML 帮助程序都有对应的标记帮助程序，所以，标记帮助程序不会替代 HTML 帮助程序，在很多情况下，HTML 帮助程序在没有对应标记帮助程序时提供了一种替代方式。

与 HTML 帮助程序方法相比，标记帮助程序更清晰，更容易阅读、编辑和维护。C# 代码会被减少至服务器需要知道的最小值。

//标记帮助程序
<label class="caption" asp-for="FirstName"></label>
//HTML帮助程序
@Html.Label("FirstName", "First Name:", new {@class="caption"})

2.<link>标记帮助程序

属性	描述
asp-fallback-href	主 URL 失效后要回退到的 CSS 样式表的 URL。
asp-fallback-test-class	样式表中定义的用于回退测试的类名称。
asp-fallback-test-property	用于回退测试的 CSS 属性名称。
asp-fallback-test-value	用于回退测试的 CSS 属性值。

3.<script>标记帮助程序

属性	描述
asp-fallback-src	主 URL 失效后要回退到的脚本标签的 URL。
asp-fallback-test	主脚本中定义的用于回退测试的脚本方法。

4.<img>标记帮助程序

属性	描述
asp-append-version	调用<img>标记帮助程序并附加哈希值

5.<a>标记帮助程序

标记帮助程序	对应HTML帮助程序
<a>	`Html.ActionLink()`

属性	描述
asp-controller	控制器
asp-action	控制器操作方法
asp-route	命名路由
asp-route-{value}	单个路由参数
asp-all-route-data	多个路由参数
asp-fragment	URL 片段
asp-area	区域
asp-protocol	HTTP 协议
asp-host	域名

6.<form>标记帮助程序

<form> 标记帮助程序默认使用 POST 提交表单数据，如果需要使用 GET 提交表单数据，需显式声明method="get"属性。

标记帮助程序	对应HTML帮助程序
<form>	`Html.BeginForm()` 和 `Html.BeginRouteForm()`
<input>	`Html.TextBox()`、`Html.TextBoxFor()`、`Html.Editor()` 和 `Html.EditorFor()`
<textarea>	`Html.TextAreaFor()`
<label>	`Html.LabelFor()`
<select>	`Html.DropDownListFor()` 和 `Html.ListBoxFor()`

属性	描述
asp-for	绑定模型表达式
asp-items	option元素

7.验证标记帮助程序

标记帮助程序	对应HTML帮助程序
验证消息	`Html.ValidationMessageFor()`
验证摘要	`Html.ValidationSummary()`

属性	描述	一般配合HTML元素使用
asp-validation-for	验证消息	<span>
asp-validation-summary	验证摘要	<div>

asp-validation-summary	显示的验证消息
`All`	属性和模型级别
`ModelOnly`	模型
`None`	无

8.<cache>标记帮助程序

属性	描述
enabled	开启缓存
expires-on	缓存绝对到期日期
expires-after	缓存时间长度
expires-sliding	未被访问缓存被逐出时间
vary-by-header	按header刷新缓存
vary-by-query	按查询刷新缓存
vary-by-route	按路由刷新缓存
vary-by-cookie	按cookie刷新缓存
vary-by-user	按用户刷新缓存
vary-by	自定义刷新缓存
priority	缓存被逐出优先级别

9.<distributed-cache>标记帮助程序

分布式缓存标记帮助程序与缓存标记帮助程序继承自相同的基类。分布式标记帮助程序可以使用所有缓存标记帮助程序的属性。

属性	描述
name	每个存储的缓存实例的键

10.<environment>标记帮助程序

环境标记帮助程序根据当前主机环境，有条件地呈现其包含的内容。比较不区分大小写。

属性	描述
names	如果主机环境包含Staging或Production，则呈现内容。
include	如果主机环境包含Staging和Production，则呈现内容。
exclude	如果主机环境不包含Development，则呈现内容。

11.<component>标记帮助程序

11.1呈现模式(render-mode)属性

Blazor Server呈现模式(render-mode)属性	描述
ServerPrerendered	将组件呈现为静态 HTML，并包含 Blazor 服务器应用的标记。当user-agent启动时，此标记用于引导 Blazor 应用程序。
Server	呈现 Blazor Server 应用程序的标记。不包括组件的输出。当user-agent启动时，此标记用于引导 Blazor 应用程序。
Static	将组件呈现为静态 HTML。

Blazor WebAssembly呈现模式(render-mode)属性	描述
`WebAssembly`	呈现 Blazor WebAssembly 应用程序的标记，用于在加载到浏览器中时包含交互式组件。该组件不预呈现。此选项可以更轻松地在不同页面上呈现不同的 Blazor WebAssembly 组件。
`WebAssemblyPrerendered`	将组件预呈现为静态 HTML，并包含 Blazor WebAssembly 应用程序的标记，以供以后加载到浏览器中时使组件具有交互性。

11.2无参数呈现组件

//假定组件 Counter 位于应用的 Pages 文件夹中
//占位符 {APP ASSEMBLY} 是应用的程序集名称
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Pages

...

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

11.3有参数呈现组件

//ColorfulCheckbox组件
<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;
    }
}

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

...

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

11.4持久保存预呈现组件的状态

要持久保存预呈现组件的状态，请使用持久化组件状态标记帮助程序。在预呈现组件的应用的 _Host 页面的结束 </body> 标记内添加标记帮助程序的标记 <persist-component-state />。

//在 Blazor Server 应用 (Pages/_Host.cshtml)
<body>
    <component type="typeof(App)" render-mode="ServerPrerendered" />

    ...

    <persist-component-state />
</body>

//在 Blazor WebAssembly 应用 (Pages/_Host.cshtml)
<body>
    <component type="typeof(App)" render-mode="WebAssemblyPrerendered" />

    ...

    <persist-component-state />
</body>

原创文章，作者：huoxiaoqiang，如若转载，请注明出处：https://www.huoxiaoqiang.com/csharp/aspnetcoremvc/14913.html