useMagicKeys

分类

传感器

导出大小

1.17 kB

上次更改

上个月

响应式按键状态，支持魔法按键组合。

演示

源代码在线演练 (beta)

按下以下按键进行测试

Shift

Vue

Use

已按下的按键

用法

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

查看所有可能的键码。

组合键

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

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` 函数来使其更短。

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

const keys
 = useMagicKeys
()

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

当前按下的按键

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

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

按键别名

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

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

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

默认情况下，我们有一些预配置的常用别名。

有条件禁用

你的应用中可能有一些 `` 元素，并且你不希望在用户聚焦这些输入时触发魔法按键处理。这里有一个使用`useActiveElement`和`logicAnd`的示例。

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

自定义事件处理程序

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

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

响应模式

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

const keys
 = useMagicKeys
({ reactive
: true })

vue

<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://mdn.org.cn/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.cn/useMagicKeys
 */
export declare function useMagicKeys
(
  options
?: UseMagicKeysOptions
<false>,
): UseMagicKeysReturn
<false>
export declare function useMagicKeys
(
  options
: UseMagicKeysOptions
<true>,
): UseMagicKeysReturn
<true>
export { DefaultMagicKeysAliasMap
 } from "./aliasMap"