onKeyStroke

类别

Sensors

导出体积

728 B

上次更改

6 minutes ago

监听键盘按键事件。默认情况下，监听 window 上的 keydown 事件。

示例

源码playground (beta)

使用箭头键或 w a s d 键来控制球的移动。

在按下键 `d` 或 `->` 时重复的事件将被忽略。

用法

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('ArrowDown', (e) => {
  e.preventDefault()
})

请参阅此表格获取所有按键代码。

返回值

返回一个停止函数，用于移除事件监听器。

const stop = onKeyStroke('Escape', handler)

// 之后，停止监听
stop()

监听多个按键

import { onKeyStroke } from '@vueuse/core'

onKeyStroke(['s', 'S', 'ArrowDown'], (e) => {
  e.preventDefault()
})

// 通过传入 `true` 或省略按键参数来监听所有按键
onKeyStroke(true, (e) => {
  e.preventDefault()
})
onKeyStroke((e) => {
  e.preventDefault()
})

自定义键盘谓词

你可以传入自定义函数来判断哪些按键会触发回调。

import { onKeyStroke } from '@vueuse/core'

onKeyStroke(
  e => e.key === 'A' && e.shiftKey,
  (e) => {
    console.log('Shift+A 被按下')
  },
)

自定义事件目标

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('A', (e) => {
  console.log('按键 A 在文档上被按下')
}, { target: document })

忽略重复事件

当按下 A 键并保持按下时，回调函数只会触发一次。dedupe 选项也可以是响应式的 ref。

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('A', (e) => {
  console.log('按键 A 被按下')
}, { dedupe: true })

参考：KeyboardEvent.repeat

被动模式

设置 passive: true 可使用被动事件监听器。

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('A', handler, { passive: true })

指令用法

<script setup lang="ts">
import { vOnKeyStroke } from '@vueuse/components'

function onUpdate(e) {
  // 实现...
}
</script>

<template>
  <input v-on-key-stroke:c,v="onUpdate" type="text">
  <!-- 带有选项 -->
  <input v-on-key-stroke:c,v="[onUpdate, { eventName: 'keyup' }]" type="text">
</template>

自定义键盘事件

import { onKeyStroke } from '@vueuse/core'

onKeyStroke('Shift', (e) => {
  console.log('按键 Shift 松开')
}, { eventName: 'keyup' })

或者

import { onKeyUp } from '@vueuse/core'

onKeyUp('Shift', () => console.log('按键 Shift 松开'))

快捷方式

• onKeyDown - onKeyStroke(key, handler, {eventName: 'keydown'}) 的别名
• onKeyPressed - onKeyStroke(key, handler, {eventName: 'keypress'}) 的别名
• onKeyUp - onKeyStroke(key, handler, {eventName: 'keyup'}) 的别名

类型声明

显示类型声明

export type KeyPredicate = (event: KeyboardEvent) => boolean
export type KeyFilter = true | string | string[] | KeyPredicate
export type KeyStrokeEventName = "keydown" | "keypress" | "keyup"
export interface OnKeyStrokeOptions {
  eventName?: KeyStrokeEventName
  target?: MaybeRefOrGetter<EventTarget | null | undefined>
  passive?: boolean
  /**
   * 当按键持续按下时，设置为`true`以忽略重复事件。
   *
   * @default false
   */
  dedupe?: MaybeRefOrGetter<boolean>
}
/**
 * 监听键盘按键事件。
 *
 * @see https://vueuse.org/onKeyStroke
 */
export declare function onKeyStroke(
  key: KeyFilter,
  handler: (event: KeyboardEvent) => void,
  options?: OnKeyStrokeOptions,
): () => void
export declare function onKeyStroke(
  handler: (event: KeyboardEvent) => void,
  options?: OnKeyStrokeOptions,
): () => void
/**
 * 监听指定按键的 keydown 事件。
 *
 * @see https://vueuse.org/onKeyStroke
 * @param key
 * @param handler
 * @param options
 */
export declare function onKeyDown(
  key: KeyFilter,
  handler: (event: KeyboardEvent) => void,
  options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void
/**
 * 监听指定按键的 keypress 事件。
 *
 * @see https://vueuse.org/onKeyStroke
 * @param key
 * @param handler
 * @param options
 */
export declare function onKeyPressed(
  key: KeyFilter,
  handler: (event: KeyboardEvent) => void,
  options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void
/**
 * 监听指定按键的 keyup 事件。
 *
 * @see https://vueuse.org/onKeyStroke
 * @param key
 * @param handler
 * @param options
 */
export declare function onKeyUp(
  key: KeyFilter,
  handler: (event: KeyboardEvent) => void,
  options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void

源码

源码 • 演示 • 文档

贡献者

一纸忘忧

更新日志

没有最近的更新日志