Components Workbench (组件工作台) UI 设计规范

自动生成时间: 2026-02-03 页面路径: workbench/NextUI.Workbench/Layout/ComponentsLayout.razor 技术栈: Blazor WebAssembly

1. 页面概述

Components Workbench 是 NextUI 的组件开发和演示工作台，提供完整的组件浏览、交互测试和文档查看功能。页面采用 SxAppShell 布局，包含可折叠的侧边导航、组件预览区和详情面板。

主要功能:

  • 组件分类导航与搜索
  • 组件效果预览与代码示例
  • 交互实验室 (Property Inspector)
  • API 文档与源码查看

2. 页面结构

┌────────────────────────────────────────────────────────────────────┐
│                      SxAppShell Header                              │
│  [≡] NextUI 工作台  [⋮]                                            │
├────────────────┬───────────────────────────────────────────────────┤
│                │                                                    │
│  [筛选导航]     │            Component Playground                    │
│                │                                                    │
│  概览          │  ┌──────────────────────────────────────────────┐ │
│    Home        │  │  SxButton (按钮)                              │ │
│    Tokens      │  │  最基础的交互组件...                           │ │
│    ...         │  │                                              │ │
│                │  │  [效果展示] [交互实验室]                       │ │
│  应用程序       │  │                                              │ │
│    SxAppShell  │  │  基础使用场景                                 │ │
│    SxNavBar    │  │  ┌────────────────────────────────────────┐ │ │
│    ...         │  │  │ [效果] [代码]                          │ │ │
│                │  │  │ RAZOR                                  │ │ │
│  身份认证       │  │  │ <SxButton Appearance="Accent">...</SxButton>│ │
│    Login       │  │  └────────────────────────────────────────┘ │ │
│    ...         │  │                                              │ │
│                │  ├──────────────────────────────────────────────┤ │
│  管理平台       │  │  [文档] [API/Schema]                         │ │
│  布局与架构     │  │                                              │ │
│  表单与输入     │  │  ## SxButton (按钮)                          │ │
│  图表          │  │  基础交互组件。遵循 Fluent UI Blazor...       │ │
│                │  │                                              │ │
│  通用组件  [↕]  │  │  ### Parameters (参数)                       │ │
│    Actions     │  │  | 参数名 | 类型 | 默认值 | 描述 |            │ │
│    Data Display│  │  | ...    |      |        |      |            │ │
│    Navigation  │  └──────────────────────────────────────────────┘ │
│    Feedback    │                                                    │
│    Advanced    │                                                    │
│                │                                                    │
├────────────────┼───────────────────────────────────────────────────┤
│  →) 登录       │                                                    │
└────────────────┴───────────────────────────────────────────────────┘

3. 主要组件

3.1 布局文件

文件 用途
Layout/ComponentsLayout.razor 主布局，包含 SxAppShell
Layout/ComponentsSidebar.razor 侧边导航组件
src/NextUI.App/Components/SxComponentPlayground.razor 组件演示区

3.2 核心组件依赖

NextUI 组件 用途
SxAppShell 应用外壳布局
SxAppRoot 应用根容器
SxNavMenu 侧边导航菜单
SxNavMenuGroup 导航分组
SxNavMenuLink 导航链接
SxDrawer 设置抽屉
SxIdentityUserBar 用户信息栏

4. 侧边导航 (ComponentsSidebar)

4.1 导航分类

分类 图标 包含内容
概览 house Home, Design Tokens, SxThemeProvider, SxTheme, SxErrorBoundary
应用程序 window-restore SxAppShell, SxNavBar, SxUserBar, SxAppRoot, SxAppRouter, SxAppGlobalMenu, SxSettings
身份认证 id-card Overview, SxLoginButton, SxUserAvatar, SxIdentityUserBar, SxAuthGuard, SxTenantSwitcher, SharedProfile, Preferences
管理平台 shield Admin 相关组件
布局与架构 layer-group SxArtboard, SxStack, SxGrid, SxCard, SxHeader, SxFooter, SxSection, SxPageBox, SxSpacer, SxSplitter, SxMultiSplitter, SxImage, SxHorizontalScroll, SxOverflow
表单与输入 keyboard SxInput, SxLabel, SxTextArea, SxAutoComplete, SxSearch, SxCheckbox, SxRadioGroup, SxSelect, SxSwitch, SxSlider, SxNumberInput, SxDatePicker, SxTimePicker, SxColorPicker, SxRating, SxSecurityCode, SxCombobox, SxListbox, SxCalendar
图表 chart-line 27 种图表类型 (SxChart, SxLineChart, SxAreaChart, SxBarChart, SxPieChart, ...)
通用组件 cubes 5 个子分类 (Actions, Data Display, Navigation, Feedback, Advanced)

4.2 通用组件子分类

子分类 图标 组件数量
Actions mouse-pointer 6 (SxButton, SxToggleButton, SxSplitButton, SxFab, SxAnchor, SxSortableList)
Data Display chart-simple 18 (SxBadge, SxTag, SxAvatar, SxPersona, SxTable, SxDataGrid, SxTree, ...)
Navigation location-arrow 9 (SxTabs, SxNavMenu, SxMenu, SxMenuButton, SxCommandBar, ...)
Feedback circle-exclamation 12 (SxDialog, SxDrawer, SxToast, SxTooltip, SxMessageBar, ...)
Advanced wand-magic-sparkles 7 (SxMarkdownViewer, SxMarkdownEditor, SxHtmlEditor, SxCodeSnippet, ...)

4.3 导航功能

功能 描述
筛选 输入框过滤组件，支持英文名、中文名、路径匹配
分组/字母排序切换 点击 [↕] 按钮切换分组视图和字母排序视图
展开/折叠 每个分组可独立展开/折叠
状态持久化 展开状态和视图模式保存到 localStorage
草稿标记 (Draft) 标记的组件显示为半透明

4.4 导航项样式

属性 值
Level 1 背景 (展开) var(--sx-colorNeutralBackground1)
Level 1 背景 (折叠) var(--sx-colorNeutralBackground3)
Level 2 背景 var(--sx-colorNeutralBackgroundSubtle)
激活状态背景 var(--sx-colorBrandBackground1)
激活状态文字 #ffffff
Hover 轮廓 1px solid var(--sx-colorNeutralStroke1)
草稿组件透明度 0.4

5. 组件演示区 (SxComponentPlayground)

5.1 布局结构

┌────────────────────────────────────────────────────────────────┐
│  ComponentName (组件名)                                         │
│  组件描述...                                                    │
│  [效果展示] [交互实验室]    [Blazor] [HTML]                      │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  基础使用场景                                                   │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ [效果] [代码]                                      [📋]  │ │
│  │ RAZOR                                                    │ │
│  │ <SxButton Appearance="Accent">Accent</SxButton>         │ │
│  │ <SxButton Appearance="Neutral">Neutral</SxButton>       │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                 │
│  状态与异常场景                                                  │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ ...                                                       │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                 │
├─────────────────────────────────────────────[_][□][▢]──────────┤
│  [文档] [API / Schema]                                          │
│                                                                 │
│  ## SxButton (按钮)                                             │
│  [x] Implemented                                                │
│  基础交互组件。遵循 Microsoft Fluent UI Blazor (Button) v4.13.2 │
│                                                                 │
│  ### Parameters (参数)                                          │
│  | 状态 | 参数名 | 类型 | 默认值 | 描述 |                       │
│  | [x]  | Appearance | ButtonAppearance | Neutral | 视觉风格 |  │
│  | ...  | ...        | ...              | ...     | ...      |  │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

5.2 主要区域

区域 比例 功能
顶部演示区 65% 组件效果预览、代码示例
底部文档区 35% API 文档、Schema、源码

5.3 底部面板控制

按钮 功能
[_] 最小化 (隐藏底部面板)
[□] 恢复默认尺寸
[▢] 最大化 (全屏文档)

6. 状态管理

6.1 持久化状态 (localStorage)

Key 内容
sx-components-nav-state 导航展开状态、视图模式
components-shell SxAppShell 状态 (侧边栏宽度等)

6.2 状态结构

// sx-components-nav-state
{
  "isGrouped": true,
  "expanded": ["Overview", "Application", "Components", ...]
}

7. 公共 API

7.1 ComponentsLayout Parameters

参数 类型 说明
(无自定义参数) - 继承 LayoutComponentBase

7.2 ComponentsSidebar 内部状态

状态 类型 默认值 说明
_isGroupedView bool true 分组视图/字母排序
_expandedIds HashSet<string> 所有分组 已展开的分组 ID
_filterCollapsedIds HashSet<string> 空 筛选时手动折叠的分组

7.3 事件

事件 触发时机
HandleGroupExpandedChanged 分组展开/折叠时
ToggleViewMode 切换分组/字母排序视图
OnLocaleChanged 语言切换时
OnStateChanged 主题/语言变化时

8. 典型使用场景 (Use Cases)

8.1 UC-1: 浏览组件列表

步骤:

  1. 用户访问 /components
  2. 看到左侧分类导航，默认展开所有分组
  3. 点击 "通用组件" 下的 "SxButton"

预期结果: 右侧显示 SxButton 组件的演示和文档

8.2 UC-2: 搜索组件

步骤:

  1. 用户在筛选输入框输入 "button"
  2. 导航自动过滤显示匹配项

预期结果:

  • 只显示包含 "button" 的组件
  • 所有包含匹配项的分组自动展开

8.3 UC-3: 切换视图模式

步骤:

  1. 用户点击 "通用组件" 旁的切换按钮 [↕]

预期结果:

  • 从分组视图切换到字母排序视图
  • 视图模式保存到 localStorage

8.4 UC-4: 查看组件 API

步骤:

  1. 用户打开某个组件页面
  2. 滚动到底部或点击 "API / Schema" 标签

预期结果: 显示组件的参数表、事件表、方法表

8.5 UC-5: 打开设置

步骤:

  1. 用户点击底部用户栏
  2. 选择设置选项

预期结果: 右侧抽屉打开，显示 SxSettingsView

9. 状态不变性测试 (State Invariants)

9.1 导航状态隔离

操作 不应影响
展开/折叠任意分组 其他分组的展开状态
切换视图模式 当前展开的分组
筛选输入 已展开分组列表 (持久化)
路由切换 导航展开状态

9.2 状态持久化验证

  • 刷新页面后，展开状态应恢复
  • 刷新页面后，视图模式应恢复
  • 切换主题不应重置导航状态

10. 测试检查点

10.1 必须测试 (E2E)

  • 页面加载显示导航和内容区
  • 组件导航树正确显示所有分类
  • 点击组件链接正确导航
  • 组件页面显示演示区和文档区
  • 筛选功能正确过滤组件

10.2 功能测试

  • 分组展开/折叠正常
  • 分组/字母排序切换正常
  • 状态持久化正常 (刷新后恢复)
  • 设置抽屉打开/关闭正常
  • 国际化文本正确显示

10.3 响应式测试

  • 侧边栏可折叠
  • 内容区自适应宽度
  • 移动端触摸交互正常

11. 规范合规检查

11.1 组件使用

检查项 结果
使用 NextUI 组件 ✅ 使用 SxAppShell, SxNavMenu, SxDrawer 等
无原生 HTML 元素 ✅ 无直接使用 button, input 等

11.2 样式

检查项 结果
使用 Design Token ✅ 所有颜色使用 --sx-color* 变量
使用间距 Token ✅ 使用 --sx-spacing-* 变量
无硬编码颜色 ⚠️ #ffffff 用于激活状态文字

11.3 例外说明

例外 原因
#ffffff 激活状态需要纯白色确保可读性
opacity: 0.4 草稿组件视觉区分

12. 已知问题 / TODO

优先级 问题 状态
P2 /components 根路由显示 "页面未找到" 需要添加概览页
P3 移动端汉堡菜单未实现 未实现
P3 草稿组件数量较多 持续完善

13. 变更历史

日期 变更内容
2026-02-03 初始版本，随 UI Test 工作流创建