feat(onKeyStroke): support ignoring repeated stroke (#2652)

vueuse · Mar 28, 2023 · 22ca513 · 22ca513
1 parent 0823d68
commit 22ca513
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 9 deletions.
diff --git a/packages/core/onKeyStroke/demo.vue b/packages/core/onKeyStroke/demo.vue
@@ -5,21 +5,21 @@ import { onKeyStroke } from '@vueuse/core'
 const translateX = ref(0)
 const translateY = ref(0)
 
-onKeyStroke(['w', 'W', 'ArrowUp'], (e: KeyboardEvent) => {
+onKeyStroke(['w', 'W', 'ArrowUp'], () => {
   translateY.value -= 10
 })
 
-onKeyStroke(['s', 'S', 'ArrowDown'], (e: KeyboardEvent) => {
+onKeyStroke(['s', 'S', 'ArrowDown'], () => {
   translateY.value += 10
 })
 
-onKeyStroke(['a', 'A', 'ArrowLeft'], (e: KeyboardEvent) => {
+onKeyStroke(['a', 'A', 'ArrowLeft'], () => {
   translateX.value -= 10
 })
 
-onKeyStroke(['d', 'D', 'ArrowRight'], (e: KeyboardEvent) => {
+onKeyStroke(['d', 'D', 'ArrowRight'], () => {
   translateX.value += 10
-})
+}, { dedupe: true })
 </script>
 
 <template>
@@ -28,7 +28,8 @@ onKeyStroke(['d', 'D', 'ArrowRight'], (e: KeyboardEvent) => {
       <div class="ball" :style="{ transform: `translate(${translateX}px, ${translateY}px)` }" />
     </div>
     <div class="text-center mt-4">
-      Use the arrow keys or w a s d keys to control the movement of the ball.
+      <p>Use the arrow keys or w a s d keys to control the movement of the ball.</p>
+      <p>Repeated events are ignored on the key `d` or `->`.</p>
     </div>
   </div>
 </template>

diff --git a/packages/core/onKeyStroke/index.md b/packages/core/onKeyStroke/index.md
@@ -44,6 +44,21 @@ onKeyStroke('A', (e) => {
 }, { target: document })
 ```
 
+### Ignore Repeated Events
+
+The callback will trigger only once when pressing `A` and **hold down**.
+
+```js
+import { onKeyStroke, onKeyStrokeOnce } from '@vueuse/core'
+
+// use `autoRepeat` option
+onKeyStroke('A', (e) => {
+  console.log('Key A pressed')
+}, { autoRepeat: false })
+```
+
+Reference: [KeyboardEvent.repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat)
+
 ## Directive Usage
 
 ```html

diff --git a/packages/core/onKeyStroke/index.test.ts b/packages/core/onKeyStroke/index.test.ts
@@ -13,8 +13,8 @@ describe('onKeyStroke', () => {
     callBackFn = vi.fn()
   })
 
-  function createKeyEvent(key: string, type: KeyStrokeEventName) {
-    const ev = new KeyboardEvent(type, { key })
+  function createKeyEvent(key: string, type: KeyStrokeEventName, repeat = false) {
+    const ev = new KeyboardEvent(type, { key, repeat })
     element.value.dispatchEvent(ev)
   }
 
@@ -73,4 +73,13 @@ describe('onKeyStroke', () => {
     createKeyEvent('B', 'keypress')
     expect(callBackFn).toBeCalledTimes(1)
   })
+
+  it('ignore repeated events', () => {
+    onKeyStroke('A', callBackFn, { target: element, dedupe: true })
+    createKeyEvent('A', 'keydown', false)
+    createKeyEvent('A', 'keydown', true)
+    createKeyEvent('A', 'keydown', true)
+    createKeyEvent('A', 'keydown', true)
+    expect(callBackFn).toBeCalledTimes(1)
+  })
 })
diff --git a/packages/core/onKeyStroke/index.ts b/packages/core/onKeyStroke/index.ts
@@ -1,4 +1,5 @@
 import type { MaybeComputedRef } from '@vueuse/shared'
+import { resolveUnref } from '@vueuse/shared'
 import { useEventListener } from '../useEventListener'
 import { defaultWindow } from '../_configurable'
 
@@ -9,6 +10,12 @@ export interface OnKeyStrokeOptions {
   eventName?: KeyStrokeEventName
   target?: MaybeComputedRef<EventTarget | null | undefined>
   passive?: boolean
+  /**
+   * Set to `true` to ignore repeated events when the key is being held down.
+   *
+   * @default false
+   */
+  dedupe?: MaybeComputedRef<boolean>
 }
 
 const createKeyPredicate = (keyFilter: KeyFilter): KeyPredicate => {
@@ -60,9 +67,17 @@ export function onKeyStroke(...args: any[]) {
     handler = args[0]
   }
 
-  const { target = defaultWindow, eventName = 'keydown', passive = false } = options
+  const {
+    target = defaultWindow,
+    eventName = 'keydown',
+    passive = false,
+    dedupe = false,
+  } = options
   const predicate = createKeyPredicate(key)
   const listener = (e: KeyboardEvent) => {
+    if (e.repeat && resolveUnref(dedupe))
+      return
+
     if (predicate(e))
       handler(e)
   }