defineShortcuts

一个在你的应用程序中定义键盘快捷键的可组合项。

用法

使用自动导入的 defineShortcuts 可组合项来定义键盘快捷键。

<script setup lang="ts">
const open = ref(false)

defineShortcuts({
  meta_k: () => {
    open.value = !open.value
  }
})
</script>

快捷键会自动为非 macOS 平台调整，将 meta 转换为 ctrl。
该可组合项使用 VueUse 的useEventListener来处理 keydown 事件。
有关可用快捷键的完整列表，请参阅KeyboardEvent.keyAPI 文档。请注意，按键应以小写形式书写。

在 Kbd 组件文档中了解如何在组件中显示快捷键。

API

defineShortcuts(config: ShortcutsConfig, options?: ShortcutsOptions): void

为您的应用程序定义键盘快捷键。

参数

config

ShortcutsConfig 必填

一个对象，其中键是快捷键定义，值是处理函数或快捷键配置对象。

options

ShortcutsOptions

快捷键行为的可选配置。

快捷键定义

快捷键使用以下格式定义

单个按键: 'a', 'b', '1', '?' 等。
组合键: 使用 _ 分隔按键，例如 'meta_k', 'ctrl_shift_f'
按键序列: 使用 - 定义序列，例如 'g-d'

修饰符

meta: 在 macOS 上代表 ⌘ Command，在其他平台上代表 Ctrl
ctrl: 在所有平台上代表 Ctrl
shift: 当需要 Shift 键时用于字母键

特殊按键

escape: 在 Esc 键按下时触发
enter: 在 Enter 键按下时触发
arrowleft, arrowright, arrowup, arrowdown: 在相应的方向键按下时触发

快捷键配置

每个快捷键可以定义为一个函数或一个具有以下属性的对象

interface ShortcutConfig { handler: () => void; usingInput?: boolean | string }

参数

handler

() => void 必填

当快捷键触发时执行的函数。

usingInput

boolean | string

根据输入焦点控制快捷键何时触发

false (默认): 快捷键仅在没有输入聚焦时触发
true: 即使有任何输入聚焦，快捷键也会触发
string: 快捷键仅在指定的输入（按名称）聚焦时触发

示例

基本用法

<script setup lang="ts">
defineShortcuts({
  '?': () => openHelpModal(),
  'meta_k': () => openCommandPalette(),
  'g-d': () => navigateToDashboard()
})
</script>

处理输入焦点

usingInput 选项允许您指定快捷键仅在特定输入聚焦时触发。

<template>
  <UInput v-model="query" name="queryInput" />
</template>

<script setup lang="ts">
const query = ref('')

defineShortcuts({
  enter: {
    usingInput: 'queryInput',
    handler: () => performSearch()
  },
  escape: {
    usingInput: true,
    handler: () => clearSearch()
  }
})
</script>

从菜单项中提取快捷键

使用 extractShortcuts 工具自动从菜单项中定义快捷键。

了解更多关于 extractShortcuts 工具的信息。

defineLocale

一个为您的应用程序创建自定义语言环境的工具。

extendLocale

一个用自定义翻译扩展现有语言环境的工具。