Commands API 参考

Commands API 用于统一按钮、菜单、快捷键、权限、启用状态和执行入口。复杂业务系统中，同一个动作应注册为一个命令，再由工具栏、菜单、右键菜单或快捷键绑定同一个 command id。

命令不是按钮。按钮、菜单项和快捷键只是命令入口。

导出清单

核心导出：

• CommandManager
• CommandScope
• AppCommand
• CommandState
• CommandExecutionContext
• CommandTrigger
• CommandPredicate
• CommandReasonResolver
• CommandExecutor
• PermissionService
• CommandInterceptor
• CommandExecuteOptions
• CommandEvaluateOptions
• CommandInspection
• CommandScopeDiagnostic
• RenderCommandScope
• RenderCommandButton
• RenderCommandToolbar
• CommandShortcutController
• CommandShortcutControllerOptions
• normalizeShortcut
• shortcutFromKeyboardEvent
• commandShortcuts
• createCommandContextMenu
• createCommandMenuBarItems
• resolveCommandMenuEntries
• executeCommandMenuSelection
• CommandMenuItem
• CommandMenuBarItem
• CommandToolbarGroup
• CommandToolbarItem
• commandManagerContextKey

AppCommand

AppCommand<TResult = unknown> 定义一个业务动作。

visible、enabled、canExecute、checked 和 disabledReason 都接收 CommandExecutionContext。这些函数必须轻量、同步、无副作用；不要在里面请求接口、修改 UI 或扫描大数据。

CommandState

CommandManager.evaluate() 返回 CommandState。

命令不存在时，visible=false、enabled=false，reason 为 命令不存在。

CommandExecutionContext

命令执行和状态求值都会创建上下文。

appContext 是一次命令求值或执行期间的快照，CommandManager 内部会在求值和执行结束后释放它。业务不要长期持有这个快照。

CommandManager

创建命令管理器：

const commandManager = new CommandManager({  permissionService: {    has(permission, context) {      return permission === 'record.save'    },  },})

构造参数：

属性：

方法：

CommandExecuteOptions 和 CommandEvaluateOptions：

CommandScope

CommandScope 是命令的分层注册表。

构造参数：

const pageScope = new CommandScope(commandManager.rootScope, 'record-page')

属性和方法：

RenderCommandScope

RenderCommandScope 把命令 scope 挂到 render tree。子组件触发命令时，会优先解析到最近的 RenderCommandScope。

构造参数：

方法：

页面或组件命令应优先放在 RenderCommandScope。这样页面关闭、tab 销毁或组件释放时，局部命令会自动失效。

RenderCommandButton

RenderCommandButton 是绑定单个命令的按钮。

构造参数：

成员：

按钮会订阅 CommandManager，manager invalidate() 后会重新求值并更新文本、禁用、loading 和 tooltip。

RenderCommandToolbar

RenderCommandToolbar 把一组命令转换为普通 RenderToolbar 项。

构造参数：

CommandToolbarGroup：

CommandToolbarItem：

方法：

Toolbar 会隐藏 state.visible=false 的命令项，禁用 state.enabled=false 的命令项。

菜单适配

命令菜单工具把命令配置转换为 ContextMenu 或 MenuBar 需要的数据。

CommandMenuItem：

CommandMenuBarItem：

函数：

菜单适配会自动过滤不可见命令，并把命令 shortcut 显示到菜单项。

快捷键

CommandShortcutController 把键盘事件映射到当前 scope 可见命令。

构造参数：

方法和工具函数：

快捷键会从 source 解析当前命令 scope，只执行可见且可用的第一个匹配命令，并调用 event.preventDefault()。

权限服务和拦截器

PermissionService：

CommandInterceptor：

拦截器适合做统一确认、埋点、审计和错误处理。它不是业务状态存储系统。

命令检查

inspect() 和 inspectAll() 用于调试命令注册、覆盖、权限和快捷键。

CommandInspection：

CommandScopeDiagnostic：

使用示例

import {  CommandManager,  RenderCommandButton,  RenderCommandScope,  RenderStackPanel,  createAppContextKey,} from 'ds-ui' const exampleCurrentRecordKey = createAppContextKey<{ id: string }>('record.current')let exampleDirty = true const exampleCommandManager = new CommandManager({  permissionService: {    has: permission => permission === 'record.save',  },}) const exampleContent = new RenderStackPanel({ spacing: 8 })const exampleScope = new RenderCommandScope({  commandManager: exampleCommandManager,  debugLabel: 'record-page',  commands: [    {      id: 'record.save',      title: '保存',      icon: 'save',      shortcut: ['Ctrl+S', 'Meta+S'],      permission: 'record.save',      canExecute: context => exampleDirty && Boolean(context.appContext.get(exampleCurrentRecordKey)),      execute: () => {        exampleDirty = false        exampleCommandManager.invalidate()      },    },  ],  child: exampleContent,}) exampleContent.addChild(new RenderCommandButton({  commandId: 'record.save',  commandManager: exampleCommandManager,})) exampleScope

使用边界

• 页面命令优先注册在页面级 RenderCommandScope，不要注册到 root scope。
• source 很重要。没有 source 时，只能解析 root scope 和应用级上下文。
• 业务状态变化后调用 commandManager.invalidate()，不要在 hover 或 paint 中频繁调用。
• execute() 会在执行前重新求值权限和可用状态，不要只依赖按钮禁用状态。
• dispose() 后继续注册、求值或执行会抛错。
• 命令适合业务动作，不适合低层 pointer move、hover、输入字符等高频事件。

相关文档

• 命令与权限指南
• CommandButton
• CommandToolbar
• MenuBar
• ContextMenu
• 应用上下文