SxCommandBar UI 设计规范

自动生成时间: 2026-02-04 组件路径: src/NextUI.Blazor/Components/SxCommandBar.razor 关联组件: SxCommandItem、SxMenuButton、SxMenuItem 关联脚本: src/NextUI.Blazor/wwwroot/js/sx-commandbar.js

1. 组件概述

SxCommandBar 是“命令工具条”容器组件，负责命令项布局与溢出处理。它通过 CascadingValue 注入自身上下文到 SxCommandItem，并在 Overflow 布局模式下使用 JS 进行测量与渐进折叠（先隐藏标签，再移入溢出菜单）。

主要能力：

  • 横向/纵向布局
  • 溢出策略（隐藏标签/移入菜单/两者结合）
  • Wrap 模式（CSS Grid 自动换行，无 JS）
  • 统一外观、尺寸、标签显示策略
  • 溢出状态变更回调

2. 组件模式

模式 条件 说明
Overflow 模式 LayoutMode = Overflow 默认模式。使用 JS (sx-commandbar.js) 测量与溢出管理，可能显示 overflow 菜单
Wrap 模式 LayoutMode = Wrap 纯 CSS Grid 自动换行，禁用溢出菜单与 JS 测量
Overflow 菜单显示 _hasOverflow && LayoutMode == Overflow 渲染 SxMenuButton 作为“更多”按钮
MoreLabel 显示 !string.IsNullOrEmpty(MoreLabel) 在溢出按钮中显示文字标签

3. 表单字段

无（命令栏本身不包含输入字段）。

4. 操作按钮

  • 溢出按钮（SxMenuButton，仅在 Overflow 且发生溢出时出现）
    • 图标：MoreIcon（默认 ellipsis-vertical）
    • 文字：可选 MoreLabel
    • 菜单项：来自 _overflowedItems（由 JS 测量决定）

5. 验证规则

无内置验证规则。

6. 状态与流程

6.1 内部状态字段

  • _items: 已注册的 SxCommandItem 列表
  • _overflowedItems: 当前被移入溢出菜单的项
  • _hasOverflow: 是否存在溢出
  • _containerId: DOM id，用于 JS 测量与回调
  • _jsModule / _dotNetRef: JS 互操作引用
  • _disposed: 是否已释放

6.2 Overflow 模式核心流程

  1. 首次渲染：OnAfterRenderAsync 初始化 JS 模块并调用 init(containerId, dotNetRef, options)
  2. JS 测量：sx-commandbar.js 读取 DOM .sx-command-item 宽度，计算 fullWidth / iconOnlyWidth
  3. 折叠策略：
    • CollapseLabels: 仅隐藏标签
    • CollapseItems: 仅移入 overflow 菜单
    • Both: 先隐藏标签，再移入 overflow 菜单
  4. 回调 .NET：JS 调用 UpdateOverflowState(collapsedIndices, overflowedIndices)
  5. .NET 更新：
    • _overflowedItems 更新
    • 对每个 SxCommandItem 调用 SetLabelVisible 与 SetVisible
    • 触发 OnOverflowChanged 回调
  6. UI 更新：StateHasChanged()，显示/隐藏溢出按钮，折叠标签或隐藏 item

6.3 Wrap 模式核心流程

  • 不使用 JS
  • .sx-command-bar--wrap 使用 CSS Grid (auto-fill) 自动换行
  • icon-only 模式被强制显示标签（CSS override）

7. 公共 API

7.1 Parameters

参数 类型 默认值 说明
ChildContent RenderFragment? null 命令项内容（通常是 SxCommandItem）
Orientation Orientation Horizontal 布局方向（横/竖）
OverflowBehavior OverflowBehavior Both 溢出策略（隐藏标签/移入菜单/两者）
MinVisibleItems int 1 至少保留可见的 item 数量
MoreIcon string ellipsis-vertical 溢出按钮图标
MoreLabel string? null 溢出按钮文字（可选）
OnOverflowChanged EventCallback<CommandBarOverflowState> - 溢出状态变化回调
Size ControlSize Small 命令项默认尺寸
Appearance ButtonAppearance Stealth 命令项默认外观
LabelMode LabelMode Auto 标签显示策略（由 SxCommandItem 使用）
Justify CommandBarJustify Start 对齐方式（Start/End）
LayoutMode CommandBarLayoutMode Overflow 布局模式（Overflow/Wrap）
WrapMinItemWidth string 120px Wrap 模式下最小 item 宽度

来自 SxComponentBase：

参数 类型 默认值 说明
Id string? null 容器 DOM id（通常由内部生成 _containerId）
Class string? null 追加 CSS 类
Style string? null 追加内联样式
Title string? null title
TabIndex int? null tabindex
AccessKey string? null accesskey
Disabled bool false 禁用（整条命令栏）
Loading bool false 加载态（影响 IsDisabled）

7.2 Public Methods

  • UpdateOverflowState(int[] collapsedLabelIndices, int[] overflowedIndices)：由 JS 调用，更新折叠/溢出结果
  • GetItemInfo()：供 JS 获取 item 元信息（Priority/Collapsible/HasLabel/HasIcon）
  • DisposeAsync()：释放 JS 模块与引用

7.3 Events/Callbacks

  • OnOverflowChanged(CommandBarOverflowState state)：溢出状态改变时触发

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

8.1 UC-1: 标准命令栏

  1. 渲染 SxCommandBar + 多个 SxCommandItem
  2. 在宽屏下所有 item 完整显示
  3. 点击 item 触发 OnClick

8.2 UC-2: 溢出折叠（Both）

  1. 设置 OverflowBehavior=Both
  2. 容器变窄
  3. 先隐藏部分标签，再将部分 item 移入 overflow 菜单
  4. OnOverflowChanged 回调触发

8.3 UC-3: Wrap 模式网格化

  1. 设置 LayoutMode=Wrap
  2. 使用 WrapMinItemWidth 控制列宽
  3. item 自动换行并等宽

8.4 UC-4: 优先级控制

  1. 给 SxCommandItem 设置 Priority
  2. 当溢出发生时，Priority 高的 item 优先折叠/溢出

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

  • 同一组 SxCommandItem 重复渲染不应导致 _items 重复注册
  • LayoutMode=Wrap 时不应创建 JS module
  • LayoutMode 在运行时切换时，溢出状态应重新计算（需人工验证）

10. 测试检查点

10.1 必须测试

  • Overflow 模式下，容器宽度不足时 _hasOverflow 为 true
  • Wrap 模式下，不渲染 overflow 按钮
  • OnOverflowChanged 在溢出变化时触发
  • MinVisibleItems 生效：不会少于该数量可见

10.2 边界情况

  • 无 SxCommandItem 时不报错
  • 所有 item Collapsible=false 时不折叠
  • item 没有 Label 但有 Icon 时能正常测量

10.3 JS 互操作

  • GetItemInfo 返回的 Priority/Collapsible/HasLabel/HasIcon 正确
  • UpdateOverflowState 能正确更新 SetLabelVisible/SetVisible

11. 规范合规检查

  • 未检测到非 Sx 元素的直接使用（符合规范）
  • Wrap 模式使用 CSS Grid（符合规范）
  • WrapMinItemWidth 为硬编码 120px（建议确认是否需要 token 替代）

11. Fluent UI 对齐

对应 Fluent UI Blazor 组件：FluentToolbar 源码：src/Core/Components/Toolbar/FluentToolbar.razor(.cs) 对齐要点：

  • 默认 Orientation=Horizontal，构造时生成 Id。
  • EnableArrowKeyTextNavigation=true 时 JS 注入阻止输入框内方向键导航。
  • 初始化与释放均通过 JS module prevent/remove 行为。 关键参数/事件：
  • Orientation、EnableArrowKeyTextNavigation。 差异与扩展：
  • SxCommandBar 的溢出策略可自定义，但方向与键盘行为需保持一致。

12. 变更历史

  • 2026-02-04: 深度分析填充规范。