開源地址: 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
手動安裝包
-
安裝以下 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
-
新增
DependsOn(typeof(AbpSettingUiXxxModule))
屬性來配置模組依賴. (幫助)
配置本地化資源
為了讓SettingUi模組使用應用程式的本地化資源, 我們需要將它們新增進SettingUiResource
:
-
MyAbpApp.Domain.Shared
專案 -MyAbpAppDomainSharedModule
類Configure<AbpLocalizationOptions>(options => { ... options.Resources .Get<SettingUiResource>() .AddVirtualJson("/Localization/MyAbpApp"); });
使用
-
授權 ("Setting UI" - "Show Setting Page")
-
重新整理瀏覽器, 然後你就可以使用 "Administration" - "Settings" 選單來看見所有ABP內建的設定了
管理自定義設定
除了ABP自定義設定以外, 你也可以使用這個模組來管理你自己的設定.
-
定義一個設定
-
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的設定系統, 請參見 設定文件
-
-
定義本地化資源, 出於演示目的, 我們定義了英語和簡體中文的本地化資源
-
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地址." } }
-
-
-
重新啟動應用程式, 我們可以看到設定顯示了, 並且本地化也正常工作
分組
你可能注意到我們的自定義設定顯示在"其它"標籤, "其它"卡片中, 這些是預設的分組, 分別稱之為"Group1"和"Group2"
那麼我們如何自定義這些設定的分組呢? 有兩種方式:
-
使用
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": "連線" } }
-
重新啟動應用程式檢視分組名稱是否正確設定
-
-
使用設定屬性檔案
另一種分組方式是使用設定分組檔案, 該方式由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中許可權系統, 請檢視該文件