@composy/hotkey-vue

@composy/hotkey-vue

Vue 3 快捷键管理适配层 — 提供 composable、指令和插件。

安装

pnpm add @composy/hotkey-vue

快速开始

// main.ts
import { createApp } from 'vue'
import { createHotkeyPlugin } from '@composy/hotkey-vue'
import App from './App.vue'

const app = createApp(App)
app.use(createHotkeyPlugin({ scope: 'global' }))
app.mount('#app')

<script setup lang="ts">
import { useHotkey, useHotkeyScope, useHotkeyHelp } from '@composy/hotkey-vue'

const { setScope } = useHotkeyScope('editor')
const { toggle } = useHotkeyHelp()

useHotkey('ctrl+s', () => save(), { description: '保存文件' })
useHotkey('ctrl+z', () => undo(), { description: '撤销', scope: 'editor' })
</script>

<template>
  <button v-hotkey="'ctrl+n'" @click="createNew">新建</button>
  <button v-hotkey="{ key: 'ctrl+s', handler: save, description: '保存' }">保存</button>
  <button @click="toggle">快捷键帮助</button>
</template>

API

createHotkeyPlugin(options?)

创建 Vue 插件，提供 manager 注册和 v-hotkey 指令。

app.use(
  createHotkeyPlugin({
    scope: 'global',
    preventDefault: true,
  })
)

也可以传入已有的 HotkeyManager：

const manager = new HotkeyManager({ scope: 'global' })
app.use(createHotkeyPlugin({ manager }))

插件自己创建的 manager 会在 Vue 应用卸载时销毁；传入的 manager 属于调用方，插件不会替调用方销毁。

useHotkey(key, handler, options?)

组合式函数，组件生命周期内自动注册/注销快捷键。

useHotkey('ctrl+s', save, {
  description: '保存',
  scope: 'editor',
  preventDefault: true,
  priority: 10,
  eventType: 'keyup',
})

useHotkey ? v-hotkey ??? ignoreInputs?allowRepeat ? ignoreComposing???????????????????? IME ????????????

useHotkeyScope(scope?)

组合式函数，管理快捷键作用域。组件挂载时切换，卸载时恢复。

const { currentScope, setScope, getBindings } = useHotkeyScope('editor')

useHotkeyHelp()

组合式函数，管理帮助面板。

const { show, hide, toggle } = useHotkeyHelp()

v-hotkey 指令

<!-- 简单字符串 -->
<button v-hotkey="'ctrl+s'">保存</button>

<!-- 带描述 (arg) -->
<button v-hotkey:保存="'ctrl+s'">保存</button>

<!-- 完整对象 -->
<button v-hotkey="{ key: 'ctrl+s', handler: save, description: '保存' }">保存</button>

<!-- 支持完整绑定选项 -->
<button v-hotkey="{ key: 'ctrl+s', handler: save, eventType: 'keyup', priority: 10 }">保存</button>

HOTKEY_MANAGER_KEY

Vue injection key，用于手动 provide/inject manager。

import { inject } from 'vue'
import { HOTKEY_MANAGER_KEY } from '@composy/hotkey-vue'

const manager = inject(HOTKEY_MANAGER_KEY)

重导出 Core

本包重导出所有 @composy/hotkey-core 类型和类，无需额外安装 core：

import { HotkeyManager, parseHotkey } from '@composy/hotkey-vue'

构建产物

构建配置位于 packages/vue/.ldesign/builder.config.ts，TypeScript 与 ESLint 权威配置也收在同一 .ldesign/ 目录。工作区通过 pnpm run build 先构建 Core，再构建 Vue，并检查 exports 与完整产物集合。

验证

pnpm run type-check
pnpm run lint:check
pnpm run test:run
pnpm run build

响应式绑定与边界策略

useHotkey 的 key 支持普通字符串、Ref 或 getter；handler 支持普通函数或 Ref，配置支持普通对象、响应式对象或 getter。任一输入变化时，旧绑定会先幂等注销，再注册最新绑定，避免闭包持有旧 handler：

const key = ref('ctrl+s')
const handler = ref(save)
const options = reactive({
  description: '保存',
  ignoreInputs: true,
  allowRepeat: false,
})

useHotkey(key, handler, options)

HotkeyBinding 和 v-hotkey 对象写法也支持 ignoreInputs、allowRepeat 与 ignoreComposing。useHotkeyScope() 会跟踪同一 manager 的外部 scope 切换，useHotkeyHelp() 会在帮助面板打开期间监听注册、移除和 scope 事件并刷新内容；组件卸载时会清理订阅、面板和由 composable 自己创建的资源。