NextUI 框架架构文档

本文档是 NextUI 框架的核心架构参考，面向开发者和 AI 助手。 最后更新：2026-02-15

一、定位与愿景

NextUI 不仅是一个 UI 组件库，而是一套完整的企业级应用工程体系。它通过 Token 驱动、组件化 和 跨端一致性，帮助开发者快速构建高质量的 Blazor (Web)、.NET MAUI (Hybrid) 应用。

核心能力：

• 200+ Blazor 组件（对齐 Microsoft Fluent UI 规范）
• 跨平台：Web / iOS / Android / macOS / Windows
• Design Token 驱动的主题系统（暗色/亮色/自定义）
• 内置身份认证集成（OpenID Connect）
• 项目脚手架模板（一键创建标准项目）
• Nx CLI 统一工程工具链

二、全局架构总览

┌─────────────────────────────────────────────────────────────────────────┐
│                          应用层 (Application)                          │
│                                                                         │
│   nextui-web-admin        nextui-public-site        nextui-maui-app    │
│   (后台管理模板)           (公共门户模板)             (MAUI 混合模板)    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│                         NextUI.App  [应用级组件]                        │
│                    SxSettingsView / SxDiagnosticView                    │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│                       NextUI.Blazor  [UI 组件库]                        │
│          140+ Sx* 组件 / DataGrid / Charts / Admin / Identity          │
│                                                                         │
├──────────────────────────────┬──────────────────────────────────────────┤
│                              │                                          │
│   NextUI.Identity            │           NextUI.Identity.EF             │
│   [身份认证集成层]            │           [EF Core 持久化]               │
│   OIDC / Mock Auth /         │           (可选，仅 Web)                 │
│   多租户 / Admin API         │                                          │
│                              │                                          │
├──────────────────────────────┴──────────────────────────────────────────┤
│                                                                         │
│                        NextUI.Core  [核心引擎]                          │
│         SxComponentBase / ThemeState / i18n / 平台抽象                  │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│          NextUI.Tokens  [设计变量]      NextUI.Assets  [品牌资产]       │
│          Color / Spacing / Typography    Fonts / Icons / SVGs           │
│          Shadows / BorderRadius                                         │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                          工具层 (Tooling)                               │
│                                                                         │
│   NextUI.Cli (nx)          NextUI.Templates          NextUI.Workbench  │
│   [统一工程 CLI]            [项目脚手架模板]           [组件实验室]       │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

三、NuGet 包清单与职责

3.1 依赖关系图

NextUI.Tokens ─────→ NextUI.Core ─────→ NextUI.Identity ──→ NextUI.Identity.EF
      │                   │                    │
      │                   │                    │
NextUI.Assets             └──────→ NextUI.Blazor ←────────┘
                                       │
                                       ↓
                                  NextUI.App
                                       │
                                       ↓
                                NextUI.Workbench

3.2 各包详细说明

四、各包详解

4.1 NextUI.Tokens — 设计变量

src/NextUI.Tokens/
├── Exports/
│   ├── tokens.json          # Token 定义（JSON 格式）
│   ├── blazor.css           # CSS 变量导出
│   └── theme-runtime.js     # 主题切换运行时
└── NextUI.Tokens.csproj

核心内容：

• 颜色系统：Neutral 系列（背景/前景/描边） + Brand 主题色（10 级色阶）
• 间距系统：--sx-spacingVertical* / --sx-spacingHorizontal*（从 XXS 到 XXXL）
• 圆角系统：--sx-borderRadius*（None → Circular）
• 字体系统：--sx-fontSize* / --sx-fontWeight* / --sx-lineHeight*
• 阴影系统：--sx-shadow*（2/4/8/16/28/64）
• 密度缩放：通过 --sx-densityScale 控制整体紧凑度

外部依赖：无

4.2 NextUI.Assets — 品牌资产

src/NextUI.Assets/
├── Fonts/                   # 嵌入式字体文件
├── Icons/                   # 图标资源
└── NextUI.Assets.csproj

包含两个程序集：NextUI.Assets（当前）+ NextUI.LegacyAssets（旧版字体/图标兼容）。

外部依赖：无

4.3 NextUI.Core — 核心引擎

src/NextUI.Core/
├── Base/
│   └── SxComponentBase.cs       # 所有 UI 组件的基类
├── Theme/
│   └── ThemeState.cs            # 主题状态管理（暗色/亮色/品牌色/密度）
├── Localization/                # i18n 翻译引擎
├── Services/
│   ├── IUserPreferences.cs      # 用户偏好抽象（浏览器/原生实现）
│   └── IUserState.cs            # 用户状态
├── Platform/                    # 平台抽象层
└── NextUI.Core.csproj

关键设计：

• SxComponentBase：所有 Sx* 组件必须继承，提供统一的生命周期、参数绑定和可访问性支持
• ThemeState：管理主题切换、调色板生成、字体缩放、密度缩放
• IUserPreferences：平台抽象接口，Web 用 localStorage，MAUI 用 Preferences.Default

依赖：NextUI.Tokens

4.4 NextUI.Identity — 身份认证与用户系统

src/NextUI.Identity/
├── Services/
│   ├── IIdentityService.cs        # 用户身份服务
│   ├── IUserProfileService.cs     # 用户资料服务
│   ├── ILocalUserService.cs       # 本地用户管理 (TODO)
│   ├── OpenIdConnectHandler.cs    # OIDC 处理器
│   ├── MockAuthService.cs         # 开发用 Mock 认证
│   ├── SharedProfileService.cs    # 跨应用 Profile 同步
│   └── UserPreferencesSync.cs     # 偏好双向同步
├── Preferences/
│   ├── IUserPreferencesService.cs # 层级偏好服务
│   ├── PreferencesResolver.cs     # 路径解析与合并
│   ├── UserPreferences.cs         # 偏好数据模型
│   └── MockUserPreferencesService.cs
├── Admin/
│   └── KeycloakAdminClient.cs     # Keycloak 管理 API 客户端
├── MultiTenancy/                  # 多租户支持
└── NextUI.Identity.csproj

关键特性：

• 4 种身份模式：Mock / OIDC / Local (TODO) / Hybrid (TODO)
• OpenID Connect 客户端流程（对接 Keycloak / Auth0 / Azure AD）
• Mock 认证服务（开发环境免登录）
• 本地用户系统 (TODO)：纯离线多用户，密码可选，访客支持
• 三层偏好架构：App 全局 → Group → User，层级继承
• 偏好同步：双向同步到 Profile 服务器，支持冲突解决
• 跨应用 Profile 同步：SharedProfile API（头像、主题、语言、时区）
• 多租户支持
• Keycloak Admin API 客户端（仅 Web 平台）

身份模式架构：

IdentityMode:
├─ Mock    → MockIdentityService (内存模拟，开发用)
├─ OIDC    → OidcIdentityService (Keycloak/Auth0/AzureAD)
├─ Local   → LocalIdentityService (TODO, 纯本地多用户)
└─ Hybrid  → HybridIdentityService (TODO, Local + OIDC 混合)

三层偏好架构：

解析优先级: User > Group > App > 系统默认

App 全局 (userId="__app__", scopePath="/")
    └─ Group (userId="__app__", scopePath="/group")
        └─ User (userId="actual-uid", scopePath="/group/app")

依赖：NextUI.Core, Microsoft.AspNetCore.Components.Authorization (Web only)

平台限制：Keycloak Admin 客户端在 iOS/Android/macOS 构建中被排除

详细设计：见 docs/plans/2026-02-15-preferences-and-user-system-design.md

4.5 NextUI.Identity.EF — 身份数据持久化

src/NextUI.Identity.EF/
├── DbContext/                   # EF Core 数据上下文
├── Repositories/                # 数据仓储实现
└── NextUI.Identity.EF.csproj

依赖：NextUI.Identity, Microsoft.EntityFrameworkCore

平台限制：仅 net10.0（Web 服务端），不支持移动端

4.6 NextUI.Blazor — UI 组件库

src/NextUI.Blazor/
├── Components/                  # 140+ 组件（详见第五节）
│   ├── Admin/                   # 管理后台组件
│   ├── Identity/                # 身份认证相关 UI
│   ├── App/                     # 应用级组件
│   ├── DataGrid/                # 数据表格系统
│   ├── Charts/                  # 图表系统（ECharts）
│   └── ...                      # 基础组件
├── wwwroot/
│   ├── js/                      # JavaScript 互操作文件
│   └── Styles/                  # CSS 样式文件
├── Resources/                   # 多语言资源文件
├── Docs/                        # 嵌入式组件文档
└── NextUI.Blazor.csproj

关键特性：

• 140+ 根级 Sx* 组件 + 60+ 子组件
• iOS/Mac Catalyst 特殊资源打包处理（MauiAsset 模式）
• ASP.NET Core 集成（服务端渲染，仅 Web）
• Markdown 渲染（基于 Markdig）
• Web Components 支持（CustomElements）
• 内嵌多语言资源

依赖：NextUI.Core, NextUI.Identity, Markdig

平台限制：

• Admin 组件：仅 Web 平台
• ASP.NET Core 功能：browser-wasm 排除

4.7 NextUI.App — 应用级组件

src/NextUI.App/
├── Components/
│   ├── SxSettingsView.razor     # 设置中心
│   ├── SxDiagnosticView.razor   # 系统诊断
│   └── ...
├── Resources/                   # 多语言资源
└── NextUI.App.csproj

定位：提供开箱即用的「应用级」页面和视图组件，不是基础 UI 组件。

依赖：NextUI.Blazor

平台限制：仅 net10.0 (browser)

4.8 NextUI.Cli (nx) — 统一工程 CLI

src/NextUI.Cli/
├── Commands/
│   ├── BuildCommand.cs          # nx build
│   ├── PackCommand.cs           # nx pack
│   ├── PushCommand.cs           # nx push
│   ├── RunCommand.cs            # nx run
│   ├── TestCommand.cs           # nx test
│   ├── DocCommand.cs            # nx doc
│   ├── CheckCommand.cs          # nx check
│   ├── LintCommand.cs           # nx lint
│   ├── AiCommand.cs             # nx ai
│   └── UpgradeCommand.cs        # nx upgrade
├── Docs/                        # 内嵌框架文档（离线可用）
└── Nx.csproj

核心命令：

依赖：Spectre.Console, System.CommandLine, Markdig

4.9 NextUI.Templates — 项目模板

templates/
├── NextUI.Templates.WebAdmin/        # 后台管理模板
│   ├── Server/                        #   ASP.NET Core 主机
│   └── Client/                        #   Blazor WASM 客户端
├── NextUI.Templates.PublicSite/       # 公共门户模板
│   └── (Blazor WASM Standalone)
└── NextUI.Templates.Maui/            # MAUI 混合模板
    ├── MauiApp/                       #   MAUI 原生壳
    ├── Shared/                        #   共享 Blazor 组件
    └── WebHost/                       #   Web 调试主机

模板创建：

# 使用 dotnet new
dotnet new nextui-web-admin -n MyAdminApp
dotnet new nextui-public-site -n MyPortal
dotnet new nextui-maui-app -n MyMauiApp

# 使用 nx CLI（更快）
./nx new web-admin -n MyAdminApp
./nx new public-site -n MyPortal
./nx new maui-app -n MyMauiApp

MAUI 模板亮点：Dual-Host 架构 — 同一套 Blazor UI 既能跑在 MAUI 原生壳里，也能通过 WebHost 在浏览器中快速调试。

五、组件清单

5.1 组件分类总览

5.2 DataGrid 子系统

Components/DataGrid/
├── SxDataGrid.razor                 # 主表格组件
├── SxPaginator.razor                # 分页器
├── Columns/                         # 列类型
│   ├── SxTextColumn                 #   文本列
│   ├── SxNumberColumn               #   数字列
│   ├── SxBooleanColumn              #   布尔列
│   ├── SxDateColumn                 #   日期列
│   ├── SxActionsColumn              #   操作列
│   ├── SxSelectColumn               #   选择列
│   └── SxCustomColumn               #   自定义列
└── Infrastructure/                  # 基础设施
    ├── Sorting                      #   排序
    └── Filtering                    #   筛选

5.3 Identity 设置向导

Components/Identity/Setup/
├── SxSetupWizard.razor              # 向导主容器
├── SxSetupWelcome.razor             # 欢迎步骤
├── SxSetupServerConfig.razor        # 服务器配置
├── SxSetupAdminAccount.razor        # 管理员账户
├── SxSetupRealmConfig.razor         # Realm 配置
├── SxSetupVerification.razor        # 验证步骤
├── SxSetupComplete.razor            # 完成步骤
└── SxSetupProgress.razor            # 进度指示器

六、平台支持矩阵

✅* = 支持但排除部分功能（如 Keycloak Admin 客户端） — = 不适用 / 不支持

MAUI 特殊处理：

• iOS/Mac Catalyst 构建中，wwwroot/ 静态资源自动配置为 MauiAsset，确保正确打包
• MAUI 环境需注册原生 IUserPreferences 实现替代浏览器 localStorage

七、构建与版本管理

7.1 构建编排 (nx.json)

项目构建顺序（按依赖拓扑排序）：

NextUI.Tokens → NextUI.Core → NextUI.Identity → NextUI.Blazor → NextUI.App
                                    ↓
                            NextUI.Identity.EF

并行构建：NextUI.Assets, NextUI.Cli, NextUI.Templates

7.2 版本策略

• 使用 Nerdbank.GitVersioning 统一版本管理
• 版本格式：{major}.{minor}.{patch}
• 构建时间戳：yyMMddHHmmss（用于内部标识）
• 模板依赖使用通配符：NextUI.Blazor Version="1.4.*"

7.3 发布流程

# 完整流程：编译 → 测试 → 打包 → 推送本地仓库 → 清理缓存
./nx publish

# 分步操作
./nx build          # 编译
./nx test           # 测试
./nx pack           # 打包
./nx push           # 推送

八、测试体系

8.1 测试项目

8.2 测试规范

• bUnit 事件触发：Immediate="true" 用 .Input()，Immediate="false" 用 .Change()
• 状态不变性测试：操作 A 不应影响状态 B（每个表单组件必须包含）
• 测试分类：Initial State / Parameter / Validation / Interaction / Callback / State Invariant

九、开发铁律

9.1 组件开发

9.2 Git 提交规范

• 格式：<type>: <中文说明>
• 类型：feat / fix / refactor / docs / test / chore
• 原则：一个功能/修复一个提交，禁止混杂无关改动
• 必须：提交前获得用户明确同意

十、已知缺失与改进方向

10.1 待补全的基础组件

以下是对齐 Fluent UI 规范但尚未实现的组件：

10.2 组件能力缺失

10.3 用户系统与偏好设置缺失

详见 docs/plans/2026-02-15-preferences-and-user-system-design.md

10.4 平台能力缺失

10.5 工程体系缺失

10.6 已知技术债

十一、目录结构速查

nextui/
├── src/                              # 框架核心源码
│   ├── NextUI.Tokens/                #   设计变量
│   ├── NextUI.Assets/                #   品牌资产
│   ├── NextUI.Core/                  #   核心引擎
│   ├── NextUI.Identity/              #   身份认证
│   ├── NextUI.Identity.EF/           #   身份数据持久化
│   ├── NextUI.Blazor/                #   UI 组件库
│   ├── NextUI.App/                   #   应用级组件
│   ├── NextUI.Cli/                   #   nx CLI 工具
│   └── NextUI.Templates/            #   项目模板包
├── templates/                        # 模板源码
│   ├── NextUI.Templates.WebAdmin/    #   后台管理
│   ├── NextUI.Templates.PublicSite/  #   公共门户
│   └── NextUI.Templates.Maui/       #   MAUI 混合
├── tests/                            # 测试项目
│   ├── NextUI.Core.Tests/
│   ├── NextUI.Blazor.Tests/
│   ├── NextUI.Identity.Tests/
│   ├── NextUI.App.Tests/
│   ├── NextUI.E2E.Tests/
│   ├── Nx.Tests/
│   └── js/                           #   JavaScript 测试
├── workbench/                        # 组件实验室（开发用）
├── samples/                          # 示例应用（演示用）
├── docs/                             # 文档（详见下表）
├── tools/                            # 开发辅助工具
├── scripts/                          # 构建脚本
├── nx.json                           # 构建编排配置
├── NuGet.Config                      # NuGet 源配置
├── version.json                      # 版本定义
└── README.md                         # 项目入口文档

十二、相关文档索引

© 2026 NextUI Team. All rights reserved.