ASP.NET Core Blazor 组件开发核心指南

第1步：理解组件基础与文件结构

在 Blazor 项目中，以 .razor 结尾的文件被称为 Razor 组件。每个 .razor 文件编译后会生成一个对应的类，其名称与文件名一致。因此，文件名必须遵循大驼峰命名法（如 Test.razor）。

1.1 页面组件与非页面组件

• 页面组件： 包含 @page 指令的文件，支持路由导航，通常放置在 Pages 文件夹中。
• 非页面组件： 不包含 @page 指令的可复用部件，通常放置在 Shared 文件夹中供其他页面引用。

建议为自定义组件类添加 Component 后缀，以提高代码可读性。

第2步：定义组件逻辑与类结构

组件内部使用 @code 块包裹 C# 代码。这部分代码实际上生成了组件类的成员变量和方法。外部可以直接实例化这些组件类并调用其公共属性，但通常作为 UI 元素通过框架自动管理生命周期。

@code{
    public string Name { get; set; }
}

注意： Blazor 不支持直接访问项目中的相对路径资源。静态资源默认托管在 wwwroot 目录下，前端访问时使用绝对路径 / 开头即可。

第3步：配置路由与捕获参数

Blazor 的路由系统扁平化，不支持传统 MVC 中灵活的 Query String 可选参数。如果 URL 中包含占位符，则访问时必须提供该值。

3.1 路由声明

@page "/test"
@page "/test/{Id}"

3.2 捕获路由参数

需使用 [Parameter] 特性修饰公共属性，且类型必须为 string。若 URL 传入数值而属性定义为整型，将导致运行时错误。

@code {
    [Parameter]
    public string Id { get; set; } = "123";
}

第4步：使用 [Parameter] 进行组件传参

父组件可以通过自定义属性向子组件传递数据。[Parameter] 修饰的属性用于接收外部传入的值。

4.1 基础传参示例

<h2>@Title</h2>

@code{
    [Parameter]
    public string Title { get; set; } = "default";
}

父组件调用：

<ChildComponent Title="Custom Value" />

4.2 避免修改参数

重要原则： 请勿在子组件内直接赋值给 [Parameter] 修饰的属性，这会导致不可预期的行为。若需在组件内部修改参数副本，应创建单独的私有字段并在初始化时拷贝。

@code{
    [Parameter]
    public string Title { get; set; }
    
    private string _localTitle;

    protected override void OnInitialized()
    {
        _localTitle = Title;
    }
}

第5步：处理子内容 (RenderFragment)

当需要类似 HTML 标签的内容嵌套（如容器组件、对话框），可使用 RenderFragment 类型接收子节点内容。

<div>@Children</div>

@code {
    [Parameter]
    public RenderFragment Children { get; set; }
}

调用方可以将任意标记作为子内容传递：

<Container>
    <h1>Header Content</h1>
</Container>

第6步：高级参数特性

对于无法预先定义的多个属性（如动态 HTML 属性），可以使用字典类型的额外参数捕获功能。

6.1 属性展开 (Attribute splatting)

除了逐个定义属性外，可以使用 @attributes 直接传递字典：

<input @attributes="InputAttributes" />

@code {
    public Dictionary<string, object> InputAttributes { get; set; }
}

6.2 捕获未匹配参数

设置 CaptureUnmatchedValues = true，可以将未在组件中显式定义的参数全部收集到一个字典中。

@code{
    [Parameter(CaptureUnmatchedValues = true)]
    public IDictionary<string, object> AdditionalAttributes { get; set; }
}

第7步：跨组件状态同步与更新

Blazor 基于单例服务的特性，可通过静态事件或注入服务实现不同页面/组件间的实时通知更新。关键在于调用基类 ComponentBase 提供的 InvokeAsync 方法以触发 UI 重绘。

// 假设存在 NotifierService 监听事件
protected async Task OnNotify(string key, int value)
{
    // 必须在 InvokeAsync 回调中修改状态
    await InvokeAsync(() => {
        _lastNotification = (key, value);
        StateHasChanged();
    });
}

这种方式常用于多窗口消息推送或全局通知场景。

第8步：性能优化 - @key 控制

在处理列表渲染时，为了防止元素插入或删除导致整个 DOM 树重建，应指定 @key。Blazor 会根据 Key 的唯一性来保持元素的 DOM 状态，显著提升性能。

@foreach (var item in list)
{
    <li @key="item.Id">@item.Value</li>
}

第9步：其他高级指令

• 继承基类： 使用 @inherits ClassName 替代默认的 ComponentBase，以复用通用逻辑。
• 路由授权： 使用 @attribute [Authorize] 控制页面访问权限。
• 原始 HTML： 使用 MarkupString 类型渲染未经转义的 HTML 字符串。

总结

掌握 Blazor 组件的开发，重点在于理解 .razor 文件的编译机制、正确使用 [Parameter] 管理数据流以及利用 InvokeAsync 响应外部事件。通过合理使用 @key 和子内容机制，可以构建出高性能且结构清晰的现代 Web 应用。

以上就是 ASP.NET Core Blazor 组件开发的详细内容，更多关于 Blazor 技术趋势与实践的资料请关注本站其它相关文章！