@adariari/vue3-keyregister v0.2.1
Vue 3 Key Register
Vue 3 plugin to register and unregister key sequences. rather than pressing keys at the same time, you can execute a callback after pressing keys in certain sequence. such as h then e then l then l then o.
installation
npm install @adariari/vue3-keyregister
then in main.ts/main.js, add:
import KeyRegister from '@adariari/vue3-keyregister'
...
.use(KeyRegister)
Full example of main.js
import { createApp } from 'vue'
import App from './App.vue'
import KeyRegister from '@adariari/vue3-keyregister'
createApp(App)
.use(KeyRegister)
.mount('#app')
Example of use
<script setup>
import { ref } from 'vue'
// import composable useKeyRegister to register keys and change options
import { useKeyRegister } from '@adariari/vue3-keyregister'
const keyPressed = ref('');
//register sequence hello, and execute callback
useKeyRegister().registerKeySequence({
keyIdentity: 'h+e+l+l+o',
callback: (key) => {
console.log(key);
keyPressed.value = key;
}
})
//register sequence bye
useKeyRegister().registerKeySequence({
keyIdentity: 'b+y+e',
callback: (key) => {
console.log(key);
keyPressed.value = key;
}
})
</script>
<template>
key pressed : {{ keyPressed }}
</template>
Methods
RegisterKeySequence
useKeyRegister().registerKeySequence (
RegisteryProps: object
)
RegistryProps can accept following options:
/*
@key string keyIdentity unique identity of key sequence such as 'hello' or 'bye', maybe used as key|identity
@key string key sequence of keys such as 'ctrl+shift+alt+key' or m+m or c+a
@key boolean once if true, callback will be executed only once
@key function callback (targetKey : string, lastEvent : KeyboardEvent) => void
@key function|null validateTargetCallback callback to validate target
*/
key Or keyIdentity required callback also required
keyIdentity can be used as identity only, or to specifiy key e.g.
keyIdentity: "c+c|my cc key"
this both sets key as c+c and use keyIdentity c+c|my cc key
or you can set them separately:
key: "c+c",
keyIdentity: "my cc key"
you can also just set the key, but cautious that when you remove the key in this case, it will remove all mentions of it from any component
unregisterKeySequence
This can unregister the sequence by keyIdentity, it will remove any registered key matching the identity
useKeyRegister().unregisterKeySequence("c+c|my cc key");
registerSequenceListener
Register a listener for sequences, to customize action and process. return true if there is match or false if none
useKeyRegister().registerSequenceListener (
ListenProps: object
)
ListenProps can accept following options:
/*
@key options ListenerProps consists of
listener a callback that should take
(sequence : array<string> containing sequence of keys, lastEvent : KeyboardEvent) => boolean
Boolean value should be returned to indicate if the sequence is matched
@key Once if true, listener will be executed only once
*/
unregisterSequenceListener
Unregister listener
/*
@param listener to be unregistered
*/
You should pass same function you passed to register listener
## Options
You can set options globally either in main or in any component using composable
Available options:
```yml
// Timeout in milliseconds to wait for the next keypress
timeout: 500,
// Timeout in milliseconds to block key events after a key sequence is matched
blockingDelay: 10,
composable
const { options } = useKeyRegister();
//can set global timeout for all key sequences
options.timeout = 1000;
main
const app = createApp(App);
app.use(KeyRegister,{
// Timeout in milliseconds to wait for the next keypress
timeout: 500,
// Timeout in milliseconds to block key events after a key sequence is matched
blockingDelay: 10,
});
app.mount('#app');