避免覆盖 ASP.NET Core Blazor 中的参数

作者 Robert Haken

本文介绍如何在重新呈现期间避免在 Blazor 应用中覆盖参数。

重写参数

Blazor 框架通常会施加安全的父级到子级参数的赋值：

• 不会意外覆盖参数。
• 最大程度地减少副作用。 例如，可避免附加的呈现，因为它们可能会创建无限的呈现循环。

当父组件重新呈现时，子组件会接收可能覆盖现有值的新参数值。 当开发带有一个或多个数据绑定参数的组件，并且开发人员直接写入子组件中的参数时，经常会发生意外覆盖子组件中的参数值：

• 子组件通过父组件中的一个或多个参数值呈现。
• 子级直接写入参数的值。
• 父组件重新呈现并覆盖子参数的值。

覆盖参数值的可能性也会延伸到子组件的属性 set 访问器中。

重要

我们的通用指南不是创建在首次呈现后直接向自身参数写入的组件。

请考虑使用以下 ShowMoreExpander 组件，它们会：

• 呈现标题。
• 选中时显示子内容。
• 允许使用组件参数 (InitiallyExpanded) 设置初始状态。

在下面的 ShowMoreExpander 组件演示了已覆盖参数之后，会显示修改后的 ShowMoreExpander 组件以演示此方案的正确方法。 下面的示例可以放置在本地示例应中，以体验所述的行为。

ShowMoreExpander.razor:

<div @onclick="ShowMore" class="card bg-light mb-3" style="width:30rem">
    <div class="card-header">
        <h2 class="card-title">Show more (<code>Expanded</code> = @InitiallyExpanded)</h2>
    </div>
    @if (InitiallyExpanded)
    {
        <div class="card-body">
            <p class="card-text">@ChildContent</p>
        </div>
    }
</div>

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

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    private void ShowMore() => InitiallyExpanded = true;
}

ShowMoreExpander 组件会添加到可调用 StateHasChanged 的以下 Expanders 父组件中：

• 在开发人员代码中调用 StateHasChanged 会向组件通知其状态已更改，并且通常会将组件重新呈现加入队列以更新 UI。 StateHasChanged 稍后将在 ASP.NET Core Razor 组件生命周期和 ASP.NET Core Razor 组件呈现中详细介绍。
• 按钮的 @onclick 指令特性会将事件处理程序附加到按钮的 onclick 事件。 稍后在 ASP.NET Core Blazor 事件处理中更详细地介绍事件处理。

Expanders.razor:

@page "/expanders"

<PageTitle>Expanders</PageTitle>

<h1>Expanders Example</h1>

<ShowMoreExpander InitiallyExpanded="false">
    Expander 1 content
</ShowMoreExpander>

<ShowMoreExpander InitiallyExpanded="false" />

<button @onclick="StateHasChanged">Call StateHasChanged</button>

最初，在设置 InitiallyExpanded 属性时，ShowMoreExpander 组件独立地作出行为。 子组件会按预期方式维护其状态。

如果在父组件中调用 StateHasChanged，则 Blazor 框架会重新呈现子组件（如果其参数可能已更改）：

• 对于 Blazor 显式检查的一组参数类型，如果 Blazor 检测到有任何参数发生更改，则会重新呈现子组件。
• 对于未选中的参数类型，无论参数是否发生更改，Blazor 都会呈现子组件。 子内容属于此类参数类型，因为子内容属于 RenderFragment 类型，它是引用其他可变对象的委托。

对于 Expanders 组件：

• 第一个 ShowMoreExpander 组件在可能可变的 RenderFragment 中设置子内容，因此在父组件中调用 StateHasChanged 会自动重新呈现该组件，并可能将 InitiallyExpanded 的值覆盖为其初始值 false。
• 第二个 ShowMoreExpander 组件未设置子内容。 因此，不存在可能可变的 RenderFragment。 在父组件中调用 StateHasChanged 不会自动呈现子内容，因此组件的 InitiallyExpanded 值不会被覆盖。

要维持在前述情况中的状态，请在 ShowMoreExpander 组件中使用私有字段来保留它的状态。

以下经修定的 ShowMoreExpander 组件：

• 接受父项中的 InitiallyExpanded 组件参数值。
• 将组件参数值分配给 OnInitialized 事件中的私有字段 (expanded)。
• 使用私有字段来维护其内部切换状态，该状态演示如何避免直接写入参数。

注意

此部分中的建议可扩展到组件参数 set 访问器中的类似逻辑，这可能会产生类似的不良副作用。

ShowMoreExpander.razor:

<div @onclick="Expand" class="card bg-light mb-3" style="width:30rem">
    <div class="card-header">
        <h2 class="card-title">Show more (<code>Expanded</code> = @expanded)</h2>
    </div>
    @if (expanded)
    {
        <div class="card-body">
            <p class="card-text">@ChildContent</p>
        </div>
    }
</div>

@code {
    private bool expanded;

    [Parameter]
    public bool InitiallyExpanded { get; set; }

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    protected override void OnInitialized() => expanded = InitiallyExpanded;

    private void Expand() => expanded = true;
}

注意

修改后的 ShowMoreExpander 不会反映初始化后对 InitiallyExpanded 参数的更改 (OnInitialized)。 在某些情况下，已初始化的组件可能会接收新的参数值。 例如，在使用相同组件呈现不同详细信息视图的主从视图中，或者当 /item/{id} 路由参数更改以显示不同的项目时，可能会发生这种情况。

请考虑使用以下 ToggleExpander 组件，它们会：

• 允许从内部和外部更改状态。
• 即使重复使用同一组件实例，也处理新的参数值。

ToggleExpander.razor:

<div class="card bg-light mb-3" style="width:30rem">
    <div @onclick="Toggle" class="card-header">
        <h2 class="card-title">Toggle (<code>Expanded</code> = @expanded)</h2>
    </div>
    @if (expanded)
    {
        <div class="card-body">
            <p class="card-text">@ChildContent</p>
        </div>
    }
</div>

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

    [Parameter]
    public EventCallback<bool> ExpandedChanged { get; set; }

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    private bool expanded;

    protected override void OnParametersSet() => expanded = Expanded;

    private async void Toggle()
    {
        expanded = !expanded;
        await ExpandedChanged.InvokeAsync(expanded);
    }
}

ToggleExpander 组件应与 @bind-Expanded="{field}" 绑定语法一起使用，从而支持对参数进行双向同步。

ExpandersToggle.razor:

@page "/expanders-toggle"

<PageTitle>Expanders Toggle</PageTitle>

<h1>Expanders Toggle</h1>

<ToggleExpander @bind-Expanded="expanded">
    Expander content
</ToggleExpander>

<button @onclick="Toggle">Toggle</button>

<button @onclick="StateHasChanged">Call StateHasChanged</button>

@code {
    private bool expanded;

    private void Toggle() => expanded = !expanded;
}

有关父母子女绑定的详细信息，请参阅以下资源：

• 与组件参数绑定
• 绑定到两个以上的组件
• Blazor双向绑定错误 (dotnet/aspnetcore #24599)

有关更改检测的详细信息，包括有关 Blazor 检查的完全匹配类型的信息，请参阅 ASP.NET Core Razor 组件呈现。