ASP.NET Core Blazor 模板化组件

作者 Robert Haken

本文介绍模板化组件如何接受一个或多个 UI 模板作为参数，然后将其用作组件呈现逻辑的一部分。

模板化组件

模板化组件是接受一个或多个 UI 模板作为参数的组件，可用于组件的呈现逻辑。 通过使用模板化组件，可以创建更易于重用、更高级别的组件。 示例包括：

• 表组件，用户可通过它指定表的标题、行和页脚的模板。
• 列表组件，用户可通过它指定用于呈现列表中项的模板。
• 一个导航栏组件，允许用户指定用于开始内容和导航链接的模板。

通过指定一个或多个 RenderFragment 或 RenderFragment<TValue> 类型的组件参数来定义模板化组件。 呈现片段，表示要呈现的 UI 段。 RenderFragment<TValue> 采用可在调用呈现片段时指定的类型参数。

注意

有关 RenderFragment 的详细信息，请参阅 ASP.NET Core Razor 组件。

通常，模板化组件是有类型的组件，如以下 TemplatedNavBar 组件 (TemplatedNavBar.razor) 所示。 以下示例中的泛型类型 (<T>) 用于呈现 IReadOnlyList<T> 值，在本例中是一个组件的宠物列表，该组件显示带有指向宠物详细信息组件的链接的导航栏。

TemplatedNavBar.razor:

@typeparam TItem

<nav class="navbar navbar-expand navbar-light bg-light">
    <div class="container justify-content-start">
        @StartContent
        <div class="navbar-nav">
            @foreach (var item in Items)
            {
                @ItemTemplate(item)
            }
        </div>
    </div>
</nav>

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

    [Parameter, EditorRequired]
    public RenderFragment<TItem> ItemTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

在使用模板化组件时，可以使用与参数名称匹配的子元素来指定模板参数。 在下面的示例中，<StartContent>...</StartContent> 和 <ItemTemplate>...</ItemTemplate> 为 TemplatedNavBar 组件的 StartContent 和 ItemTemplate 提供 RenderFragment<TValue> 模板。

如果要为隐式子内容指定内容参数名称（不包含任何包装子元素），请在组件元素上指定 Context 属性。 在下面的示例中，Context 属性显示在 TemplatedNavBar 元素上，并应用于所有 RenderFragment<TValue> 模板参数。

Pets1.razor:

@page "/pets-1"

<PageTitle>Pets 1</PageTitle>

<h1>Pets Example 1</h1>

<TemplatedNavBar Items="pets" Context="pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-1")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

或者，您可以使用 RenderFragment<TValue> 子元素上的 Context 特性更改参数名称。 在下面的示例中，Context 是在 ItemTemplate 上设置的，而不是 TemplatedNavBar。

Pets2.razor:

@page "/pets-2"

<PageTitle>Pets 2</PageTitle>

<h1>Pets Example 2</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate Context="pet">
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-2")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

类型为 RenderFragment<TValue> 的组件参数具有一个名为 context 的隐式参数，可使用该参数。 在以下示例中，没有设置 Context。 @context.{PROPERTY} 向模板提供宠物值，其中 {PROPERTY} 是一个 Pet 属性：

Pets3.razor:

@page "/pets-3"

<PageTitle>Pets 3</PageTitle>

<h1>Pets Example 3</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{context.PetId}?ReturnUrl=%2Fpets-3")" class="nav-link">
            @context.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

使用泛型类型组件时，将在可能的情况下推断类型参数。 但是，可以使用名称与类型参数匹配的属性（上文示例中的 TItem）显式指定类型：

Pets4.razor:

@page "/pets-4"

<PageTitle>Pets 4</PageTitle>

<h1>Pets Example 4</h1>

<TemplatedNavBar Items="pets" Context="pet" TItem="Pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-4")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 2, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 4, Name = "Salem Saberhagen" },
        new Pet { PetId = 7, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

TemplatedNavBar 组件 (TemplatedNavBar.razor) 中提供的示例假设 Items 集合在初始呈现后不会更改；或者，如果它确实发生更改，则无需维持 ItemTemplate 中使用的组件/元素的状态。 有关无法预测此类使用情况的模板化组件，请参阅使用 @key 保留关系部分。

使用 @key 保留关系

模板化组件通常用于呈现项集合，例如表格或列表。 在这种一般情况下，我们不能假设用户将避免项模板定义中的有状态组件/元素，或者不会对 Items 集合进行其他更改。 对于此类模板化组件，必须使用 @key 指令属性保留关系。

注意

有关 @key 指令属性的详细信息，请参阅在 ASP.NET Core Blazor 中保留元素、组件和模型关系。

以下 TableTemplate 组件 (TableTemplate.razor) 演示了一个使用 @key 保留关系的模板化组件。

TableTemplate.razor:

@typeparam TItem

<table class="table">
    <thead>
        <tr>@TableHeader</tr>
    </thead>
    <tbody>
        @foreach (var item in Items)
        {
            <tr @key="@item">@RowTemplate(item)</tr>
        }
    </tbody>
</table>

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

    [Parameter, EditorRequired]
    public RenderFragment<TItem> RowTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

考虑以下 Pets5 组件 (Pets5.razor)，它演示了键入数据以保留模型关系的重要性。 在组件中，在 OnAfterRenderAsync 中添加宠物的每次迭代都会导致 Blazor 重新呈现 TableTemplate 组件。

Pets5.razor:

@page "/pets-5"

<PageTitle>Pets 5</PageTitle>

<h1>Pets Example 5</h1>

<TableTemplate Items="pets" Context="pet">
    <TableHeader>
        <th>ID</th>
        <th>Name</th>
    </TableHeader>
    <RowTemplate>
        <td><input value="@pet.PetId" /></td>
        <td><input value="@pet.Name" /></td>
    </RowTemplate>
</TableTemplate>


@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        // Insert new pet every 5 seconds
        if (pets.Count < 10)
        {
            await Task.Delay(5000);
            pets.Insert(0, new Pet() { PetId = pets.Count + 1, Name = "<new pet>" });
            StateHasChanged();
        }
    }

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

此演示使你可以：

• 从多个呈现的表格行中选择 <input>。
• 随着宠物集合自动增长，研究页面焦点的行为。

如果不在 TableTemplate 组件中使用 @key 指令属性，页面的焦点将保留在表格的同一索引位置（行）上，导致每次添加宠物时焦点都会发生移动。 若要演示这一点，请删除 @key 指令属性和值，重启应用，然后尝试在添加项时修改字段值。

其他资源

• ASP.NET Core Blazor 性能最佳做法
• 在 ASP.NET Core Blazor 中保留元素、组件和模型关系
• Blazor 示例 GitHub 存储库 (dotnet/blazor-samples)（下载方法）