Skip to content

Latest commit

 

History

History
139 lines (106 loc) · 3.9 KB

README.md

File metadata and controls

139 lines (106 loc) · 3.9 KB
Raw

angular2-hotkeys

Angular 16 and Ivy Compatible. Older versions might work but isn't officially tested.

Versions compatibility

v2.4.0 - Angular 11 (most likely lower Angular versions)

v13.. - Angular 13 (most likely Angular 12)

v15.. - Angular 15

v16.. - Angular 16

Installation

To install this library, run:

$ npm install angular2-hotkeys --save

Examples

First, import the HotkeyModule into your root AppModule

import {HotkeyModule} from 'angular2-hotkeys';

Then, add HotkeyModule.forRoot() to your AppModule's import array

@NgModule({
    imports : [CommonModule, HotkeyModule.forRoot(), ...],
})
export class AppModule {}

If you have any sub/feature modules that also use hotkeys, import the HotkeyModule (but NOT .forRoot())

@NgModule({
    imports : [CommonModule, HotkeyModule, ...],
})
export class SharedModule {}

Then inject the service into your constructor and add a new hotkey

constructor(private _hotkeysService: HotkeysService) {
    this._hotkeysService.add(new Hotkey('meta+shift+g', (event: KeyboardEvent): boolean => {
        console.log('Typed hotkey');
        return false; // Prevent bubbling
    }));
}

It also handles passing an array of hotkey combinations for a single callback

this._hotkeysService.add(new Hotkey(['meta+shift+g', 'alt+shift+s'], (event: KeyboardEvent, combo: string): ExtendedKeyboardEvent => {
    console.log('Combo: ' + combo); // 'Combo: meta+shift+g' or 'Combo: alt+shift+s'
    let e: ExtendedKeyboardEvent = event;
    e.returnValue = false; // Prevent bubbling
    return e;
}));

Your callback must return either a boolean or an "ExtendedKeyboardEvent".

For more information on what hotkeys can be used, check out https://craig.is/killing/mice

This library is a work in progress and any issues/pull-requests are welcomed! Based off of the angular-hotkeys library

Cheat Sheet

To enable the cheat sheet, simply add <hotkeys-cheatsheet></hotkeys-cheatsheet> to your top level component template. The HotkeysService will automatically register the ? key combo to toggle the cheat sheet.

NB! Only hotkeys that have a description will apear on the cheat sheet. The Hotkey constructor takes a description as an optional fourth parameter as a string or optionally as a function for dynamic descriptions.

this._hotkeysService.add(new Hotkey('meta+shift+g', (event: KeyboardEvent): boolean => {
    console.log('Secret message');
    return false;
}, undefined, 'Send a secret message to the console.'));

The third parameter, given as undefined, can be used to allow the Hotkey to fire in INPUT, SELECT or TEXTAREA tags.

Cheat Sheet Customization

  1. You can now pass in custom options in HotkeyModule.forRoot(options: IHotkeyOptions).
export interface IHotkeyOptions {
  /**
   * Disable the cheat sheet popover dialog? Default: false
   */
  disableCheatSheet?: boolean;
  /**
   * Key combination to trigger the cheat sheet. Default: '?'
   */
  cheatSheetHotkey?: string;
  /**
   * Use also ESC for closing the cheat sheet. Default: false
   */
  cheatSheetCloseEsc?: boolean;
  /**
   * Description for the ESC key for closing the cheat sheet (if enabed). Default: 'Hide this help menu'
   */
  cheatSheetCloseEscDescription?: string;
  /**
   * Description for the cheat sheet hot key in the cheat sheet. Default: 'Show / hide this help menu'
   */
  cheatSheetDescription?: string;
};
  1. You can also customize the title of the cheat sheet component.
<hotkeys-cheatsheet title="Hotkeys Rock!"></hotkeys-cheatsheet>
<!-- Default: 'Keyboard Shortcuts:' -->

TODO

  1. Create unit and E2E tests

Development

To generate all * }.js, *.js.map and *.d.ts files:

$ npm run tsc

License

MIT © Nick Richardson