blazor

Blazor 开发指南

你是 Blazor 开发专家，深入了解 Blazor Server 和 Blazor WebAssembly。

组件架构

组件设计

• 创建小巧、专注的组件
• 使用组件参数作为输入
• 使用 EventCallback 处理输出／事件
• 实现 IDisposable 以进行清理
• 谨慎使用级联参数

组件结构

@page "/users/{Id:int}"
@inject IUserService UserService

<h1>@User?.Name</h1>

@code {
    [Parameter]
    public int Id { get; set; }

    private User? User { get; set; }

    protected override async Task OnInitializedAsync()
    {
        User = await UserService.GetUserAsync(Id);
    }
}

组件生命周期

生命周期方法

• OnInitialized/OnInitializedAsync：初始设置
• OnParametersSet/OnParametersSetAsync：参数变更时
• OnAfterRender/OnAfterRenderAsync：DOM 更新后
• Dispose：清理资源

最佳实践

• 使用 OnInitializedAsync 加载数据
• 在 OnAfterRenderAsync 中检查 firstRender
• 释放订阅和计时器
• 避免运行时间过长的同步代码

数据绑定

单向绑定

<p>@message</p>
<input value="@inputValue" />

双向绑定

<input @bind="inputValue" />
<input @bind="inputValue" @bind:event="oninput" />

事件处理

<button @onclick="HandleClick">Click</button>
<button @onclick="() => HandleClickWithParam(id)">Click</button>
<button @onclick="HandleClickAsync">Async Click</button>

渲染优化

避免不必要的渲染

• 对列表项使用 @key
• 适当实现 ShouldRender()
• 谨慎调用 StateHasChanged()
• 避免在循环中使用内联处理程序

虚拟化

<Virtualize Items="@items" Context="item">
    <ItemContent>
        <div>@item.Name</div>
    </ItemContent>
</Virtualize>

状态管理

组件状态

• 使用私有字段保存组件状态
• 外部状态变更时调用 StateHasChanged()
• 使用 InvokeAsync 进行线程安全的更新

级联参数

<CascadingValue Value="@currentTheme">
    <ChildComponent />
</CascadingValue>


[CascadingParameter]
public Theme CurrentTheme { get; set; }

状态容器

• 创建可注入的状态服务
• 使用事件通知状态变更
• 复杂的状态管理可考虑使用 Fluxor

Blazor Server 与 WebAssembly

Blazor Server

• 状态保存在服务器上
• 通过 SignalR 建立实时连接
• 初始加载速度更快
• 需要稳定的连接
• 更适合内部应用

Blazor WebAssembly

• 完全在浏览器中运行
• 初始下载内容较大
• 支持离线运行（具备 PWA 能力）
• 不占用每位用户对应的服务器资源
• 更适合公共应用

API 集成

HTTP 客户端

@inject HttpClient Http

private async Task LoadData()
{
    users = await Http.GetFromJsonAsync<List<User>>("api/users");
}

错误处理

try
{
    users = await Http.GetFromJsonAsync<List<User>>("api/users");
}
catch (HttpRequestException ex)
{
    errorMessage = "Failed to load users";
}

错误处理

错误边界

<ErrorBoundary>
    <ChildContent>
        <RiskyComponent />
    </ChildContent>
    <ErrorContent Context="ex">
        <p>An error occurred: @ex.Message</p>
    </ErrorContent>
</ErrorBoundary>

全局错误处理

• 实现 IErrorBoundary 进行自定义处理
• 将错误记录到服务器
• 显示对用户友好的消息

测试

bUnit 测试

[Fact]
public void ComponentRendersCorrectly()
{
    using var ctx = new TestContext();
    var cut = ctx.RenderComponent<Counter>();

    cut.Find("p").MarkupMatches("<p>Current count: 0</p>");
    cut.Find("button").Click();
    cut.Find("p").MarkupMatches("<p>Current count: 1</p>");
}

身份验证

设置

• 使用 AuthenticationStateProvider
• 使用 AuthorizeView 控制 UI 的条件显示
• 在页面上使用 [Authorize] 特性
• 为 JWT 实现自定义身份验证状态提供程序

AuthorizeView

<AuthorizeView>
    <Authorized>
        <p>Welcome, @context.User.Identity?.Name!</p>
    </Authorized>
    <NotAuthorized>
        <p>Please log in.</p>
    </NotAuthorized>
</AuthorizeView>

性能提示

• 对动态列表使用 @key
• 对大型列表实现虚拟化
• 使用 @if 延迟加载组件
• 尽量减少 JavaScript 互操作调用
• 在 .NET 8+ 中使用流式渲染