使用MASA Blazor開發一個標準的查詢表格頁

capdiem發表於2022-03-10
Blazor

前言

大家好，我是開源專案 MASA Blazor 主要開發者之一，如果你還不瞭解MASA Blazor，可以訪問我們的 官網 和部落格 《初識MASA Blazor》 一探究竟。簡單來說，MASA Blazor 是一個基於 Material Design 設計語言的 Blazor 元件庫，dotNET開發者只需或者甚至不需要懂得 javascript 就能開發一個企業級中後臺系統。

我這次分享的主題是《使用MASA Blazor開發一個標準的查詢表格頁》，我會先從建立專案開始手擼一個沒有任何技巧的查詢表格頁，然後我會分享一些技巧和封裝的元件，實現快速開發。

手擼查詢表格頁

建立應用程式

關於如何安裝MASA Blazor模板，請移步 MASA.Blazor快速入門。

  1. 首先通過MASA Blazor模板預設的Server專案，專案命名為 MasaBlazorStandardTablePage。

    dotnet new --install MASA.Template
dotnet new masab -o MasaBlazorStandardTablePage

  2. 通過CLI執行應用程式，或直接通過vs啟動專案。

    cd MasaBlazorStandardTablePage
dotnet run

  3. 啟動成功後切換到 Fetch data 頁面，此頁面展示了一個簡單的使用了 MDataTable 的表格。

    default-fetch-data.png

支援單個查詢條件和搜尋

讓我們從最簡單的單個條件查詢開始。

將隨機資料替換成模擬資料

  1. 修改 WeatherForecastService，將隨機資料替換成死資料以便支援查詢功能。下面的程式碼更新了資料來源和 GetForecastAsync 查詢方法。

        public class WeatherForecastService
    {
        private readonly List<WeatherForecast> _data = new()
        {
            new() { Date = DateTime.Now.AddDays(-1), TemperatureC = 23, Summary = "Freezing" },
            new() { Date = DateTime.Now.AddDays(-1), TemperatureC = -10, Summary = "Bracing" },
            new() { Date = DateTime.Now.AddDays(-1), TemperatureC = 37, Summary = "Chilly" },
            new() { Date = DateTime.Now.AddDays(-2), TemperatureC = 29, Summary = "Cool" },
            new() { Date = DateTime.Now.AddDays(-3), TemperatureC = 11, Summary = "Mild" },
            new() { Date = DateTime.Now.AddDays(-4), TemperatureC = 35, Summary = "Warm" },
            new() { Date = DateTime.Now.AddDays(-5), TemperatureC = 41, Summary = "Balmy" },
            new() { Date = DateTime.Now.AddDays(-5), TemperatureC = -13, Summary = "Hot" },
            new() { Date = DateTime.Now.AddDays(-6), TemperatureC = 23, Summary = "Sweltering" },
            new() { Date = DateTime.Now.AddDays(-7), TemperatureC = 2, Summary = "Scorching" },
        };
        
        public Task<WeatherForecast[]> GetForecastAsync()
        {
            IEnumerable<WeatherForecast> res = _data.AsQueryable();

            return Task.FromResult(res.ToArray());
        }
    }

  2. 同時修改 FetchData.razor，因為 WeatherForecastService.GetForecastAsync() 刪除了 startDate 入參。

    protected override async Task OnInitializedAsync()
{
    await Task.Delay(1000); // 模擬真實環境，觸發Loading效果
    forecasts = await ForecastService.GetForecastAsync(); // here
}

新增查詢輸入框和搜尋按鈕

  1. 在 FetchData.razor 頁面中的 <p> 標籤下新增以下程式碼

    <MRow Class="pb-3">
    <MCol Cols="12">
        <MTextField @bind-Value="summary"
                    Dense
                    HideDetails="@("auto")"
                    Label="Summary"
                    Outlined>
        </MTextField>
    </MCol>
    <MCol Cols="12" Class="d-flex py-0 pb-3">
        <MSpacer></MSpacer>
        <MButton Color="primary" OnClick="OnSearch">搜尋</MButton>
    </MCol>
</MRow>

@code {
    private string summary;

    private async Task OnSearch()
    {
        forecasts = await ForecastService.GetForecastAsync(summary);
    }
}

    • Line 3,17

      定義了一個 string 型別的名為 summary 的變數，雙向繫結給了 MTextField 元件。MTextFiled 除了 @bind-Value 屬性用於設定雙向繫結，其他屬性的含義請閱讀 文件。

    • Line 12

      定義了一個搜尋按鈕，用於觸發查詢。

  2. 修改 WeatherForecastService.GetForecastAsync 方法，增加 summary 入參，並支援查詢。

    public Task<WeatherForecast[]> GetForecastAsync(string? summary = null)
{
    IEnumerable<WeatherForecast> res = _data.AsQueryable();

    if (!string.IsNullOrEmpty(summary))
    {
        res = res.Where(item => item.Summary.Contains(summary));
    }

    return Task.FromResult(res.ToArray());
}

summary-query.gif

支援多個查詢條件和重置

現在讓我們再新增一個高溫預警的選擇框來查詢不同高溫預警狀態的資料。

更新 WeatherForecastService 以支援根據高溫預警篩選資料

public Task<WeatherForecast[]> GetForecastAsync(string? summary = null, WarningSigns? warningSigns = null)
{
    IEnumerable<WeatherForecast> res = _data.AsQueryable();

    if (!string.IsNullOrEmpty(summary))
    {
        res = res.Where(item => item.Summary.Contains(summary));
    }

    if (warningSigns.HasValue)
    {
        res = warningSigns switch
        {
            WarningSigns.Yellow => res.Where(item => item.TemperatureC >= 35 && item.TemperatureC < 37),
            WarningSigns.Orange => res.Where(item => item.TemperatureC >= 37 && item.TemperatureC < 39),
            WarningSigns.Red => res.Where(item => item.TemperatureC >= 39),
            _ => res
        };
    }

    return Task.FromResult(res.ToArray());
}

增加高溫預警選擇框

  1. 在 Data 目錄下新增名為 WarningSigns 的列舉。

    public enum WarningSigns
{
    [Description("高溫黃色預警 35℃")]
    Yellow = 1,
    [Description("高溫橙色預警 37℃")]
    Orange,
    [Description("高溫紅色預警 39℃")]
    Red
}

  2. 引入 Masa.Utils.Enums 包，此包提供的 GetEnumObjectList 方法能輕鬆的將列舉的 Description 和列舉值用於 MSelect 元件的 Items。

    dotnet add package Masa.Utils.Enums

  3. 更新 FetchData.razor。

    <MRow Class="pb-3">
        <MCol Cols="12" Sm="6">
        <MTextField @bind-Value="@summary"
                    Label="Summary"
                    Dense
                    HideDetails="@("auto")"
                    Outlined>
        </MTextField>
    </MCol>
    <MCol Cols="12" Sm="6">
        <MSelect @bind-Value="warningSigns"
                Items="@(Enum<WarningSigns>.GetEnumObjectList<WarningSigns>())"
                ItemText="item => item.Name"
                ItemValue="item => item.Value"
                TValue="WarningSigns?"
                TItem="EnumObject<WarningSigns>"
                TItemValue="WarningSigns"
                Label="高溫警告"
                Clearable
                Dense
                HideDetails="@("auto")"
                Outlined>
        </MSelect>
    </MCol>
    <MCol Cols="12" Class="d-flex py-0 pb-3">
        <MSpacer></MSpacer>
        <MButton Class="mr-2" OnClick="OnReset">重置</MButton>
        <MButton Color="primary" OnClick="OnSearch">搜尋</MButton>
    </MCol>
</MRow>

@code {
    private WarningSigns? warningSigns;
    
    private Task OnReset()
    {
        summary = null;
        warningSigns = null;
        return OnSearch();
    }

    private async Task OnSearch()
    {
        forecasts = await ForecastService.GetForecastAsync(summary, warningSigns);
    }
}
    • Line 2,10

    通過設定 Sm="6" 可以讓螢幕尺寸大於768px時一行佔兩個 MCol ，實現 MTextField 和 MSelect 並排顯示。

    • Line 11-23,33,44

    第33行定義 warningSigns 變數用於接收 MSelect 選中的值，當然也可以通過設定值更新 MSelect 選中的值，只要設定了 @bind-Value 雙向繫結就行，就像第11行那樣。第12行使用了 Masa.Utils.Enums 提供的方法，返回了一個包含Name(Description)和Value(列舉值)的列表，賦值給了 MSelect.Items 。第44行將 warningSigns 的傳給查詢介面。

    • Line 27,35-40

    此處定義了一個重置按鈕，用於清空所有查詢輸入框的內容並重新整理表格。

select-query.gif

支援鍵入回車或選擇後觸發查詢

後來測試小姐姐說你這太難用了，回車不能觸發搜尋，選擇完也不能觸發搜尋。好吧好吧，我們現在加上。

鍵入回車後觸發

原理即捕捉 OnKeyDown 事件是否點選了 Enter 鍵。

<MTextField @bind-Value="@summary"
            OnKeyDown="HandleOnKeyDown"
            Label="Summary"
            Dense
            HideDetails="@("auto")"
            Outlined>
</MTextField>

@code {
    private async Task HandleOnKeyDown(KeyboardEventArgs args)
    {
        if (args.Code == "Enter")
        {
            // 等待156毫秒，預防輸入的值在更新到變數之前按下Enter鍵
            await Task.Delay(156);

            await OnSearch();
        }
    }
}

  • Line 2

    將 HandleOnKeyDown 繫結到 MTextField 的 OnKeyDown 事件。

  • Line 10-17

    通過判斷 KeyboardEventArgs 的 Code 值是否為 Enter 來觸發搜尋。第14行等待156毫秒是為了等待 summary 的值已經是輸入過後的值。

選擇後觸發查詢

<MSelect @bind-Value="warningSigns"
    	 Items="@(Enum<WarningSigns>.GetEnumObjectList<WarningSigns>())"
    	 ItemText="item => item.Name"
    	 ItemValue="item => item.Value"
    	 TValue="WarningSigns?"
    	 TItem="EnumObject<WarningSigns>"
    	 TItemValue="WarningSigns"
    	 Label="高溫警告"
    	 OnSelectedItemUpdate="OnSearch"
    	 Clearable
         Dense
         HideDetails="@("auto")"
    	 Outlined>
</MSelect>

  • Line 9

    當選擇項更新時(OnSelectedItemUpdate)直接呼叫 OnSearch 方法，觸發查詢。此處不用像上面處理 OnKeyDown 那樣等待156毫秒，因為 OnSelectedItemUpdate 是在 warningSigns 更新後觸發的。

點選清空圖示觸發查詢

很簡單，只要給 MTextField 和 MSelect 元件新增以下屬性：

Clearable
OnClearClick="OnSearch"

enter-query.gif

加點Loading動畫可好？

好！

<MButton Color="primary" 
    	 Loading="searching" 
    	 OnClick="HandleOnSearch">
    搜尋
</MButton>
...

<MDataTable Headers="_headers" Items="forecasts" 
            Loading="loading" 
            ItemsPerPage="5" Class="elevation-1">
...
    
@code {
    private bool loading;
    private bool searching;
    
    private async Task HandleOnSearch()
    {
        searching = true;

        await OnSearch();

        searching = false;
    }
    
    private async Task OnSearch()
    {
        loading = true;
        
        await Task.Delay(1000);
        forecasts = await ForecastService.GetForecastAsync(summary, warningSigns);

        loading = false;
    }
}

  • Line 2-3,15,17-24

    新增 searching 變數用於控制搜尋按鈕的 Loading 狀態，同時新增了 HandleOnSearch 代替原來的 OnSearch 是為了單獨控制點選搜尋按鈕的動畫。

  • Line 9,14,28,33

    新增 loading 變數用於控制 MDataTable 的 Loading 狀態。OnSearch 方法塊中在介面請求前後設定 loading 的值。

loading.gif

表的行操作和自定義列樣式

因為篇幅限制，我就不一一把程式碼貼出來了，具體程式碼請查閱 原始碼 接下來我將針對Table寫一些常見的程式碼，如行操作和自定義列樣式。

table.gif

封裝元件和技巧

我本應該用這節分享的內容將上面的例子重構的過程寫出來，但感覺會使得本文太冗長。重構後的程式碼我也會上傳到 Github 上。

封裝元件

試想一下，當你被分配到好幾個模組，每個模組都有至少一個查詢表格頁，你會如何開發？你大概會說複製最合適的程式碼檔案，然後重新命名檔名，重新命名相應的變數，修修改改就完行了。當然這是一個方法，但不優雅。那優雅的方式是什麼，是封裝。我有段時間在全職開發 MASA.Blazor 元件庫，後面因為業務需求分配到了IoT專案幫助Blazor後臺系統的研發和 MASA.Blazor 的實踐。在開發IoT專案時，經常會看見相同的程式碼分佈在相同的類中，我試著優化重構這些程式碼，並從查詢表格頁中抽離封裝了以下幾個元件：

  • Filters：接收OnSearch引數代理查詢，通過context提供onEnter和onSearch方法供單個查詢元件使用。
  • PageHeader：一個標準的頁頭，包括了標題、副標題、搜尋按鈕，並提供Filters元件的能力。
  • Actions：提供一組操作按鈕，預設展示前兩個，後面的按鈕會移動到MMenu中顯示。
  • BlockText：將相同型別的兩個資料並列顯示。
  • ColorChip：提供有限的顏色列表生成帶淺色字型的MChip。
  • CopyableText：在文字後提供可以複製內容的圖示按鈕。
  • DateTimePicker：提高帶時分秒選擇器的彈出層時間選擇器。
  • EllipsisText：根據父級盒子的寬度自動截斷文字。
  • GenericColumnRender：渲染DateTime、列舉、bool和其他型別值。可以用於MDataTable的ItemColContent和Definitions的DetailContent。

PageHeader元件作為 MASA.Blazor 預置元件的一部分已經發布，其他提及的元件還沒有併入 MASA.Blazor 主庫。如果你想要使用或參考，可以訪問 MASA.Blazor.Experimental.Components。關於預置元件和實驗性元件的詳細介紹和使用的文章，後面會由其他同事編寫和釋出，請大家帶多多關注！

MASA.Blazor.Experimental.Components 是一個實驗性元件庫，這意味著該庫的API和功能可能會被重新設計。不過隨著實驗性元件的功能不斷完善和穩定，會隨著 MASA.Blazor 版本的更新而併入主庫。

技巧

善用基類

Blazor的元件其實也是一個類，它預設繼承自 ComponentBase 並提供了許多虛擬方法，我們可以重寫它們來影響應用程式的行為。而這些方法通過繼承機制給所有Blazor元件使用。

在實際開發中，我會發現幾乎每個頁面都會注入 NavigationManager、IJsRunTime 和其他可能存在的業務服務，或者會使用某些共同使用的元件，那我們可以在繼承 ComponentBase 的基礎上再寫一個已經使用了這些服務和元件的基類。

按架構可以建立專門給 @page 元件用的 PageComponentBase 和單純封裝功能的 PureComponentBase。
按業務分類就得看情況了，因為業務更加具體，基類裡通常會有注入 HttpClient 或者同型別業務服務，以及任何共同使用的程式碼。

SetParametersAsync

SetParametersAsync sets parameters supplied by the component's parent in the render tree or from route parameters.

只需知道每當父級呈現時，都會執行此方法。這意味著它是指定預設引數值的正確位置。
拿前面的例子來說，在使用 MTextField 和 MSelect 時都會設定以下程式碼來維持相同的外觀和行為：

Clearable
Dense
HideDetails="@("auto")"
Outlined

那麼與其每次都要寫一遍，不如利用 SetParametersAsync 的特性把這些預設引數提前設定：

public class DefaultTextField<TValue> : MTextField<TValue>
{
    public override async Task SetParametersAsync(ParameterView parameters)
    {
        Clearable = true;
        Dense = true;
        HideDetails = "auto";
        Outlined = true;

        await base.SetParametersAsync(parameters);
    }
}

public class DefaultSelect<TItem, TItemValue, TValue> : MSelect<TItem, TItemValue, TValue>
{
    public override async Task SetParametersAsync(ParameterView parameters)
    {
        Clearable = true;
        Dense = true;
        HideDetails = "auto";
        Outlined = true;
        
        await base.SetParametersAsync(parameters);
    }
}

<DefaultTextField @bind-Value="@summary"
                  OnKeyDown="@context.onEnter"
                  OnClearClick="@context.onSearch"
                  Label="Summary">
</DefaultTextField>

<DefaultSelect @bind-Value="warningSigns"
               Items="@(Enum<WarningSigns>.GetEnumObjectList<WarningSigns>())"
               ItemText="item => item.Name"
               ItemValue="item => item.Value"
               TValue="WarningSigns?"
               TItem="EnumObject<WarningSigns>"
               TItemValue="WarningSigns"
               Label="高溫警告"
               OnSelectedItemUpdate="@context.onSearch"
               OnClearClick="@context.onSearch">
</DefaultSelect>

after.gif

未來的計劃

未來我們團隊將繼續優化各個元件的效能，完成缺失的元件，解決BUG問題，完善文件等。另外，我們也計劃出Blazor相關的教程和分享文章，敬請期待。

感謝閱讀！

資源

開源地址

MASA.BuildingBlocks：https://github.com/masastack/MASA.BuildingBlocks

MASA.Contrib：https://github.com/masastack/MASA.Contrib

MASA.Utils：https://github.com/masastack/MASA.Utils

MASA.EShop：https://github.com/masalabs/MASA.EShop

MASA.Blazor：https://github.com/BlazorComponent/MASA.Blazor

如果你對我們的 MASA Framework 感興趣，無論是程式碼貢獻、使用、提 Issue，歡迎聯絡我們

16373211753064.png

相關文章