ABP設定管理模組: Abp.SettingUi

WAKU發表於2021-02-08

開源地址: https://github.com/EasyAbp/Abp.SettingUi

一直想宣傳一下SettingUi, 因為 工作比較忙, 所以才拖到今天.

關於ABP就不需要我再多廢口舌了, 已經是一個非常出名的.NET Core的框架, 在國內也已經有很多企業在正式專案中廣泛使用了.

Abp.SettingUi是一個用來管理ABP中設定的模組, 簡單來講它可以讓使用者通過UI來管理ABP中各個設定的值, 比如修改預設語言, 設定密碼複雜度等等, 可以說裝上這個模組你就開啟了ABP的"隱藏功能".

應該說設定管理是一個很重要的功能, 但是ABP的社群版沒有內建, 只在ABP的商業版中才有設定的UI, 但仍需開發者通過程式碼來為各個設定項進行適配才可以.

而SettingUi會自動掃描系統中所有的設定, 並在UI中顯示出來, 無需開發者過多幹預, 開箱即用.

從釋出至今, SettingUi在NUGET上已經有近7000次下載, 可以說是ABP中非常實用一個模組, 甚至也有ABP商業版使用者來使用這個模組, 可見SettingUi得到了很多ABP開發者的認可.

為了更好的讓國內開發者使用, SettingUi 1.3.0版增加了中文文件, 該文件是我花了很多心思寫的一個Step by Step的教程, 所以接下來就是該文件複製過來, 希望能吸引更多的使用者:)


Abp.SettingUi

一個用來管理ABP設定的模組

如果你在使用 ABP v2.1.1 之前的版本, 請檢視Abp.SettingManagement.Mvc.UI

功能

  • 通過UI管理ABP設定的值
  • 支援本地化
  • 設定分組
  • 為不同設定顯示適當的控制元件
  • 可通過許可權控制設定的顯示

線上演示

我們為這個模組建立了一個線上演示: https://settingui.samples.easyabp.io

安裝

使用AbpHelper (推薦)

在你的ABP專案的根資料夾中執行以下命令:

abphelper module add EasyAbp.Abp.SettingUi -acshlw

手動安裝包

  1. 安裝以下 NuGet 包.

    • EasyAbp.Abp.SettingUi.Application
    • EasyAbp.Abp.SettingUi.Application.Contracts
    • EasyAbp.Abp.SettingUi.Domain.Shared
    • EasyAbp.Abp.SettingUi.HttpApi
    • EasyAbp.Abp.SettingUi.HttpApi.Client (只有 分層結構 才需要)
    • EasyAbp.Abp.SettingUi.Web
  2. 新增 DependsOn(typeof(AbpSettingUiXxxModule)) 屬性來配置模組依賴. (幫助)

配置本地化資源

為了讓SettingUi模組使用應用程式的本地化資源, 我們需要將它們新增進SettingUiResource:

  • MyAbpApp.Domain.Shared 專案 - MyAbpAppDomainSharedModule

    Configure<AbpLocalizationOptions>(options =>
    {
        ...
        options.Resources
            .Get<SettingUiResource>()
            .AddVirtualJson("/Localization/MyAbpApp");
    });
    

使用

  1. 授權 ("Setting UI" - "Show Setting Page")

  2. 重新整理瀏覽器, 然後你就可以使用 "Administration" - "Settings" 選單來看見所有ABP內建的設定了

管理自定義設定

除了ABP自定義設定以外, 你也可以使用這個模組來管理你自己的設定.

  1. 定義一個設定

    • MyAbpApp.Domain 專案 - Settings/MyAbpAppSettingDefinitionProvider

      public class MyAbpAppSettingDefinitionProvider : SettingDefinitionProvider
      {
          public override void Define(ISettingDefinitionContext context)
          {
              context.Add(
                  new SettingDefinition(
                      "Connection.Ip", // 設定的名稱
                      "127.0.0.1", // 預設值
                      L("DisplayName:Connection.Ip"), // 顯示名稱
                      L("Description:Connection.Ip") // 描述
                  ));
          }
      
          private static LocalizableString L(string name)
          {
              return LocalizableString.Create<MyAbpAppResource>(name);
          }
      }
      
      • 設定的名稱為"Connection.Ip"
      • 提供了一個預設值: "127.0.0.1"
      • 使用幫助方法 L顯示名稱描述 賦予了可本地化的字串. 格式 "DisplayName:{SettingName}" 是ABP推薦的形式.

      ABP的設定系統, 請參見 設定文件

  2. 定義本地化資源, 出於演示目的, 我們定義了英語和簡體中文的本地化資源

    • MyAbpApp.Domain.Shared 專案

      • Localization/MyAbpApp/en.json

        {
            "culture": "en",
            "texts": {
                ...
                "DisplayName:Connection.Ip": "IP",
                "Description:Connection.Ip": "The IP address of the server."
            }
        }
        
      • Localization/MyAbpApp/zh-Hans.json

        {
            "culture": "zh-Hans",
            "texts": {
                ...
                "DisplayName:Connection.Ip": "IP",
                "Description:Connection.Ip": "伺服器的IP地址."
            }
        }
        
  3. 重新啟動應用程式, 我們可以看到設定顯示了, 並且本地化也正常工作

分組

你可能注意到我們的自定義設定顯示在"其它"標籤, "其它"卡片中, 這些是預設的分組, 分別稱之為"Group1"和"Group2"

那麼我們如何自定義這些設定的分組呢? 有兩種方式:

  1. 使用 WithProperty 方法

    WithProperty 方法是由ABPSettingDefinition類提供的一個方法, 我們可以直接在設定定義中使用它:

    • MyAbpApp.Domain 專案 - Settings/MyAbpAppSettingDefinitionProvider

      context.Add(
          new SettingDefinition(
                  "Connection.Ip", // 設定名稱
                  "127.0.0.1", // 預設值
                  L("DisplayName:Connection.Ip"), // 顯示名稱
                  L("Description:Connection.Ip") // 描述
              )
              .WithProperty(SettingUiConst.Group1, "Server")
              .WithProperty(SettingUiConst.Group2, "Connection")
      );
      
      • 常量 Group1Group2 定義在 SettingUiConst類中
      • 設定 "Group1" 為 "Server", "Group2" 為 "Connection"

    然後我們應該為這兩個分組名字提供本地化資源:

    • MyAbpApp.Domain.Shared 專案

      • Localization/MyAbpApp/en.json

        {
            "culture": "en",
            "texts": {
                ...
                "Server": "Server",
                "Connection": "Connection"
            }
        }
        
      • Localization/MyAbpApp/zh-Hans.json

        {
            "culture": "zh-Hans",
            "texts": {
                ...
                "Server": "伺服器",
                "Connection": "連線"
            }
        }
        

    重新啟動應用程式檢視分組名稱是否正確設定

  2. 使用設定屬性檔案

    另一種分組方式是使用設定分組檔案, 該方式由SettingUi模組提供. 當你不太容易修改設定的定義, 或者你想將分組資訊彙集在一個單獨的位置時, 這種方式很有用.

    為了演示這種方式, 讓我們定義一個新設定:

    • MyAbpApp.Domain 專案 - Settings/MyAbpAppSettingDefinitionProvider

      new SettingDefinition(
          "Connection.Port",
          8080.ToString(),
          L("DisplayName:Connection.Port"),
          L("Description:Connection.Port")
      )
      

    為這個設定新增本地化的步驟省略了.

    然後我們需要建立一個新的任意名字的JSON檔案, 但是路徑必須為"/SettingProperties", 這是因為SettingUi模組將會從這個路徑下查詢設定屬性檔案.

    • MyAbpApp.Domain.Shared 專案 - /SettingProperties/MySettingProperties.json 檔案

      {
          "Connection.Port": {
              "Group1": "Server",
              "Group2": "Connection"
          }
      }
      
      • 設定名稱 Connection.Port 做為JSON物件的鍵
      • 使用 "Group1" 和 "Group2" 來設定分組名稱
    • 重新啟動應用程式來檢視新分組的設定

設定型別

預設情況下, 一個設定的值是字串型別, 將會在UI中渲染為一個文字輸入控制元件. 我們可以簡單地提供一個設定屬性"Type"來定製它:

  • MyAbpApp.Domain.Shared 專案 - /SettingProperties/MySettingProperties.json 檔案

    {
        "Connection.Port": {
            "Group1": "Server",
            "Group2": "Connection",
            "Type": "number"
        }
    }
    
    • "Connection.Port" 設定型別為 "number"

不用重新啟動應用程式, 只需要按下F5來重新整理瀏覽器, 你可以立即看到效果:

現在輸入的型別變更為了"數字", 並且前端的驗證也生效了.

設定型別也可以通過 WithProperty 方法來配置, 如 WithProperty("Type", "number")

目前SettingUi支援以下幾種設定型別:

  • text (預設)
  • number
  • checkbox
  • select
    • 需要一個額外屬性 "Options" 來提供選項, 是一個使用豎線(|)分隔的字串

      "Connection.Protocol": {
          "Group1": "Server",
          "Group2": "Connection",
          "Type": "select",
          "Options": "|HTTP|TCP|RDP|FTP|SFTP"
      }
      
      

      渲染結果:

到這裡教程就結束了. 通過本教程, 你應該可以輕鬆地使用SettingUi來管理你的設定了. 教程的原始碼可以在sample資料夾中找到.

本地化

SettingUi模組使用ABP的本地化系統來顯示設定的本地化資訊. 現在支援的語言有:

  • 英語
  • 簡體中文
  • 土耳其語

本地化資源存放在EasyAbp.Abp.SettingUi.Domain.Shared專案的/Localization/SettingUi中.

你可以新增更多的資原始檔來讓這個模組支援更多語言. 歡迎PR ? .

ABP的本地化系統, 請檢視文件

許可權

SettingUi通過檢查SettingUi.ShowSettingPage許可權,來控制是否顯示SettingUi的頁面.

只要賦予了該許可權, 那麼系統中所有的設定都可以通過SettingUi來修改.

但有些時候, 我們不想讓使用者在SettingUi中看到某些設定, 這可以通過定義特定的許可權來實現這個目的.

比如我們需要對使用者隱藏"系統"分組, 那麼需要在SettingUi.ShowSettingPage下新增一個子許可權, 許可權的名字為SettingUi.System. 程式碼如下:

public override void Define(IPermissionDefinitionContext context)
{
    var settingUiPage = context.GetPermissionOrNull(SettingUiPermissions.ShowSettingPage);  // 取得ShowSettingPage許可權
    var systemGroup = settingUiPage.AddChild("SettingUi.System", L("Permission:SettingUi.System")); // 新增控制 Group1: System 的許可權
}

這樣當SettingUi遍歷設定時, 如果發現有SettingUi.Group1形式的許可權, 則只有顯式的賦予該許可權後, 分組Group1才會顯示.

我們可以繼續新增對Group2控制的許可權, 如"系統" -> "密碼"分組, 需要繼續新增字尾為Group2的許可權, 程式碼如下:

public override void Define(IPermissionDefinitionContext context)
{
    ...
    var passwordGroup = systemGroup.AddChild("SettingUi.System.Password", L("Permission:SettingUi.System.Password"));   // 新增控制 Group2: Password 的許可權
}

這樣當SettingUi遍歷設定時, 如果發現有SettingUi.Group1.Group2形式的許可權, 則只有顯示的賦予該許可權後, 分組Group1中的Group2才會顯示.

當然, 我們也可繼續新增精確控制某一設定的許可權, 如"系統" -> "密碼" -> "要求長度", 需要繼續新增字尾為設定名稱的許可權, 程式碼如下:

public override void Define(IPermissionDefinitionContext context)
{
    ...
    var requiredLength = passwordGroup.AddChild("SettingUi.System.Password.Abp.Identity.Password.RequiredLength", L("Permission:SettingUi.System.Password.RequiredLength"));    // 新增控制設定Abp.Identity.Password.RequiredLength的許可權
}

這樣當SettingUi遍歷設定時, 如果發現有SettingUi.Group1.Group2.SettingName形式的許可權, 則只有顯示的賦予該許可權後, 分組Group1中的Group2中的SettingName才會顯示.

通過以上3級的許可權定義方式, 我們就可以在SettingUi中任意控制設定的顯示了.

下圖是Setting Ui許可權的截圖, 和顯示的結果:

關於ABP中許可權系統, 請檢視該文件

相關文章