用途:本指南说明如何为 Sentry 的 Command+K 命令面板添加新操作。该面板基于树状收集系统,CMDKAction 组件通过 React context 自行注册,操作渲染在组件树中的实际位置,无需维护中央注册表。
核心文件:cmdk.tsx 提供 CMDKAction 组件;types.tsx 提供公开类型与 cmdkQueryOptions 辅助函数;commandPaletteSlot.tsx 提供 CommandPaletteSlot 用于作用域划分;commandPaletteGlobalActions.tsx 存放常驻全局操作。
三种插槽:task 优先级最高但保留未用;page 次之,随页面组件挂载/卸载;global 最后,对任意组织常驻。页面级操作需用 CommandPaletteSlot name="page" 包裹,全局操作统一注册在 GlobalCommandPaletteActions 中,不要新建第二个全局插槽消费者。
主要能力与模式:CMDKAction 支持导航(to)、回调(onAction)、分组/资源(resource + children)三类互斥操作;可设置 display(label、details、icon、trailingItem)、keywords、id、prompt、limit。常见模式包括导航链接、回调操作、静态分组(父标签作为面包屑前缀,组图标可反映当前状态)、异步资源选择器(用 cmdkQueryOptions 包装以注入 meta 并驱动加载指示,用 enabled: context.state === 'selected' 延迟请求,select 转换为 CommandPaletteAction[])、render-prop 子节点、通过 hook 渲染静态异步子节点、trailingItem 标记当前项、按查询内容激活资源、按状态条件渲染操作,以及以 cmdk:supplementary: 前缀的补充区(始终排最后)。
使用方式:在页面组件或其子树中包裹插槽并直接输出 CMDKAction 节点;复杂页面可拆分到多个组件,子组件无需自带插槽,继承父级上下文;向已有父组贡献平级项时用 Fragment 而非再包一层 CMDKAction。
限制:resource 必须用 cmdkQueryOptions 包装;query 为未防抖的实时输入;静态 children 加 resource 时,资源返回的分组项会被静默跳过,仅自动渲染 to 与 onAction 结果,需要分组时用 render-prop;无 children 或 resource 时组件返回 null;prompt 在无内容可下钻时无效;limit 默认值仅在 resource 与 render-prop 组合时为 4;混合实体列表的 key 需加实体类型前缀避免冲突;trailingItem 的“Current”徽章仅用于实体选择,不用于设置或模式。
适用场景:为 Sentry 前端页面、设置页、问题详情等添加命令面板操作。其他细节暂未提供。