@wordpress/keycodes
Version:
Keycodes utilities for WordPress. Used to check for keyboard events across browsers/operating systems.
220 lines (126 loc) • 4.06 kB
Markdown
Keycodes
Keycodes utilities for WordPress, used to check the key pressed in events like `onKeyDown`. Contains keycodes constants for keyboard keys like `DOWN`, `UP`, `ENTER`, etc.
# Installation
Install the module
```bash
npm install @wordpress/keycodes --save
```
_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._
# Usage
Check which key was used in an `onKeyDown` event:
```js
import { DOWN, ENTER } from '@wordpress/keycodes';
// [...]
onKeyDown( event ) {
const { keyCode } = event;
if ( keyCode === DOWN ) {
alert( 'You pressed the down arrow!' );
} else if ( keyCode === ENTER ) {
alert( 'You pressed the enter key!' );
} else {
alert( 'You pressed another key.' );
}
}
```
# API
<!-- START TOKEN(Autogenerated API docs) -->
## ALT
Keycode for ALT key.
## BACKSPACE
Keycode for BACKSPACE key.
## COMMAND
Keycode for COMMAND/META key.
## CTRL
Keycode for CTRL key.
## DELETE
Keycode for DELETE key.
## displayShortcut
An object that contains functions to display shortcuts.
_Usage_
```js
// Assuming macOS:
displayShortcut.primary( 'm' );
// "⌘M"
```
Keyed map of functions to display shortcuts.
## displayShortcutList
Return an array of the parts of a keyboard shortcut chord for display.
_Usage_
```js
// Assuming macOS:
displayShortcutList.primary( 'm' );
// [ "⌘", "M" ]
```
Keyed map of functions to shortcut sequences.
## DOWN
Keycode for DOWN key.
## END
Keycode for END key.
## ENTER
Keycode for ENTER key.
## ESCAPE
Keycode for ESCAPE key.
## F10
Keycode for F10 key.
## HOME
Keycode for HOME key.
## isAppleOS
Return true if platform is MacOS.
_Parameters_
- _\_window_ `Window`: window object by default; used for DI testing.
_Returns_
- `boolean`: True if MacOS; false otherwise.
## isKeyboardEvent
An object that contains functions to check if a keyboard event matches a predefined shortcut combination.
_Usage_
```js
// Assuming an event for ⌘M key press:
isKeyboardEvent.primary( event, 'm' );
// true
```
Keyed map of functions to match events.
## LEFT
Keycode for LEFT key.
## modifiers
Object that contains functions that return the available modifier depending on platform.
_Type_
- `WPModifierHandler< WPModifier >`
## PAGEDOWN
Keycode for PAGEDOWN key.
## PAGEUP
Keycode for PAGEUP key.
## rawShortcut
An object that contains functions to get raw shortcuts.
These are intended for user with the KeyboardShortcuts.
_Usage_
```js
// Assuming macOS:
rawShortcut.primary( 'm' );
// "meta+m""
```
## RIGHT
Keycode for RIGHT key.
## SHIFT
Keycode for SHIFT key.
## shortcutAriaLabel
An object that contains functions to return an aria label for a keyboard shortcut.
_Usage_
```js
// Assuming macOS:
shortcutAriaLabel.primary( '.' );
// "Command + Period"
```
Keyed map of functions to shortcut ARIA labels.
## SPACE
Keycode for SPACE key.
## TAB
Keycode for TAB key.
## UP
Keycode for UP key.
## ZERO
Keycode for ZERO key.
<!-- END TOKEN(Autogenerated API docs) -->
# Contributing to this package
This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>