v-hotkey

简介

v-hotkey 指令用于监听键盘事件，并在事件发生时执行指定的回调函数，支持单个或多个按键的组合。

基本用法

将 v-hotkey 指令添加到需要监听键盘事件的元素上，并指定要监听的按键组合和回调函数：

点击查看代码

<template>
  <a-card title="尝试按下单个按钮">
    <p v-hotkey="{ key: 'space', callback: handleSpace }">按 <kbd>Space</kbd></p>
    <p v-hotkey="{ key: 'w', callback: handleEnter }">按 <kbd>W</kbd></p>
  </a-card>
</template>

<script lang="ts" setup>
import { vHotkey } from '@cp-vuedir/core'
import { Notification } from '@arco-design/web-vue'

const handleSpace = () => Notification.info('Space 被按下！')
const handleEnter = () => Notification.info('W 被按下！')
</script>

<style scoped>
kbd {
  background: #333;
  color: #fff;
  padding: 3px 6px;
  border-radius: 4px;
}
</style>

多个按键组合

可以同时监听多个按键组合，当所有按键都被按下时，回调函数将被执行，按键间通过 + 符号连接：

点击查看代码

<template>
  <a-card title="尝试按下多个按键">
    <ul>
      <li
        v-hotkey="{
          key: 'shift+space',
          callback: handleMore
        }"
      >
        按下：<kbd>shift</kbd> + <kbd>space</kbd>
      </li>
      <li
        v-hotkey="{
          key: 'ctrl+alt+delete',
          callback: handleCtrlAltDelete
        }"
      >
        按下：<kbd>ctrl</kbd> + <kbd>alt</kbd> + <kbd>delete</kbd>
      </li>
    </ul>
  </a-card>
</template>

<script lang="ts" setup>
import { vHotkey } from '@cp-vuedir/core'
import { Notification } from '@arco-design/web-vue'

const handleMore = () => Notification.success('你按下了shift+space')
const handleCtrlAltDelete = () => Notification.success('你按下了ctrl+alt+delete')
</script>

<style scoped>
ul {
  list-style: none;
  padding: 0;
}
li {
  background: #f1f1f1;
  padding: 10px;
  margin: 5px;
  border-radius: 6px;
}
kbd {
  background: #333;
  color: #fff;
  padding: 3px 6px;
  border-radius: 4px;
}
</style>

自动避免可编辑元素冲突

当指令所在的元素是可编辑元素（如 input、textarea 等）时，会自动避免与可编辑元素的默认快捷键冲突，您可以放心使用。

点击查看代码

<template>
  <a-card title="尝试在输入框聚焦时按下按键">
    <a-textarea placeholder="在这里输入，Enter 不会触发"></a-textarea>
    <a-input type="text" placeholder="输入框中也不会触发快捷键" />

    <p v-hotkey="{ key: 'enter', callback: handleEnter }">按 <kbd>Enter</kbd>（不在输入框时）</p>
  </a-card>
</template>

<script lang="ts" setup>
import { vHotkey } from '@cp-vuedir/core'
import { Message } from '@arco-design/web-vue'

const handleEnter = () => Message.info('Enter 被按下！')
</script>

<style scoped>
kbd {
  background: #333;
  color: #fff;
  padding: 3px 6px;
  border-radius: 4px;
}
</style>

API

属性名	说明	类型	是否必选	默认值
event	触发事件时的回掉函数	Function	✓	无
value	监听的按键组合或单个按键，多个按键间通过 `+` 符号连接	String	✓	无