# 命令面板项

## 使用方法

`CommandPaletteItem` 就是结果列表里的一行。它本身不带交互，放进 `CommandPaletteList` 或 `CommandPaletteGroup` 里用。键盘那一套由 `CommandPalette` 统一管；单独用的时候，它只负责你明确传进来的视觉状态和鼠标点击。

```ts
import { CommandPaletteItem } from '@astryx-vue/core/CommandPalette'
```

### 结构

- **项**: 选项的根元素，负责选中、禁用、身份、交互和主题状态。
- **内容**: 使用方放进去的、不带交互的文字和辅助展示。

## 最佳实践

| 指引 | 实践 |
| --- | --- |
| 推荐 | 每个 `value` 在同一份结果里保持唯一，这样高亮、active-descendant 和选中才能对上同一行。 |
| 推荐 | 行里只放不带交互的内容，例如图标、说明和快捷键提示。要点就点这一行本身，别在里面再套按钮或链接。 |
| 避免 | 把 `isHighlighted` 当成选中。高亮表示键盘当前停在哪一行，`isSelected` 才表示选中的值。 |

## 示例

常见的用法和不同的状态。

### 基础

CommandPaletteList 里可以点的一行行命令，包含高亮和禁用两种状态。想自己手动拼一个面板、不用搜索源时用它。

```vue
<script setup lang="ts">
import { CommandPaletteItem, CommandPaletteList } from '@astryx-vue/core/CommandPalette'
</script>

<template>
  <CommandPaletteList>
    <CommandPaletteItem value="new-file">
      New File
    </CommandPaletteItem>
    <CommandPaletteItem is-highlighted value="open-recent">
      Open Recent
    </CommandPaletteItem>
    <CommandPaletteItem value="save-all">
      Save All
    </CommandPaletteItem>
    <CommandPaletteItem is-disabled value="publish">
      Publish (disabled)
    </CommandPaletteItem>
  </CommandPaletteList>
</template>
```

## 属性

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `value` | `string` | — | 这一行的身份。同一份列表里要保持唯一：高亮、active-descendant 和选中都靠它对上号。必填。 |
| `isDisabled` | `boolean` | `false` | 禁用这一行，点不动，键盘也会跳过它。会写上 `aria-disabled`。 |
| `isHighlighted` | `boolean` | `false` | 这一行是不是键盘当前停的那一行。不传时，从外层的 `CommandPalette` 读。单独做预览时再显式传。 |
| `isSelected` | `boolean` | `false` | 在选择模式下，这一行是不是选中的那个值。不传时，拿 `value` 去和面板的 `v-model:value` 比。会写上 `aria-selected`。 |

## 事件

- `select(value: string)`：这一行被点了一下，或者按了 Enter、空格。放在 `CommandPalette` 里时，面板接着会写入这个值并关掉面板。

## 插槽

- `default`：这一行的内容。里面别放能交互的东西——图标、文字、快捷键提示都可以，按钮和链接不行。