Blazor 元件庫開發指南

翻譯自 Waqas Anwar 2021年5月21日的文章《A Developer’s Guide To Blazor Component Libraries》 ^[1]

Blazor 的核心是元件，我們建立不同型別的元件並在整個專案中重用它們。沒有人想重複造輪子，因此建立一個可重用的 Blazor 元件庫始終是一個好主意，這些元件不僅可以在多個專案之間共享，還可以作為 NuGet 包與其他人共享。Blazor 允許我們基於一個名為 Razor 類庫（Razor Class Library）的新模板建立這樣的元件庫，在本文中，我將向您演示如何建立這樣一個庫，不僅僅共享元件，還共享靜態內容（比如圖片、樣式表等等）。

下載原始碼^[2]

建立一個 Razor 元件庫

在 Visual Studio 2019 中建立一個新的名為 BlazorClassLibraryDemo 的 Blazor Server 應用程式，確保您可以正常構建和執行該專案。如果您不確定如何建立 Blazor Server 應用程式，那麼我建議您閱讀我的文章《Blazor Server 和 WebAssembly 應用程式入門指南》

要在 Blazor 專案中新增一個新元件庫，請右鍵點選解決方案並選擇 新增 > 新建專案... 選項。從專案模板列表中選擇 Razor 類庫（Razor Class Library） 專案模板。

為專案提供任意合適的名稱，我這裡將其命名為 MyComponentsLibrary。

然後，會詢問您選擇一些其他設定項，直接點選建立按鈕就好。

預設情況下，模板會建立一個名為 Component1.razor 的示例元件和一些附加檔案。在開始建立我們的第一個共享元件之前，我們需要刪除 Component1.razor、ExampleJsInterop.cs 以及 wwwroot 資料夾中的所有內容，以便我們有一個純淨的開始。

在 Razor 類庫中建立一個元件

讓我們在 Razor 類庫專案 MyComponentsLibrary 中建立我們的第一個可重用的共享元件。右鍵點選類庫專案並選擇 新增 > 新建項… 選項。選擇 Razor 元件 模板並指定元件名稱 TableWidget.razor。

如果您希望將 C# 程式碼與元件檢視分開，您還可以新增程式碼隱藏檔案 TableWidget.razor.cs。該 TableWidget 元件是一個簡單的模板化元件，可用於從任何物件列表生成 HTML 表格。如果您想了解有關 Blazor 模板化元件的更多知識，那麼您可以閱讀我的文章《Blazor 模板化元件開發指南》。

在 TableWidget.razor 元件檢視檔案中新增以下標記。

TableWidget.razor

@typeparam TItem

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

    <thead class="thead-green">

        <tr>

            @HeaderTemplate

        </tr>

    </thead>

    <tbody>

    @foreach (var item in Items)

    {

        <tr>

            @RowTemplate(item)

        </tr>

    }

    </tbody>

    <tfoot>

        <tr>

            @FooterTemplate

        </tr>

    </tfoot>

</table>

下面是 TableWidget 元件的程式碼隱藏檔案。該元件具有 RenderFragment 型別的 Header、Row 和 Footer 模板，用於在檢視中生成 HTML 表格的表頭、資料行和頁尾。

TableWidget.razor.cs

using System.Collections.Generic;

using Microsoft.AspNetCore.Components;

namespace MyComponentsLibrary

{

    public partial class TableWidget<TItem>

    {

        [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; }

    }

}

我們在 Razor 類庫中建立的每個可重用元件還可以有對應的樣式表來定義元件的外觀。例如，如果我們希望我們的 TableWidget 元件生成帶有深綠色表頭的表格，我們可以在 TableWidget.razor.css 檔案中定義元件的樣式。

TableWidget.razor.css

.thead-green {

    background-color: darkgreen;

    color: white;

}

使用 Razor 類庫中的 Razor 元件

現在我們已經在類庫專案中定義了我們的 TableWidget 元件，是時候在我們的 Blazor 專案中使用這個元件了。右鍵單擊解決方案資源管理器中的 依賴項（Dependencies） 節點，然後從上下文選單中選擇 新增專案引用...（Add Project Reference...） 選項。選中 MyComponentsLibrary 專案並點選確定。

如果您想在多個頁面上使用 TableWidget 元件，那麼推薦您在 _Imports.razor 檔案中新增該類庫的引用。

@using MyComponentsLibrary

Blazor 專案模板預設生成一個 FetchData.razor 頁面，顯示來自後端服務的天氣預報物件。我們可以在此頁面上測試我們的 TableWidget 元件。開啟 FetchData.razor 檔案，並使用 TableWidget 元件替換其中的 HTML 表格，如下面的程式碼片段所示。

FetchData.razor

@page "/fetchdata"

@using BlazorClassLibraryDemo.Data

@inject WeatherForecastService ForecastService

<h1>Weather forecast</h1>

@if (forecasts == null)

{

    <p><em>Loading...</em></p>

}

else

{

    <TableWidget Items="forecasts" Context="forecast">

        <HeaderTemplate>

            <th>Date</th>

            <th>Temp. (C)</th>

            <th>Temp. (F)</th>

            <th>Summary</th>

        </HeaderTemplate>

        <RowTemplate>

            <td>@forecast.Date.ToShortDateString()</td>

            <td>@forecast.TemperatureC</td>

            <td>@forecast.TemperatureF</td>

            <td>@forecast.Summary</td>

        </RowTemplate>

    </TableWidget>

}

@code {

    private WeatherForecast[] forecasts;

    protected override async Task OnInitializedAsync()

    {

        forecasts = await ForecastService.GetForecastAsync(DateTime.Now);

    }

}

執行該專案，您會看到使用我們的 TableWidget 元件生成的天氣預報表格。現在，您可以在多個頁面或專案中重用該 TableWidget 元件，並且將會看到始終為您生成相同的表格。

使用 Razor 類庫中的圖片

Razor 類庫可以公開靜態資源（比如圖片），並且這些資源可以由使用該庫的 Blazor 應用程式使用。讓我們在 MyComponentsLibrary 專案的 wwwroot/images 資料夾中新增一個圖片 blazor_logo.jpg。為了在 Blazor 元件中使用此圖片，請在 MyComponentsLibrary 專案中新增一個名為 BlazorLogo.razor 的元件。

使用簡單的 img 標籤將 blazor_logo.jpg 圖片新增到 BlazorLogo.razor 元件中。

BlazorLogo.razor

<img src="data:images/blazor_logo.jpg" alt="Blazor Logo"/>

要在 Blazor 應用程式中使用此 BlazorLogo.razor 元件，請從我們上面建立的 Blazor 示例應用中開啟 Index.razor 頁面，然後直接使用 BlazorLogo 元件，如下面的程式碼片段所示。

Index.razor

<h1>Hello, Blazor!</h1>

<BlazorLogo></BlazorLogo>

執行該專案，您會注意到圖片並未如預期那樣顯示出來。這是因為無法從類庫專案外訪問圖片的相對路徑 images/blazor_logo.jpg。

要解決上述問題，您需要使用下面給出的特殊路徑語法：

_content/{Razor Class Library Name}/{Path to file}

在上面的語法中，{Razor Class Library Name} 是類庫名稱的佔位符（例如 MyComponentsLibrary），{Path to file} 是 wwwroot 資料夾下的檔案路徑。

讓我們使用上面描述的特殊語法來修復我們的圖片路徑。

BlazorLogo.razor

<img src="_content/MyComponentsLibrary/images/blazor_logo.jpg" alt="Blazor Logo"/>

再次執行專案，這次您會注意到圖片按預期顯示了。

我們還可以使用上述特殊語法直接訪問 Razor 類庫中的圖片。例如，下面的程式碼片段將使用 BlazorLogo 元件以及 img 標籤顯示 Razor 類庫中的圖片。請注意，Blazor 應用中的 img 標籤使用相同的特殊語法來訪問 MyComponentsLibrary 中的圖片。

Index.razor

<h1>Hello, Blazor!</h1>

<h4>Showing Image from a Component available inside Class Library</h4>

<BlazorLogo></BlazorLogo>

<h4>Showing Image directly from Class Library</h4>

<img src="_content/MyComponentsLibrary/images/blazor_logo.jpg" alt="Blazor Logo" />

再次執行該專案，這次您應該會看到相同的圖片使用了兩種不同的方式顯示兩次。

使用 Razor 類庫中樣式表

我們還可以在 Razor 類庫中新增樣式表，並且 Blazor 應用程式可以使用這些樣式表中定義的樣式。讓我們在 wwwroot/css 資料夾中新增一個樣式表 components.css。

出於演示目的，讓我們新增一些與 img 標籤相關的樣式。

components.css

img

{

    background-color: lightgreen;

    padding: 5px;

    border: 1px solid black;

}

要在我們的 Blazor 應用程式中包含 components.css 檔案，我們可以使用與上面看到的相同的特殊語法。開啟 Blazor Server 應用程式中的 _Host.cshtml 檔案，並使用以下 link 標籤將 components.css 檔案包含在 head 標籤內。

_Host.cshtml

<head>

    <meta charset="utf-8" />

    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    ...

    <link href="~/_content/MyComponentsLibrary/css/components.css" rel="stylesheet" />

</head>

執行專案，您會發現我們在 components.css 檔案中定義的與 img 標籤相關的樣式被應用到了專案中的所有圖片上。

總結

我在本文中介紹了可重用元件的非常基礎的示例，但您可以藉此領會到 Razor 類庫的強大功能。開發者可以建立一些又酷又炫的可重用 Blazor 元件庫，這些庫不僅可以為您的專案新增一些高階功能，還可以提升開發速度。許多元件供應商已經開發了一些開源和商業庫，例如 MatBlazor^[3]、Radzen^[4]、Syncfusion^[5] 等。

Blazor 元件庫開發指南