KeyboardActions is a lightweight JavaScript utility that allows you to easily define custom keyboard shortcuts and manage key events in your web applications. With features like customizable key combinations, action hooks, and event management, this package provides a flexible way to handle keyboard interactions.
Install the package via npm:
npm install keyboard-actions
- Custom Key Combinations: Define actions for specific key sequences.
- Hooks: Pre-action and post-action hooks to run custom logic before or after the key action.
- Automatic Key Ordering: Ensure that key combinations are recognized regardless of the order of key presses.
- Event Management: Easily add or remove event listeners.
- Logging: Optionally log key combinations to the console for debugging.
First, import and initialize the KeyboardActions
class:
const KeyboardActions = require('keyboard-actions');
const keyboardActions = new KeyboardActions();
You can start listening to key events by calling the start
method. To stop listening, use the stop
method.
keyboardActions.start(); // Begin listening for key events
keyboardActions.stop(); // Stop listening for key events
To add a custom action for a specific key or key combination, use the addKeyAction
method:
keyboardActions.addKeyAction('Control + S', (event) => {
console.log('Save command triggered!');
// Your custom save logic here
});
You can also add actions for single keys:
keyboardActions.addKeyAction('Escape', (event) => {
console.log('Escape key pressed!');
});
If you need to remove a specific key action, use the clearKeyAction
method:
keyboardActions.clearKeyAction('Control + S');
The KeyboardActionsConfig
class provides several options to customize the behavior of the keyboard listener.
const config = {
element: document, // The DOM element to attach the event listeners to
logKeys: true, // Whether to log key combinations to the console
keepDefault: false, // Prevent default browser behavior for key events
isAutoKeyOrdering: true, // Automatically order key combinations
preActionHook: () => {}, // Function to run before each key action
postActionHook: () => {}, // Function to run after each key action
};
You can modify the configuration by accessing the config
property of the KeyboardActions
instance:
keyboardActions.config.logKeys = false; // Disable logging
keyboardActions.config.keepDefault = true; // Allow default browser behavior
keyboardActions.config.preActionHook = () => {
console.log('Action is about to be executed!');
};
keyboardActions.config.postActionHook = () => {
console.log('Action executed!');
};
The Utils.onWindowChange
method can be used to attach a callback function that runs when the window's focus changes:
const Utils = require('keyboard-actions').Utils;
Utils.onWindowChange((event) => {
if (event.type === 'blur') {
console.log('Window lost focus');
} else if (event.type === 'focus') {
console.log('Window gained focus');
}
});
Here's an example of how you can implement a simple keyboard shortcut using KeyboardActions
:
const KeyboardActions = require('keyboard-actions');
const keyboardActions = new KeyboardActions();
keyboardActions.addKeyAction('Control + N', (event) => {
console.log('New document command triggered!');
// Your logic to create a new document
});
keyboardActions.addKeyAction('Control + S', (event) => {
console.log('Save command triggered!');
// Your logic to save the current document
});
keyboardActions.start();
const keyboardActions = new KeyboardActions();
// Custom pre-action and post-action hooks
keyboardActions.config.preActionHook = () => console.log('Before action');
keyboardActions.config.postActionHook = () => console.log('After action');
// Enable automatic key ordering
keyboardActions.config.isAutoKeyOrdering = true;
keyboardActions.addKeyAction('N + Control', () => {
console.log('This will work even if N is pressed before Control');
});
keyboardActions.start();
The EventsManager
class allows you to easily add and remove event listeners:
const EventsManager = require('keyboard-actions').EventsManager;
const eventsManager = new EventsManager({ element: document });
// Add custom event listeners
eventsManager.addEventListener('click', () => console.log('Document clicked'));
eventsManager.addEventListener('keydown', () => console.log('Key down'));
// Remove all event listeners
eventsManager.remove();
Contributions are welcome! Please submit a pull request or open an issue if you have any suggestions or find any bugs.
This project is licensed under the MIT License - see the LICENSE file for details.