@douyinfe/semi-ui
Version:
A modern, comprehensive, flexible design system and UI library. Connect DesignOps & DevOps. Quickly build beautiful React apps. Maintained by Douyin-fe team.
253 lines (211 loc) • 7.97 kB
Markdown
---
localeCode: en-US
order: 33
category: Plus
title: HotKeys
icon: doc-configprovider
width: 60%
brief: used to facilitate the customization of keyboard shortcut
---
## When to use
When it is necessary to express the usage method of shortcut key combinations to users, using the `Hotkeys` component can quickly render the corresponding UI elements and automatically obtain event bindings.
## Demos
### How to import
PinCode supported from 2.66.0
```jsx import
import { HotKeys } from '@douyinfe/semi-ui';
```
### Explaination
The hotkeys only support combinations of modifier keys like Shift, Control, Meta, and Alt with other keys.
> [Meta](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/metaKey) corresponds to Command on macOS and Win on Windows.
When setting a shortcut that overlaps with common shortcuts like Ctrl/Meta + C, the preventDefault setting can be used to control whether the default event is triggered.
### Basic Usage
Pass in key combinations via `hotKeys` and bind a shortcut handler function using `onHotKey` to respond to the action.
When pressing `Ctrl + Shift + A`, it opens the modal. By default, it listens on the body, making it effective globally.
[values reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)
It's also recommended to use the `HotKeys.Keys` wrapper to set hotkeys.
```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal } from '@douyinfe/semi-ui';
function Demo() {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
const handleOk = () => {
setVisible(false);
};
const handleCancel = () => {
setVisible(false);
};
const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.A]
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} ></HotKeys>
<Modal
title="Dialog"
visible={visible}
onOk={handleOk}
onCancel={handleCancel}
>
This is the Modal opened by hotkey: {hotKeys.join('+')}.
</Modal>
</div>
);
}
```
### Custom content
Set the characters through `content`
```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal } from '@douyinfe/semi-ui';
function Demo() {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
const handleOk = () => {
setVisible(false);
};
const handleCancel = () => {
setVisible(false);
};
const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.B]
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} content={['Ctrl', 'Shift', 'B']}></HotKeys>
<Modal
title="Dialog"
visible={visible}
onOk={handleOk}
onCancel={handleCancel}
>
This is the Modal opened by hotkey: {hotKeys.join('+')}.
</Modal>
</div>
);
}
```
Replace the element through `render`
```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal, Tag } from '@douyinfe/semi-ui';
function Demo() {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
const handleOk = () => {
setVisible(false);
};
const handleCancel = () => {
setVisible(false);
};
const hotKeys = [HotKeys.Keys.Control, HotKeys.Keys.R]
const newHotKeys = <Tag>Press Ctrl+R to Open Modal</Tag>
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} render={newHotKeys}></HotKeys>
<Modal
title="Dialog"
visible={visible}
onOk={handleOk}
onCancel={handleCancel}
>
This is the Modal opened by hotkey: {hotKeys.join('+')}.
</Modal>
</div>
);
}
```
### prevent Default event
Control the default event by setting `preventDefault`.
```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal } from '@douyinfe/semi-ui';
function Demo() {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
const handleOk = () => {
setVisible(false);
};
const handleCancel = () => {
setVisible(false);
};
const hotKeys = [HotKeys.Keys.Meta, HotKeys.Keys.S]
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} preventDefault></HotKeys>
<br />
<HotKeys hotKeys={[HotKeys.Keys.Control, HotKeys.Keys.S]} onHotKey={showDialog} preventDefault></HotKeys>
<Modal
title="Dialog"
visible={visible}
onOk={handleOk}
onCancel={handleCancel}
>
This is the Modal opened by hotkey: {'Meta/Control + S'}.
</Modal>
</div>
);
}
```
### change the DOM element the listener is mounted on
The hotkey is listened to on the body by default, through `getListenerTarget`
```jsx live=true
import React, { useState, useRef } from 'react';
import { HotKeys, Input, Modal } from '@douyinfe/semi-ui';
function Demo() {
const hotKeys = ["Control", "q"]
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
const handleOk = () => {
setVisible(false);
};
const handleCancel = () => {
setVisible(false);
};
const inputRef = useRef(null);
return (
<div>
<Input ref={inputRef} placeholder='test for target'></Input>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog}
getListenerTarget={() => inputRef.current}>
</HotKeys>
<Modal
title="Dialog"
visible={visible}
onOk={handleOk}
onCancel={handleCancel}
>
This is the Modal opened by hotkey: {hotKeys.join('+')}.
</Modal>
</div>
);
}
```
## API Reference
### HotKeys
| Property | Instructions | type | Default |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|-----------|
| className | class name | string | |
| content | Set the characters | string[] | - |
| getListenerTarget | change the DOM element the listener is mounted on | () => HTMLElement | document.body |
| hotKeys | Define keyboard shortcut，[values](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) | KeyboardEvent.key[] | - |
| onClick | callback that clicking triggers | () => void | - |
| onHotKey | callback that hotKeys triggers | (e: KeyboardEvent) => void | - |
| preventDefault | Whether to prevent the default behavior of the shortcut | boolean | false |
| render | Replace the element | () => ReactNode \| ReactNode | |
| style | style | CSSProperties | |
## Design Tokens
<DesignToken/>
<!-- ## Related Material
```material
44, 46
``` -->
## Related Material
<semi-material-list code="46"></semi-material-list>