# 命令面板 · CommandPalette

- 页面: https://jiguang132.com/zh/resources/astryx/docs/command-palette
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

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

## 安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **命令面板 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **命令面板 · 综合展示 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 综合展示 / 分组 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 综合展示 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 综合展示 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 综合展示 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 综合展示 7**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 搜索 8**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 分组 9**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 自定义 10**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 基础用法 11**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 基础用法 12**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 基础用法 / 分组 13**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 基础用法 14**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 基础用法 15**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 基础用法 16**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 交互示例 17**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **命令面板 · 交互示例 18**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## 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

```json
{
  "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 |  | 要显示的消息或内容。 |

## Command Palette Footer

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

```json
{
  "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

```json
{
  "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

```json
{
  "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() 的值。 |

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt