命令面板 | astryx-vue

使用方法

CommandPalette（命令面板）是一个可以通过键盘全局唤起、支持即时搜索的指令弹窗，类似于 VS Code 或 Mac 上的 Spotlight 搜索。它把居中弹窗、输入搜索框、指令分组、键盘上下选行、以及搜不到时的空状态都封装在了一起。只要传入数据源 SearchSource，输入框为空时它会展示推荐列表（bootstrap），用户打字时则会即时进行关键词搜索（search）。

什么时候用：

需要为高级用户提供全局快捷键（如 Cmd + K 或 Ctrl + K），让他们能够秒级搜索页面、执行快捷操作或跳转路由时。

什么时候不要用：

普通表单里的局部下拉选择，请使用 Selector 或下拉菜单。
站内文章的全文搜索结果页，更适合使用带翻页的专属搜索大页面。

通过快捷键打开面板非常简单，配合 useHotkeys 监听快捷键，控制 isOpen 开关即可：

vue

<script setup lang="ts">
import { createStaticSource, useHotkeys } from '@astryx-vue/core'
import { CommandPalette } from '@astryx-vue/core/CommandPalette'
import { ref } from 'vue'

const isOpen = ref(false)
const source = createStaticSource([
  { id: 'home', label: 'Home' },
  { id: 'settings', label: 'Settings' },
])

function openPalette() {
  isOpen.value = true
}

useHotkeys([{ keys: 'mod+k', onPress: openPalette }])
</script>

<template>
  <CommandPalette
    :is-open="isOpen"
    :search-source="source"
    @open-change="isOpen = $event"
  />
</template>

其他好用的配置包括：

v-model:value：可以把命令面板变成单选选择器，当前选中的项会保留打勾标记。
在数据项里配置 auxiliaryData.group，组件就会自动将菜单整理成带标题的分类区域。
上下方向键在选项间移动高亮，到头就停住。Home 和 End 留在输入框里，不改高亮。Page Up 跳到第一项可用项，Page Down 跳到最后一项可用项。Enter 执行当前高亮行。Escape 关掉面板，并丢掉还没回来的异步搜索。鼠标划过只会移动高亮，不会把列表滚走。
只有在做组件文档演示或特殊内嵌时才开启 isInline（将面板平铺在页面里），正常的实际业务项目中请保持默认的模态弹窗形式。

解剖

部分	说明
对话框	装着命令面板的模态表面。
输入区	装着查询框和配套视觉的搜索区域。
搜索符号	默认输入区里由 Icon 画出的搜索符号。
查询框	用来输入搜索词的原生文本框。
加载转圈	搜索进行中时，默认输入区里的转圈。
列表	可滚动的列表框，装着当前结果或空状态。
项	列表里可选的一条命令结果。
分组	共享一个标题的一组项，可选。
分组标题	分组显示出来的标题。
空状态	当前没有结果时显示的消息。
页脚	放默认的键盘提示，或使用方自己的内容。
快捷键	默认页脚提示里由 Kbd 画出的按键徽章。

示例

异步搜索

搜索会稍等一下再按文件名过滤。还没输入时提示输入文件名。

分组

Home 和 Settings 在 Navigation 下，New File 和 Save 在 Actions 下。

自定义页脚

底部提示换成一句说明。

选择模式

Light、Dark、System。当前主题保留勾选标记。

带附加信息的条目

行上显示命令；设置了快捷键时，右侧会显示按键。

使用方法 ​

解剖

示例 ​

异步搜索

分组

自定义页脚

选择模式

带附加信息的条目

使用方法

示例