useMagicKeys

类别

Sensors

导出大小

1.26 kB

最近修改

2 days ago

反应式按键按下状态，具有神奇按键组合支持。

🌐 Reactive keys pressed state, with magical keys combination support.

示例

源代码在线运行

Press the following keys to test out

V

u

e

U

s

e

Shift

Vue

Use

Keys Pressed

用法

🌐 Usage

import { useMagicKeys } from '@vueuse/core'

const { shift, space, a /* keys you want to monitor */ } = useMagicKeys()

watch(space, (v) => {
  if (v)
    console.log('space has been pressed')
})

watchEffect(() => {
  if (shift.value && a.value)
    console.log('Shift + A have been pressed')
})

注意

如果你在 tsconfig.json 中启用了 noUncheckedIndexedAccess 并使用 TypeScript（或者使用默认启用它的 Nuxt），解构的键将具有类型 ComputedRef<boolean> | undefined。

noUncheckedIndexedAccess TypeScript 选项会将 undefined 添加到通过索引签名访问的任何未声明字段。由于 useMagicKeys() 使用索引签名以允许动态访问任何键，TypeScript 会为了类型安全将解构的属性视为可能未定义。

🌐 The noUncheckedIndexedAccess TypeScript option adds undefined to any un-declared field accessed via index signatures. Since useMagicKeys() uses an index signature to allow accessing any key dynamically, TypeScript will treat destructured properties as potentially undefined for type safety.

你需要使用可选链或者用一个 getter 函数封装：

🌐 You'll need to use optional chaining or wrap with a getter function:

const { shift, space, a } = useMagicKeys()

watch(
  () => space?.value,
  (v) => {
    if (v)
      console.log('space has been pressed')
  },
)

watchEffect(() => {
  if (shift?.value && a?.value)
    console.log('Shift + A have been pressed')
})

有关 noUncheckedIndexedAccess 的更多详细信息，请查看 TypeScript 文档。

🌐 Check the TypeScript documentation for more details about noUncheckedIndexedAccess.

查看所有可能的按键代码。

🌐 Check out all the possible keycodes.

组合

🌐 Combinations

你可以通过使用 + 或 _ 连接按键来神奇地使用组合键（快捷键/热键）。

🌐 You can magically use combinations (shortcuts/hotkeys) by connecting keys with + or _.

import { useMagicKeys } from '@vueuse/core'

const keys = useMagicKeys()
const shiftCtrlA = keys['Shift+Ctrl+A']

watch(shiftCtrlA, (v) => {
  if (v)
    console.log('Shift + Ctrl + A have been pressed')
})

import { useMagicKeys } from '@vueuse/core'

const { Ctrl_A_B, space, alt_s /* ... */ } = useMagicKeys()

watch(Ctrl_A_B, (v) => {
  if (v)
    console.log('Control+A+B have been pressed')
})

你也可以使用 whenever 函数来让它更短

🌐 You can also use whenever function to make it shorter

import { useMagicKeys, whenever } from '@vueuse/core'

const keys = useMagicKeys()

whenever(keys.shift_space, () => {
  console.log('Shift+Space have been pressed')
})

当前按下的键

🌐 Current Pressed keys

提供了一个特殊属性 current 用于表示当前所有被按下的按键。

🌐 A special property current is provided to representing all the keys been pressed currently.

import { useMagicKeys, whenever } from '@vueuse/core'

const { current } = useMagicKeys()

console.log(current) // Set { 'control', 'a' }

whenever(
  () => current.has('a') && !current.has('b'),
  () => console.log('A is pressed but not B'),
)

键别名

🌐 Key Aliasing

import { useMagicKeys, whenever } from '@vueuse/core'

const { shift_cool } = useMagicKeys({
  aliasMap: {
    cool: 'space',
  },
})

whenever(shift_cool, () => console.log('Shift + Space have been pressed'))

默认情况下，我们为一些常见做法提供了一些预配置的别名。

🌐 By default, we have some preconfigured alias for common practices.

有条件地禁用

🌐 Conditionally Disable

你的应用中可能有一些 <input /> 元素，你不希望在用户聚焦这些输入时触发快捷键处理。有一个使用 useActiveElement 和 logicAnd 来实现该功能的例子。

🌐 You might have some <input /> elements in your apps, and you don't want to trigger the magic keys handling when users focused on those inputs. There is an example of using useActiveElement and logicAnd to do that.

import { useActiveElement, useMagicKeys, whenever } from '@vueuse/core'
import { logicAnd } from '@vueuse/math'

const activeElement = useActiveElement()
const notUsingInput = computed(() =>
  activeElement.value?.tagName !== 'INPUT'
  && activeElement.value?.tagName !== 'TEXTAREA',)

const { tab } = useMagicKeys()

whenever(logicAnd(tab, notUsingInput), () => {
  console.log('Tab has been pressed outside of inputs!')
})

自定义事件处理程序

🌐 Custom Event Handler

import { useMagicKeys, whenever } from '@vueuse/core'

const { ctrl_s } = useMagicKeys({
  passive: false,
  onEventFired(e) {
    if (e.ctrlKey && e.key === 's' && e.type === 'keydown')
      e.preventDefault()
  },
})

whenever(ctrl_s, () => console.log('Ctrl+S have been pressed'))

⚠️ 不建议使用此方法，请谨慎使用。

反应式模式

🌐 Reactive Mode

默认情况下，useMagicKeys() 的值是 Ref<boolean>。如果你想在模板中使用该对象，可以将其设置为响应式模式。

🌐 By default, the values of useMagicKeys() are Ref<boolean>. If you want to use the object in the template, you can set it to reactive mode.

const keys = useMagicKeys({ reactive: true })

<template>
  <div v-if="keys.shift">
    You are holding the Shift key!
  </div>
</template>