ABP設置管理模組: Abp.SettingUi

開源地址: //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設置的值
  • 支援本地化
  • 設置分組
  • 為不同設置顯示適當的控制項
  • 可通過許可權控制設置的顯示

在線演示

我們為這個模組創建了一個在線演示: //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")
);
      • 常量 Group1 和 Group2 定義在 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中許可權系統, 請查看該文檔

Tags:

VirMach 便宜 VPS

QNews

QNews