Blazor 模板化元件開發指南

翻譯自 Waqas Anwar 2021年4月15日的文章《A Developer’s Guide To Blazor Templated Components》 ^[1]

在我之前的一篇文章 Blazor 元件入門指南中，我介紹了元件引數，並向您展示瞭如何將資料作為引數傳遞給 Blazor 元件以定製化其功能。在這篇文章中，我將更進一步向您展示，如何將一個或多個 UI 模板作為引數傳遞給一個稱之為模板化元件的不同型別的 Blazor 元件。

下載原始碼^[2]

Blazor 模板化元件概述

Blazor 模板化元件是一種接受將一個或多個 UI 模板作為引數的元件。這有助於元件的可重用性，因為您只需要建立一次模板化元件，然後使用該元件的每個頁面都可以提供其 UI 模板，模板化元件可以根據頁面需求渲染此 UI 模板。

本文中的模板化元件示例包括：

一個允許使用者指定表格表頭、行和頁尾模板的表格元件。
一個允許使用者呈現具有相同外觀和體驗而具有不同內容的小部件元件。
一個允許使用者指定一個模板來呈現專案符號或編號等列表項的列表元件。
一個允許使用者以列表、網格或卡片檢視來顯示資料的列表元件。

當我們建立 Blazor 元件的一個引數時，我們通常將其型別指定為 string、int 或者其他內建 .NET 資料型別。為了建立一個模板化元件，我們需要建立型別為 RenderFragment 或 RenderFragment<T> 的元件引數。RenderFragment 允許我們提供一個可以由模板化元件渲染的 UI 內容片段（作為一個委託實現，將其內容寫入到 RenderTreeBuilder）。

[Parameter]

public RenderFragment HeaderTemplate { get; set; }

RenderFragment<T> 更進一步，允許我們傳入引數的型別 T，可以用它來自定義模板化元件的輸出。

[Parameter]

public RenderFragment<T> RowTemplate { get; set; }

從一個例項開始

為了詳細瞭解模板化元件，我決定構建一個 TableWidget 模板化元件，它允許我們自定義不同格式的表頭、行和頁尾。在建立第一個模板化元件之前，我們先來建立一個新的 Blazor Server 應用程式並新增其基本功能，以表格格式呈現一些資料。

在 Blazor Server 應用程式中建立一個 Data 資料夾，並在 Data 資料夾中新增以下兩個模型類。

Product.cs

public class Product

{

    public int Id { get; set; }

    public string Title { get; set; }

    public decimal Price { get; set; }

    public int Quantity { get; set; }

}

Order.cs

public class Order

{

    public int Id { get; set; }

    public string OrderNo { get; set; }

    public DateTime OrderDate { get; set; }

    public string Status { get; set; }

    public decimal OrderTotal { get; set; }

}

在專案中建立一個 Services 資料夾，並在 Services 資料夾中新增如下的 IProductService 和 ProductService。在本教程中，我僅返回一些用於生成表格的模擬資料。

IProductService.cs

public interface IProductService

{

    List<Product> GetTopSellingProducts();

}

ProductService.cs

public class ProductService : IProductService

{

    public List<Product> GetTopSellingProducts()

    {

        return new List<Product>()

        {

            new Product()

            {

                Id = 1,

                Title = "Wireless Mouse",

                Price = 29.99m,

                Quantity = 3

            },

            new Product()

            {

                Id = 2,

                Title = "HP Headphone",

                Price = 79.99m,

                Quantity = 4

            },

            new Product()

            {

                Id = 3,

                Title = "Sony Keyboard",

                Price = 119.99m,

                Quantity = 5

            }

        };

    }

}

接下來，在同一 Services 資料夾中建立 IOrderService 和 OrderService 並新增一些用於生成表格的模擬訂單資料。

IOrderService.cs

public interface IOrderService

{

    List<Order> GetLatestOrders();

}

OrderService.cs

public class OrderService : IOrderService

{

    public List<Order> GetLatestOrders()

    {

        return new List<Order>()

        {

            new Order()

            {

                Id = 1,

                OrderNo = "12345",

                OrderDate = DateTime.Today.AddDays(-2),

                Status = "Pending",

                OrderTotal = 399.99m

            },

            new Order()

            {

                Id = 2,

                OrderNo = "67890",

                OrderDate = DateTime.Today.AddDays(-5),

                Status = "Completed",

                OrderTotal = 199.99m

            },

            new Order()

            {

                Id = 3,

                OrderNo = "13579",

                OrderDate = DateTime.Today.AddDays(-7),

                Status = "Completed",

                OrderTotal = 249.99m

            }

        };

    }

}

我們需要使用依賴注入將上述服務注入到 Blazor 元件中，為此，我們需要在 Startup.cs 檔案中註冊上述服務。如果您想了解關於依賴注入的更多知識，可以閱讀我的文章 A Step by Step Guide to ASP.NET Core Dependency Injection^[3]。

Startup.cs

public void ConfigureServices(IServiceCollection services)

{

    services.AddRazorPages();

    services.AddServerSideBlazor();

    services.AddSingleton<WeatherForecastService>();

    services.AddScoped<IOrderService, OrderService>();

    services.AddScoped<IProductService, ProductService>();

}

接下來，在專案 Pages 資料夾中建立 Blazor 元件 Dashboard.razor 及其對應的程式碼隱藏檔案 Dashboard.razor.cs。如果您不熟悉 Blazor 元件及程式碼隱藏檔案，請閱讀我的文章 Blazor 元件入門指南。

元件的程式碼隱藏檔案 Dashboard.razor.cs 中同時注入了 IOrderService 和 IProductService，然後我們將使用 GetLatestOrders 和 GetTopSellingProducts 方法來填充我們的本地 Orders 和 Products 列表。

Dashboard.razor.cs

public partial class Dashboard

{

    [Inject]

    private IOrderService OrderService { get; set; }

    [Inject]

    private IProductService ProductService { get; set; }

    private List<Order> Orders { get; set; }

    private List<Product> Products { get; set; }

    protected override void OnInitialized()

    {

        Orders = OrderService.GetLatestOrders();

        Products = ProductService.GetTopSellingProducts();

    }

}

Razor 元件檢視檔案將簡單地在 Orders 和 Products 上執行 foreach 迴圈，並生成 HTML 表格。

@page "/dashboard"

<h1>Dashboard</h1>

<br />

<div class="row">

   <div class="col">

      @if (Orders != null)

      {

          <table class="table table-striped table-bordered">

             <thead class="thead-dark">

                <tr>

                   <th scope="col">Order</th>

                   <th scope="col">Date</th>

                   <th scope="col">Status</th>

                   <th scope="col">Total</th>

                </tr>

             </thead>

             <tbody>

                @foreach (var order in Orders)

                {

                    <tr>

                       <td>@order.OrderNo</td>

                       <td>@order.OrderDate.ToShortDateString()</td>

                       <td>@order.Status</td>

                       <td>@order.OrderTotal</td>

                    </tr>

                }

             </tbody>

          </table>

      }

   </div>

   <div class="col">

      @if (Products != null)

      {

          <h3>Top Selling Products</h3>

          <table class="table table-striped table-bordered">

             <thead class="thead-dark">

                <tr>

                   <th scope="col">Title</th>

                   <th scope="col">Price</th>

                   <th scope="col">Quantity</th>

                </tr>

             </thead>

             <tbody>

                @foreach (var product in Products)

                {

                    <tr>

                       <td>@product.Title</td>

                       <td>@product.Price</td>

                       <td>@product.Quantity</td>

                    </tr>

                }

             </tbody>

          </table>

      }

   </div>

</div>

此時如果您執行專案，將在頁面上看到以下兩個表格。

截至目前，我們尚沒有建立任何模板化元件，但您會感覺到我們很快將需要一個，因為上面顯示的訂單和產品表格幾乎都具有相同的外觀和體驗，並且我們在上面的 foreach 迴圈中複製了大量的 HTML 來生成這兩張表格。一個好注意是，建立一個模板化元件，然後重用該元件來生成上述兩張表格，並且仍然能夠自定義它們顯示的表頭和資料行。讓我們來建立我們的第一個模板化元件，命名為 TableWidget 元件。

建立 Blazor 模板化元件

在 Shared 資料夾中新建一個 Razor 元件 TableWidget.razor，並在其中新增以下程式碼：

TableWidget.razor

@typeparam TItem

<br />

<h3>@Title</h3>

<table class="table table-striped table-bordered">

   <thead class="thead-dark">

      <tr>

         @HeaderTemplate

      </tr>

   </thead>

   <tbody>

      @foreach (var item in Items)

      {

      <tr>

         @RowTemplate(item)

      </tr>

      }

   </tbody>

   <tfoot>

      <tr>

         @FooterTemplate

      </tr>

   </tfoot>

</table>

@code {

    [Parameter]

    public string Title { get; set; }

    [Parameter]

    public RenderFragment HeaderTemplate { get; set; }

    [Parameter]

    public RenderFragment<TItem> RowTemplate { get; set; }

    [Parameter]

    public RenderFragment FooterTemplate { get; set; }

    [Parameter]

    public IReadOnlyList<TItem> Items { get; set; }

}

我們的 TableWidget 元件包含以下三個模板：

[Parameter]

public RenderFragment HeaderTemplate { get; set; }

[Parameter]

public RenderFragment<TItem> RowTemplate { get; set; }

[Parameter]

public RenderFragment FooterTemplate { get; set; }

HeaderTemplate 允許使用者在表格的表頭中呈現任意 UI 模板。此模板用於在 thead 元素內渲染表格表頭的單元格。

<thead class="thead-dark">

   <tr>

      @HeaderTemplate

   </tr>

</thead>

FooterTemplate 與 HeaderTemplate 類似，它允許使用者在表格的頁尾中呈現任意 UI 模板。此模板用於在 tfoot 元素內渲染表格頁尾的單元格。

<tfoot>

   <tr>

      @FooterTemplate

   </tr>

</tfoot>

RowTemplate 的型別為 RanderFragment<TItem>，它允許使用者使用任意的 .NET 型別渲染 UI 模板。該型別不是固定的，而是使用元件頂部的 @typeparam 指令宣告為一個泛型型別。

@typeparam TItem

我們還在元件中建立了一個 TItem 物件的集合，以便我們可以迭代該集合生成表格的行。

[Parameter]

public IReadOnlyList<TItem> Items { get; set; }

我們將要傳入 UI 模板中的 TItem 型別的物件會使用以下 foreach 迴圈進行渲染。您很快就會看到這將如何幫助我們使用相同的 TableWidget 元件同時渲染產品和訂單表格。

<tbody>

   @foreach (var item in Items)

   {

       <tr>

          @RowTemplate(item)

       </tr>

   }

</tbody>

使用 Blazor 模板化元件的不同方式

現在是時候來實踐一下我們的 TableWidget 元件了，我們可以通過不同的方式使用這個元件。用下面的 TableWidget 元件替換我們前面生成的 Recent Orders 表格。

<div class="col">

   @if (Orders != null)

   {

       <TableWidget Title="Recent Orders" Items="Orders">

          <HeaderTemplate>

             <th scope="col">Order</th>

             <th scope="col">Date</th>

             <th scope="col">Status</th>

             <th scope="col">Total</th>

          </HeaderTemplate>

          <RowTemplate>

             <td>@context.OrderNo</td>

             <td>@context.OrderDate.ToShortDateString()</td>

             <td>@context.Status</td>

             <td>@context.OrderTotal</td>

          </RowTemplate>

       </TableWidget>

   }

</div>

在上面的程式碼片段中，Items 屬性是使用我們的從服務獲取的 Orders 列表進行初始化的。然後我們選擇使用 HeaderTemplate 和 RowTemplate 來生成表格的表頭和資料行。您可能在想 context 是從哪裡來的？context 是一個隱式引數，所有型別為 RenderFragment<T> 的元件引數都可以使用。我們可以使用 context 訪問我們正在處理物件的屬性。在上面的示例中，context 將向模板提供訂單資訊。

如果此時您執行專案，會在頁面上看到以下兩個表格。現在，最近的訂單（Recent Orders）表格是使用我們的 TableWidget 元件生成的了。

讓我們重用 TableWidget 元件來生成熱賣產品（Top Selling Products）表格。這一次，我們傳遞了 Products 列表給它，還指定了我們自己的 Context="product"，這意味著現在我們可以使用 product 取代隱式引數 context 來訪問產品的屬性。

<div class="col">

   @if (Products != null)

   {

       <TableWidget Title="Top Selling Products" Items="Products" Context="product">

          <HeaderTemplate>

             <th scope="col">Title</th>

             <th scope="col">Price</th>

             <th scope="col">Quantity</th>

          </HeaderTemplate>

          <RowTemplate>

             <td>@product.Title</td>

             <td>@product.Price</td>

             <td>@product.Quantity</td>

          </RowTemplate>

       </TableWidget>

   }

</div>

您還可以在模板級別指定上下文（Context），如下面的示例所示，其中將 Context="product" 新增到了 RowTemplate。

<TableWidget Title="Top Selling Products" Items="Products">

   <HeaderTemplate>

      <th scope="col">Title</th>

      <th scope="col">Price</th>

      <th scope="col">Quantity</th>

   </HeaderTemplate>

   <RowTemplate Context="product">

      <td>@product.Title</td>

      <td>@product.Price</td>

      <td>@product.Quantity</td>

   </RowTemplate>

</TableWidget>

現在如果您執行該專案，您將看到頁面上顯示了以下兩個表格，但是我們知道這次這兩個表格是使用我們的模板化元件 TableWidget 渲染的。該示例清楚地演示了，同一個模板化元件可用於生成不同型別的 UI，並且可以根據我們的應用程式需求渲染不同型別的物件。

下面讓我們通過另外兩個例子重用一下我們的 TableWidget 元件，它們將顯示同樣的最近訂單（Recent Orders）和熱銷產品（Top Selling Products），但佈局略有改變。

<div class="row">

   <div class="col">

      @if (Orders != null)

      {

          <TableWidget Title="Recent Orders" Items="Orders">

             <HeaderTemplate>

                <th scope="col" colspan="2">Order Details</th>

                <th scope="col">Status</th>

                <th scope="col">Total</th>

             </HeaderTemplate>

             <RowTemplate Context="order">

                <td colspan="2">

                   <b>Order No: </b>@order.OrderNo

                   <br />

                   <b>Order Date: </b>@order.OrderDate.ToShortDateString()

                </td>

                <td>@order.Status</td>

                <td>@order.OrderTotal</td>

             </RowTemplate>

          </TableWidget>

      }

   </div>

   <div class="col">

      @if (Products != null)

      {

          <TableWidget Title="Top Selling Products" Items="Products" TItem=”Product”>

             <RowTemplate Context="product">

                <td>

                   <h2>@product.Title</h2>

                   <h4><b>@product.Price.ToString("C")</b></h4>

                </td>

             </RowTemplate>

             <FooterTemplate>

                <td class="text-right"><b>Last 30 Days</b></td>

             </FooterTemplate>

          </TableWidget>

      }

   </div>

</div>

在使用泛型型別元件時，會盡可能推斷型別引數。不過，我們可以選擇使用一個特性來顯式指定型別，該特性的名稱與型別引數相同，在上面的示例中是 TItem。

此時如果您執行該專案，您將在頁面上看到使用同一個 TableWidget 模板化元件渲染的全部四個表格。

建立通用模板化元件

我們的 TableWidget 元件很好，我們已見識了重用它的多個示例，但該元件的問題是它只生成了 HTML 表格。如果我們想要建立一個更通用的元件，可以重用它來生成任何型別的 UI（比如：表格、卡片、專案符號等）。我們可以通過從模板化元件中刪除所有的標籤來輕鬆地建立這樣一個元件。讓我們來建立一個通用的 ListWidget 元件，來實戰練習一下這種元件。

在 Shared 資料夾中建立一個新的 ListWidget.razor 元件，並在其中新增以下程式碼。這次在元件中沒有 HTML 標籤，在 foreach 迴圈中僅有一個 ItemTemplate。這意味著我們可以使用這個 ListWidget 元件自由地生成任意型別的列表。

ListWidget.razor

@typeparam TItem

@foreach (var item in Items)

{

    @ItemTemplate(item)

}

@code {

    [Parameter]

    public RenderFragment<TItem> ItemTemplate { get; set; }

    [Parameter]

    public IReadOnlyList<TItem> Items { get; set; }

}

假如我們想要使用這個 ListWidget 元件生成 bootstrap 列表，那麼我們可以使用下面的程式碼段來實現這一操作。

<ul class="list-group">

   <li class="list-group-item d-flex justify-content-between align-items-center active">

      Latest Products

   </li>

   <ListWidget Items="Products" Context="product">

      <ItemTemplate>

         <li class="list-group-item d-flex justify-content-between align-items-center">

            @product.Title

            <b>@product.Price.ToString("C")</b>

            <span class="badge badge-primary badge-pill">

            @product.Quantity

            </span>

         </li>

      </ItemTemplate>

   </ListWidget>

</ul>

執行該專案，您將看到以 bootstrap 列表方式生成的相同產品的列表。

現在，假設您有另一個頁面，其中需要使用 div 和 a 標籤以不同形式展示產品列表，那麼您可以再次重用相同的 ListWidget 元件，這次生成如下標記：

<div class="list-group">

   <a class="list-group-item d-flex justify-content-between align-items-center active">

   Latest Products

   </a>

   <ListWidget Items="Products" Context="product" TItem="Product">

      <ItemTemplate>

         <a href="#" class="list-group-item list-group-item-action flex-column align-items-start">

            <div class="d-flex w-100 justify-content-between">

               <h5 class="mb-1"><b>@product.Title</b></h5>

               <small class="text-muted">@product.Quantity units left</small>

            </div>

            <p class="mb-1">@product.Price.ToString("C")</p>

         </a>

      </ItemTemplate>

   </ListWidget>

</div>

執行該專案，您將看到類似以下內容的輸出。

總結

在本教程中，我概述了 Blazor 模板化元件，並建立了兩種型別的模板化元件。然後，我們實踐了幾個重用 TableWidget 和 ListWidget 元件來生成不同型別標記的例子。我不得不承認，模板化元件是 Blazor 開發者工具箱中的一個很好的補充，我們可以使用這些元件建立一些令人驚歎的可重用元件。

Blazor 模板化元件開發指南