1 | ---
|
2 | tag: new
|
3 | ---
|
4 |
|
5 | @# HotkeysTarget2
|
6 |
|
7 | <div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
|
8 | <h4 class="@ns-heading">This API requires React 16.8+</h4>
|
9 | </div>
|
10 |
|
11 | <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
|
12 | <h4 class="@ns-heading">
|
13 |
|
14 | Migrating from [HotkeysTarget](#core/components/hotkeys)?
|
15 |
|
16 | </h4>
|
17 |
|
18 | HotkeysTarget2 is a replacement for HotkeysTarget. You are encouraged to use this new API, or
|
19 | the `useHotkeys` hook directly in your function components, as they will become the standard
|
20 | APIs in Blueprint v4. See the full
|
21 | [migration guide](https://github.com/palantir/blueprint/wiki/HotkeysTarget-&-useHotkeys-migration) on the wiki.
|
22 |
|
23 | </div>
|
24 |
|
25 |
|
26 | The `HotkeysTarget2` component is a utility component which allows you to use the new
|
27 | [`useHotkeys` hook](#core/hooks/use-hotkeys) inside a React component class. It's useful
|
28 | if you want to switch to the new hotkeys API without refactoring your class components
|
29 | into functional components.
|
30 |
|
31 | Focus on the piano below to try its hotkeys. The global hotkeys dialog can be shown using the "?" key.
|
32 |
|
33 | @reactExample HotkeysTarget2Example
|
34 |
|
35 | @## Usage
|
36 |
|
37 | First, make sure [HotkeysProvider](#core/context/hotkeys-provider) is configured correctly at the root of your
|
38 | React application.
|
39 |
|
40 | Then, to register hotkeys and generate the relevant event handlers, use the component like so:
|
41 |
|
42 | ```tsx
|
43 | import React from "react";
|
44 | import { HotkeysTarget2, InputGroup } from "@blueprintjs/core";
|
45 |
|
46 | export default class extends React.PureComponent {
|
47 | private inputEl: HTMLInputElement | null = null;
|
48 | private handleInputRef = (el: HTMLInputElement) => (this.inputEl = el);
|
49 |
|
50 | private hotkeys = [
|
51 | {
|
52 | combo: "R",
|
53 | global: true,
|
54 | label: "Refresh data",
|
55 | onKeyDown: () => console.info("Refreshing data..."),
|
56 | },
|
57 | {
|
58 | combo: "F",
|
59 | group: "Input",
|
60 | label: "Focus text input",
|
61 | onKeyDown: this.inputEl?.focus(),
|
62 | },
|
63 | ];
|
64 |
|
65 | public render() {
|
66 | return (
|
67 | <HotkeysTarget2 hotkeys={this.hotkeys}>
|
68 | {({ handleKeyDown, handleKeyUp }) => (
|
69 | <div tabIndex={0} onKeyDown={handleKeyDown} onKeyUp={handleKeyUp}>
|
70 | Press "R" to refresh data, "F" to focus the input...
|
71 | <InputGroup ref={this.handleInputRef} />
|
72 | </div>
|
73 | )}
|
74 | </HotkeysTarget2>
|
75 | )
|
76 | }
|
77 | }
|
78 | ```
|
79 |
|
80 | Hotkeys must define a group, or be marked as global. The component will automatically bind global event handlers
|
81 | and configure the <kbd>?</kbd> key to open the generated hotkeys dialog, but it is up to you to bind _local_
|
82 | event handlers with the `handleKeyDown` and `handleKeyUp` functions in the child render function. Note that
|
83 | you will likely have to set a non-negative `tabIndex` on the DOM node to which these local event handlers are
|
84 | bound for them to work correctly.
|
85 |
|
86 | `<HotkeysTarget2>` takes an optional `options: UseHotkeysOptions` prop which can customize some of the hook's
|
87 | default behavior.
|
88 |
|
89 | @## Props
|
90 |
|
91 | @interface HotkeysTarget2Props
|
92 |
|
93 | @interface HotkeyConfig
|
94 |
|
95 | @interface UseHotkeysOptions
|