这是基于vue-vben-admin 模板适用于abp vNext的前端管理项目

16 KiB

Raw Blame History

主题与品牌化

**本文档中引用的文件** - [PlatformThemeVueVbenAdminModule.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/PlatformThemeVueVbenAdminModule.cs) - [ThemeSettingAppService.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/ThemeSettingAppService.cs) - [ThemeSettingController.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/ThemeSettingController.cs) - [ThemeSettingDto.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/ThemeSettingDto.cs) - [ProjectConfigDto.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/ProjectConfigDto.cs) - [HeaderSettingDto.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/HeaderSettingDto.cs) - [MenuSettingDto.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/MenuSettingDto.cs) - [TransitionSettingDto.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/TransitionSettingDto.cs) - [BeforeMiniStateDto.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/LINGYUN/Platform/Theme/VueVbenAdmin/BeforeMiniStateDto.cs) - [VueVbenAdminSettingNames.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Settings.VueVbenAdmin/LINGYUN/Platform/Settings/VueVbenAdmin/VueVbenAdminSettingNames.cs) - [VueVbenAdminSettingDefinitionProvider.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Settings.VueVbenAdmin/LINGYUN/Platform/Settings/VueVbenAdmin/VueVbenAdminSettingDefinitionProvider.cs) - [PlatformSettingsVueVbenAdminModule.cs](file://aspnet-core/modules/platform/LINGYUN.Platform.Settings.VueVbenAdmin/LINGYUN/Platform/Settings/VueVbenAdmin/PlatformSettingsVueVbenAdminModule.cs) - [README.md](file://aspnet-core/modules/platform/LINGYUN.Platform.Theme.VueVbenAdmin/README.md)

简介

LINGYUN.Platform.Theme.VueVbenAdmin 模块为 VueVbenAdmin 前端框架提供了一套完整的主题管理解决方案，支持系统外观的全面定制。该模块允许管理员动态配置主题颜色、布局样式、Logo 和品牌信息等视觉元素，从而实现系统的个性化展示。

本模块提供了丰富的配置选项，包括暗黑模式、灰色模式、色弱模式等特殊视觉效果，以及菜单、头部、标签页等界面组件的详细设置。通过与 ABP 框架的深度集成，实现了配置的持久化存储和多租户环境下的独立管理。

Section sources

README.md

主题配置结构

主题配置采用分层的数据结构，将相关设置组织在不同的 DTO 类中，便于管理和维护。

classDiagram
class ThemeSettingDto {
+string DarkMode
+ProjectConfigDto ProjectConfig
+BeforeMiniStateDto BeforeMiniInfo
}
class ProjectConfigDto {
+int PermissionCacheType
+bool ShowSettingButton
+bool ShowDarkModeToggle
+string SettingButtonPosition
+string PermissionMode
+int SessionTimeoutProcessing
+bool GrayMode
+bool ColorWeak
+string ThemeColor
+bool FullContent
+string ContentMode
+bool ShowLogo
+bool ShowFooter
+HeaderSettingDto HeaderSetting
+MenuSettingDto MenuSetting
+MultiTabsSettingDto MultiTabsSetting
+TransitionSettingDto TransitionSetting
+bool OpenKeepAlive
+int LockTime
+bool ShowBreadCrumb
+bool ShowBreadCrumbIcon
+bool UseErrorHandle
+bool UseOpenBackTop
+bool CanEmbedIFramePage
+bool CloseMessageOnSwitch
+bool RemoveAllHttpPending
}
class HeaderSettingDto {
+string BgColor
+bool Fixed
+bool Show
+string Theme
+bool ShowFullScreen
+bool UseLockPage
+bool ShowDoc
+bool ShowNotice
+bool ShowSearch
}
class MenuSettingDto {
+string BgColor
+bool Fixed
+bool Collapsed
+bool CanDrag
+bool Show
+bool Hidden
+bool Split
+int MenuWidth
+string Mode
+string Type
+string Theme
+string TopMenuAlign
+string Trigger
+bool Accordion
+bool CloseMixSidebarOnChange
+bool CollapsedShowTitle
+string MixSideTrigger
+bool MixSideFixed
}
class TransitionSettingDto {
+bool Enable
+string BasicTransition
+bool OpenPageLoading
+bool OpenNProgress
}
class BeforeMiniStateDto {
+bool? MenuCollapsed
+bool? MenuSplit
+string MenuMode
+string MenuType
}
ThemeSettingDto --> ProjectConfigDto : "包含"
ProjectConfigDto --> HeaderSettingDto : "包含"
ProjectConfigDto --> MenuSettingDto : "包含"
ProjectConfigDto --> MultiTabsSettingDto : "包含"
ProjectConfigDto --> TransitionSettingDto : "包含"

Diagram sources

ThemeSettingDto.cs
ProjectConfigDto.cs
HeaderSettingDto.cs
MenuSettingDto.cs
TransitionSettingDto.cs
BeforeMiniStateDto.cs

后端实现机制

主题管理模块的后端实现基于 ABP 框架的设置管理功能，通过定义设置名称常量和设置定义提供程序来管理所有可配置项。

设置名称定义

所有主题相关的设置名称都定义在 VueVbenAdminSettingNames 静态类中，采用分组命名的方式组织：

public static class VueVbenAdminSettingNames
{
    public const string GroupName = PlatformSettingNames.GroupName + ".Theme.VueVbenAdmin";
    
    public const string DarkMode = GroupName + ".DarkMode";
    
    public static class ProjectConfig
    {
        public const string Prefix = GroupName + ".ProjectConfig";
        public const string PermissionCacheType = Prefix + ".PermissionCacheType";
        public const string ShowSettingButton = Prefix + ".ShowSettingButton";
        // ... 其他设置
    }
}

设置定义提供程序

VueVbenAdminSettingDefinitionProvider 类负责注册所有主题相关的设置定义，包括默认值、显示名称和描述信息：

flowchart TD
A[VueVbenAdminSettingDefinitionProvider] --> B[Define 方法]
B --> C[添加主题基础设置]
B --> D[添加项目配置设置]
B --> E[添加头部配置设置]
B --> F[添加菜单配置设置]
B --> G[添加多标签页配置设置]
B --> H[添加过渡动画设置]
B --> I[添加迷你状态配置]
C --> J[DarkMode: 默认值 "light"]
D --> K[PermissionCacheType: 默认值 "1"]
D --> L[ShowSettingButton: 默认值 "true"]
D --> M[ThemeColor: 默认值 "#0960bd"]
E --> N[BgColor: 默认值 "#ffffff"]
E --> O[Theme: 默认值 "light"]
F --> P[Mode: 默认值 "inline"]
F --> Q[Theme: 默认值 "dark"]
G --> R[Cache: 默认值 "true"]
H --> S[Enable: 默认值 "true"]

Diagram sources

VueVbenAdminSettingNames.cs
VueVbenAdminSettingDefinitionProvider.cs

API接口设计

主题管理模块提供了 RESTful API 接口，用于获取和更新主题配置。

控制器实现

ThemeSettingController 是主题配置的 API 控制器，继承自 AbpControllerBase 并实现了 IThemeSettingAppService 接口：

sequenceDiagram
participant Client as 客户端
participant Controller as ThemeSettingController
participant Service as ThemeSettingAppService
participant SettingManager as ISettingManager
Client->>Controller : GET /api/platform/theme/vue-vben-admin
Controller->>Service : 调用 GetAsync()
Service->>SettingManager : 获取所有设置
SettingManager-->>Service : 返回设置集合
Service-->>Controller : 构造 ThemeSettingDto
Controller-->>Client : 返回主题配置
Client->>Controller : PUT /api/platform/theme/vue-vben-admin/change
Controller->>Service : 调用 ChangeAsync(input)
Service->>SettingManager : 逐个保存设置
SettingManager-->>Service : 保存成功
Service-->>Controller : 返回完成任务
Controller-->>Client : 返回成功响应

Diagram sources

ThemeSettingController.cs
ThemeSettingAppService.cs

应用服务实现

ThemeSettingAppService 是主题配置的应用服务，负责具体的业务逻辑处理：

public class ThemeSettingAppService : ApplicationService, IThemeSettingAppService
{
    protected ISettingManager SettingManager { get; }

    public ThemeSettingAppService(ISettingManager settingManager)
    {
        SettingManager = settingManager;
        LocalizationResource = typeof(PlatformResource);
    }

    public async virtual Task<ThemeSettingDto> GetAsync()
    {
        var theme = new ThemeSettingDto();
        var settings = await SettingProvider.GetAllAsync(GetAllSettingNames());

        // 从设置中提取主题配置
        theme.DarkMode = GetSettingValue(settings, VueVbenAdminSettingNames.DarkMode);
        
        // 项目配置
        theme.ProjectConfig.PermissionCacheType = GetSettingValue(settings, VueVbenAdminSettingNames.ProjectConfig.PermissionCacheType, 1);
        theme.ProjectConfig.ShowSettingButton = GetSettingValue(settings, VueVbenAdminSettingNames.ProjectConfig.ShowSettingButton, true);
        // ... 其他配置项
        
        return theme;
    }

    [Authorize]
    public async virtual Task ChangeAsync(ThemeSettingDto input)
    {
        // 保存主题配置到设置管理器
        await SettingManager.SetForCurrentUserAsync(VueVbenAdminSettingNames.DarkMode, input.DarkMode);
        await SettingManager.SetForCurrentUserAsync(VueVbenAdminSettingNames.ProjectConfig.PermissionCacheType, input.ProjectConfig.PermissionCacheType.ToString());
        // ... 保存其他配置项
    }
}

Section sources

ThemeSettingAppService.cs

多租户环境下的主题隔离

主题管理模块完全支持 ABP 框架的多租户特性，确保不同租户的主题配置相互隔离。

租户级别配置

所有主题设置都存储在租户级别的设置表中，通过 ISettingManager 的租户感知功能自动处理租户隔离：

graph TB
A[主题配置请求] --> B{是否多租户环境?}
B --> |是| C[使用当前租户ID作为作用域]
B --> |否| D[使用全局作用域]
C --> E[从租户设置表读取配置]
D --> F[从全局设置表读取配置]
E --> G[返回租户特定配置]
F --> H[返回默认配置]

当调用 SettingManager.SetForCurrentUserAsync 方法时，ABP 框架会自动根据当前用户所属的租户来确定设置的作用域，确保每个租户都有独立的主题配置。

配置继承机制

系统支持配置的继承机制，允许在不同层级上定义默认值：

全局默认值：在 VueVbenAdminSettingDefinitionProvider 中定义的默认值
租户默认值：租户管理员可以设置租户级别的默认配置
用户覆盖值：用户可以根据个人偏好覆盖部分配置

这种分层的配置机制既保证了品牌一致性，又提供了足够的灵活性。

Section sources

ThemeSettingAppService.cs

前端集成方案

主题管理模块与 VueVbenAdmin 前端框架深度集成，通过 API 接口实现主题配置的动态加载。

模块依赖

后端模块需要正确引用以启用主题管理功能：

[DependsOn(
    typeof(PlatformDomainModule),
    typeof(PlatformSettingsVueVbenAdminModule),
    typeof(PlatformApplicationContractModule),
    typeof(AbpAspNetCoreMvcModule))]
public class PlatformThemeVueVbenAdminModule : AbpModule
{
    public override void PreConfigureServices(ServiceConfigurationContext context)
    {
        PreConfigure<IMvcBuilder>(mvcBuilder =>
        {
            mvcBuilder.AddApplicationPartIfNotExists(typeof(PlatformThemeVueVbenAdminModule).Assembly);
        });
    }
}

语言映射配置

为了支持国际化，系统配置了 VueVbenAdmin 前端的语言映射：

options.AddLanguagesMapOrUpdate(
    "vben-admin-ui",
    new NameValue("zh_CN", "zh-Hans"));

这确保了前端界面的语言与后端保持一致。

Section sources

PlatformThemeVueVbenAdminModule.cs
MicroServiceApplicationsSingleModule.Configure.cs

配置持久化策略

主题配置的持久化基于 ABP 框架的设置管理基础设施，确保配置的安全存储和高效访问。

存储结构

所有主题配置都存储在数据库的 AbpSettings 表中，每条记录包含以下关键字段：

Name: 设置名称（如 LINGYUN.Platform.Theme.VueVbenAdmin.ProjectConfig.ThemeColor）
Value: 设置值（如 #0960bd）
TenantId: 租户ID（null 表示全局设置）
UserId: 用户ID（null 表示租户级别设置）

批量获取优化

为了提高性能，ThemeSettingAppService 在获取配置时采用批量获取策略：

protected virtual string[] GetAllSettingNames()
{
    return new string[]
    {
        VueVbenAdminSettingNames.DarkMode,
        VueVbenAdminSettingNames.ProjectConfig.PermissionCacheType,
        VueVbenAdminSettingNames.ProjectConfig.ShowSettingButton,
        // ... 所有相关设置名称
    };
}

// 批量获取所有设置，减少数据库查询次数
var settings = await SettingProvider.GetAllAsync(GetAllSettingNames());

这种方法将多个单独的数据库查询合并为一次批量查询，显著提高了性能。

动态加载流程

前端应用启动时的主题配置加载流程如下：

flowchart LR
A[前端应用启动] --> B[调用API获取主题配置]
B --> C{API请求}
C --> D[后端获取所有设置]
D --> E[构造ThemeSettingDto]
E --> F[返回JSON响应]
F --> G[前端应用接收配置]
G --> H[应用主题配置到UI]
H --> I[渲染页面]

这种设计确保了每次用户登录时都能获取到最新的主题配置，实现了配置的实时生效。

Section sources

ThemeSettingAppService.cs

16 KiB Raw Blame History

主题与品牌化

目录

简介

主题配置结构

后端实现机制

设置名称定义

设置定义提供程序

API接口设计

控制器实现

应用服务实现

多租户环境下的主题隔离

租户级别配置

配置继承机制

前端集成方案

模块依赖

语言映射配置

配置持久化策略

存储结构

批量获取优化

动态加载流程

16 KiB

Raw Blame History