useMagicKeys

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

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

This function uses Proxy

It is NOT supported by IE 11 or below.

示例

source

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')
})

看看 所有可能的键码。

¥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'))

⚠️ 不推荐此用法，请谨慎使用。

¥⚠️ This usage is NOT recommended, please use with caution.

反应式模式

¥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>

类型声明

显示类型声明

export interface UseMagicKeysOptions<Reactive extends boolean> {
  /**
   * Returns a reactive object instead of an object of refs
   *
   * @default false
   */
  reactive?: Reactive
  /**
   * Target for listening events
   *
   * @default window
   */
  target?: MaybeRefOrGetter<EventTarget>
  /**
   * Alias map for keys, all the keys should be lowercase
   * { target: keycode }
   *
   * @example { ctrl: "control" }
   * @default <predefined-map>
   */
  aliasMap?: Record<string, string>
  /**
   * Register passive listener
   *
   * @default true
   */
  passive?: boolean
  /**
   * Custom event handler for keydown/keyup event.
   * Useful when you want to apply custom logic.
   *
   * When using `e.preventDefault()`, you will need to pass `passive: false` to useMagicKeys().
   */
  onEventFired?: (e: KeyboardEvent) => void | boolean
}
export interface MagicKeysInternal {
  /**
   * A Set of currently pressed keys,
   * Stores raw keyCodes.
   *
   * @see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key
   */
  current: Set<string>
}
export type UseMagicKeysReturn<Reactive extends boolean> = Readonly<
  Omit<
    Reactive extends true
      ? Record<string, boolean>
      : Record<string, ComputedRef<boolean>>,
    keyof MagicKeysInternal
  > &
    MagicKeysInternal
>
/**
 * Reactive keys pressed state, with magical keys combination support.
 *
 * @see https://vueuse.org/useMagicKeys
 */
export declare function useMagicKeys(
  options?: UseMagicKeysOptions<false>,
): UseMagicKeysReturn<false>
export declare function useMagicKeys(
  options: UseMagicKeysOptions<true>,
): UseMagicKeysReturn<true>
export { DefaultMagicKeysAliasMap } from "./aliasMap"

源代码

源代码 • 示例 • 文档

变更日志

No recent changes