命令面板 · CommandPalette

集中搜索和执行命令，支持键盘操作。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Command Palette

CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.

属性	类型	默认值	说明
isOpen *	boolean		Whether the command palette dialog is visible.
onOpenChange *	(isOpen: boolean) => void		Called when the palette visibility changes.
searchSource *	SearchSource<T>		Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.
input	ReactNode	<CommandPaletteInput />	Input slot. Defaults to CommandPaletteInput with standard behavior.
footer	ReactNode	<CommandPaletteFooter />	Footer slot. Defaults to CommandPaletteFooter showing keyboard hints.
renderItem	(item: T, isSelected: boolean) => ReactNode		Per-item render function for non-interactive presentation content such as labels, icons, descriptions, and shortcut hints. Do not return buttons or links inside the option. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.
emptySearchText	ReactNode	'No results'	Content shown when a search query returns no results.
emptyBootstrapText	ReactNode	'Type to search'	Content shown when there is no search query and bootstrap() returns nothing.
value	string		Controlled selected value for picker mode.
onValueChange	(value: string) => void		Called when the selected value changes in picker mode.
label	string	'Command palette'	Accessible label for the command palette dialog.
width	number \| string	640	Width of the dialog.
maxHeight	number \| string	480	Maximum height of the dialog.
isInline	boolean	false	Renders command palette content inline without modal behavior. Automatically disables input auto-focus and initial highlighted-item auto-scroll. For documentation previews and showcases only.

使用建议

Provide a searchSource with bootstrap results so users see useful options before typing.
Use auxiliaryData.group on items to automatically organize results into labeled sections.
Provide a specific label when more than one command palette can appear in the same product surface.
Keep renderItem content non-interactive; each rendered row is one option, so buttons and links cannot be nested inside it.
避免：Intercept query-field keyboard events without preserving active IME composition and native Home/End caret movement.
避免：Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.
避免：Add too many groups or items; curate results to keep the palette fast and scannable.

主题 API

{
  "targets": [
    {
      "className": "astryx-command-palette-empty"
    },
    {
      "className": "astryx-command-palette-footer"
    },
    {
      "className": "astryx-command-palette-group"
    },
    {
      "className": "astryx-command-palette-group-heading"
    },
    {
      "className": "astryx-command-palette-input"
    },
    {
      "className": "astryx-command-palette-item"
    },
    {
      "className": "astryx-command-palette-list"
    }
  ]
}

CommandPaletteInput

CommandPaletteList

CommandPaletteItem

CommandPaletteGroup

CommandPaletteFooter

CommandPaletteEmpty

组件结构

Dialog: Modal surface that contains the command palette.
Input: Search region containing the query field and its supporting visuals.
Search glyph: Search symbol rendered by Icon in the default Input.
Query field: Native text field used to enter a search query.
Loading spinner: Spinner shown in the default Input while a search is pending.
List: Scrollable results container: a listbox while selectable results exist, otherwise the Empty state as plain content.
Item: Selectable command result rendered inside the List.
Group: Optional collection of Items that share a heading.
Group heading: Visible heading rendered for a Group.
Empty: Message shown when the current result set is empty.
Footer: Footer region for default keyboard guidance or caller-provided content.
Keyboard shortcut: Painted key badges rendered by Kbd in the default Footer guidance.

Command Palette Empty

结果区域的空状态展示。由 CommandPalette 在无结果和无查询状态下自动渲染。

属性	类型	默认值	说明
children *	ReactNode		要显示的消息或内容。

CommandPalette renders CommandPaletteFooter automatically. Pass a CommandPaletteFooter to the footer slot only when replacing the default guidance.

属性	类型	默认值	说明
children	ReactNode		自定义页脚内容。省略时通过 Kbd 渲染默认键盘提示。
xstyle	StyleXStyles		StyleX 布局自定义样式。必须是 stylex.create() 的值。

主题 API

{
  "targets": [
    {
      "className": "astryx-command-palette-footer"
    }
  ]
}

组件结构

Footer: Supporting region that presents default guidance or caller-provided footer content.
Keyboard shortcut: Default Kbd badges for navigation, selection, and dismissal.

Command Palette Group

带标题标签的视觉分组。放置在 CommandPaletteList 内。

属性	类型	说明
heading *	string	分组标题文本。
children *	ReactNode	CommandPaletteItem 子元素。
xstyle	StyleXStyles	StyleX 布局自定义样式。必须是 stylex.create() 的值。

Command Palette Input

Use CommandPaletteInput inside CommandPalette for a popup-backed command query, or as an independent search field when no result popup is present.

属性	类型	默认值	说明
placeholder	string	'Search…'	输入框的占位文本。
label	string		查询字段的无障碍标签，供屏幕阅读器朗读。默认为翻译后的 "Search commands"；占位文本不会用作名称。
hasAutoFocus	boolean	true	挂载时自动聚焦输入框。内联命令面板中自动禁用。
endContent	ReactNode		渲染在输入框末尾的内容，位于加载指示器之后。
value	string		搜索值。在 CommandPalette 内省略时从上下文读取。
onValueChange	(value: string) => void		搜索值变化时调用。在 CommandPalette 内省略时写入上下文。
xstyle	StyleXStyles		StyleX 布局自定义样式。必须是 stylex.create() 的值。

使用建议

Pass a concise label that identifies what can be searched when "Search commands" does not describe it; the placeholder is never the field's name.
Use endContent for short supporting controls or shortcut hints at the trailing edge.
避免：Override combobox role or popup state. CommandPaletteInput owns those semantics when connected to CommandPalette.

主题 API

{
  "targets": [
    {
      "className": "astryx-command-palette-input"
    }
  ]
}

组件结构

Input: The surrounding inline layout for the search glyph, query field, and trailing content.
Search glyph: A decorative search icon before the query field.
Query field: The native text field. It is a searchbox when standalone without popup attributes and a combobox when popup relationships are supplied or CommandPalette context is present.
Loading spinner: A delayed pending indicator shown before trailing content while search is busy.
Trailing content: Caller-provided supporting content such as a clear control or shortcut hint.

Command Palette Item

Use CommandPaletteItem for one non-interactive result row inside CommandPaletteList or CommandPaletteGroup. CommandPalette owns the composite keyboard model; standalone items expose only their explicit visual state and pointer activation.

属性	类型	默认值	说明
value *	string		用于条目标识、高亮查找和选择的唯一值。
children *	ReactNode		非交互式条目内容，例如标签、图标、描述或键盘快捷键。
onSelect	(value: string) => void		通过指针激活此条目后调用。CommandPalette 中的键盘选择通过根组件的 onValueChange 报告。
isHighlighted	boolean	false	此条目是否为当前键盘结果。在 CommandPalette 内省略时从上下文派生。
isSelected	boolean	false	此条目是否代表选择器模式中的已选值。
isDisabled	boolean	false	条目是否不可用并禁止指针激活。
xstyle	StyleXStyles		StyleX 布局自定义样式。必须是 stylex.create() 的值。

使用建议

Keep each value unique within the result list so highlight, active-descendant identity, and selection resolve to the same item.
Use non-interactive child content such as icons, descriptions, and shortcut hints; activate the option itself instead of nesting buttons or links.
避免：Treat isHighlighted as selection. Highlight is the active keyboard result; isSelected represents the chosen value.

主题 API

{
  "targets": [
    {
      "className": "astryx-command-palette-item"
    }
  ]
}

组件结构

Item: The option root that carries selection, disabled, item identity, interaction, and theme state.
Content: Caller-provided non-interactive label and supporting presentation.

Command Palette List

可滚动的结果容器。独立使用时，以及在 CommandPalette 中存在可选结果时，作为 listbox 渲染。

属性	类型	默认值	说明
children *	ReactNode		条目、分组和空状态。
label	string	'Commands'	listbox 的无障碍标签。
xstyle	StyleXStyles		StyleX 布局自定义样式。必须是 stylex.create() 的值。

命令面板

命令面板 · CommandPalette

安装与前置条件

示例与使用方式

API 与上游详细参考

Command Palette

使用建议

主题 API

CommandPaletteInput

CommandPaletteList

CommandPaletteItem

CommandPaletteGroup

CommandPaletteFooter

CommandPaletteEmpty

组件结构

Command Palette Empty

Command Palette Footer

主题 API

组件结构

Command Palette Group

Command Palette Input

使用建议

主题 API

组件结构

Command Palette Item

使用建议

主题 API

组件结构

Command Palette List