Skip to content

Commit

Permalink
docs: update Hotkeys API docs
Browse files Browse the repository at this point in the history
  • Loading branch information
yanzhuoran committed Dec 2, 2024
1 parent 9f10862 commit 14bd943
Show file tree
Hide file tree
Showing 4 changed files with 215 additions and 31 deletions.
103 changes: 93 additions & 10 deletions content/plus/hotkeys/index-en-US.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ PinCode supported from 2.66.0
import { HotKeys } from '@douyinfe/semi-ui';
```

### Explaination
### Explanation
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.
Expand Down Expand Up @@ -75,12 +75,47 @@ function Demo() {
```

### Custom content
Priority order is: `children` > `render` > `content`

Set the characters through `content`
Replace the element through `render` or `children`

```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal } from '@douyinfe/semi-ui';
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.T];

const newHotKeys = <Tag>Press Ctrl+T to Open Modal</Tag>;
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog}>{newHotKeys}</HotKeys>
<Modal
title="Dialog"
visible={visible}
onOk={handleOk}
onCancel={handleCancel}
>
This is the Modal opened by hotkey: {hotKeys.join('+')}.
</Modal>
</div>
);
}
```

```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal, Tag } from '@douyinfe/semi-ui';

function Demo() {
const [visible, setVisible] = useState(false);
Expand All @@ -93,11 +128,12 @@ function Demo() {
const handleCancel = () => {
setVisible(false);
};
const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.B]
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} content={['Ctrl', 'Shift', 'B']}></HotKeys>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} render={newHotKeys}></HotKeys>
<Modal
title="Dialog"
visible={visible}
Expand All @@ -111,11 +147,12 @@ function Demo() {
}
```

Replace the element through `render`

Set the characters through `content`

```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal, Tag } from '@douyinfe/semi-ui';
import { HotKeys, Modal } from '@douyinfe/semi-ui';

function Demo() {
const [visible, setVisible] = useState(false);
Expand All @@ -128,12 +165,11 @@ function Demo() {
const handleCancel = () => {
setVisible(false);
};
const hotKeys = [HotKeys.Keys.Control, HotKeys.Keys.R]
const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.B]

const newHotKeys = <Tag>Press Ctrl+R to Open Modal</Tag>
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} render={newHotKeys}></HotKeys>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} content={['Ctrl', 'Shift', 'B']}></HotKeys>
<Modal
title="Dialog"
visible={visible}
Expand Down Expand Up @@ -224,6 +260,51 @@ function Demo() {
}
```

### change the shortcut listener options
using `listenerOptions` to change the shortcut listener options
```jsx live=true
import React, { useState, useRef } from 'react';
import { HotKeys, Input, Modal } from '@douyinfe/semi-ui';

function Demo() {
const hotKeys = ["m"];
const [visible, setVisible] = useState(false);
const [triggered, setTriggered] = useState(false);
const showDialog = () => {
setVisible(true);
setTriggered(true);
};
const handleOk = () => {
setVisible(false);
};
const handleCancel = () => {
setVisible(false);
};

const options = {
once: true,
}
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} listenerOptions={options}>
</HotKeys>
<br/>
<span>
{triggered? 'triggered' : 'not triggered'}
</span>
<Modal
title="Dialog"
visible={visible}
onOk={handleOk}
onCancel={handleCancel}
>
This is the Modal opened by hotkey: {hotKeys.join('+')}.
</Modal>
</div>
);
}
```

## API Reference

### HotKeys
Expand All @@ -233,8 +314,10 @@ function Demo() {
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|-----------|
| className | class name | string | |
| content | Set the characters | string[] | - |
| children | Replace the element | ReactNode | - |
| 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[] | - |
| listenerOptions | [reference](https://developer.mozilla.org/zh-CN/docs/Web/API/EventTarget/addEventListener#options) | AddEventListenerOptions | - |
| 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 |
Expand Down
117 changes: 99 additions & 18 deletions content/plus/hotkeys/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,12 +71,12 @@ function Demo() {
```

### 自定义内容

通过`content`传入渲染的字符
优先级顺序为：`children` > `render` > `content`
通过`render`或`children`代替渲染的元素

```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal } from '@douyinfe/semi-ui';
import { HotKeys, Modal, Tag } from '@douyinfe/semi-ui';

function Demo() {
const [visible, setVisible] = useState(false);
Expand All @@ -89,11 +89,12 @@ function Demo() {
const handleCancel = () => {
setVisible(false);
};
const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.B];
const hotKeys = [HotKeys.Keys.Control, HotKeys.Keys.T];

const newHotKeys = <Tag>Press Ctrl+T to Open Modal</Tag>;
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} content={['Ctrl', 'Shift', 'B']}></HotKeys>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog}>{newHotKeys}</HotKeys>
<Modal
title="Dialog"
visible={visible}
Expand All @@ -107,8 +108,6 @@ function Demo() {
}
```

通过`render`传入代替渲染的元素

```jsx live=true
import React, { useState } from 'react';
import { HotKeys, Modal, Tag } from '@douyinfe/semi-ui';
Expand Down Expand Up @@ -143,6 +142,41 @@ function Demo() {
}
```

通过`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>
);
}
```

### 阻止默认事件

通过设置`preventDefault`控制默认事件是否触发。
Expand Down Expand Up @@ -220,21 +254,68 @@ function Demo() {
}
```

### 修改监听器参数
通过`listenerOptions`修改快捷键监听器的参数
```jsx live=true
import React, { useState, useRef } from 'react';
import { HotKeys, Input, Modal } from '@douyinfe/semi-ui';

function Demo() {
const hotKeys = ["m"];
const [visible, setVisible] = useState(false);
const [triggered, setTriggered] = useState(false);
const showDialog = () => {
setVisible(true);
setTriggered(true);
};
const handleOk = () => {
setVisible(false);
};
const handleCancel = () => {
setVisible(false);
};

const options = {
once: true,
}
return (
<div>
<HotKeys hotKeys={hotKeys} onHotKey={showDialog} listenerOptions={options}>
</HotKeys>
<br/>
<span>
{triggered? '已触发' : '未触发'}
</span>
<Modal
title="Dialog"
visible={visible}
onOk={handleOk}
onCancel={handleCancel}
>
This is the Modal opened by hotkey: {hotKeys.join('+')}.
</Modal>
</div>
);
}
```

## API 参考

### HotKeys

| 属性 | 说明 | 类型 | 默认值 |
| ----------------- | --------------------------------------------------------------------- | ------------------------------- | --------- |
| className | 类名 | string | |
| content | 设置显示内容 | string[] | - |
| getListenerTarget | 用于设置监听器挂载的DOM | () => HTMLElement | document.body |
| hotKeys | 设置快捷键组合，[取值参考](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) | KeyboardEvent.key[] | - |
| onClick | 点击回调函数 | () => void | - |
| onHotKey | 快捷键回调函数 | (e: KeyboardEvent) => void | - |
| preventDefault | 是否阻止快捷键默认行为 | boolean | false |
| render | 覆盖组件渲染 | () => ReactNode \| ReactNode | |
| style | 样式 | CSSProperties | |
| 属性 | 说明 | 类型 | 默认值 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------- |
| className | 类名 | string | |
| content | 设置显示内容 | string[] | - |
| children | 覆盖组件默认渲染 | ReactNode | |
| getListenerTarget | 用于设置监听器挂载的DOM | () => HTMLElement | document.body |
| hotKeys | 设置快捷键组合，[取值参考](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) | KeyboardEvent.key[] | - |
| listenerOptions | [参考](https://developer.mozilla.org/zh-CN/docs/Web/API/EventTarget/addEventListener#options) | AddEventListenerOptions | - |
| onClick | 点击回调函数 | () => void | - |
| onHotKey | 快捷键回调函数 | (e: KeyboardEvent) => void | - |
| preventDefault | 是否阻止快捷键默认行为 | boolean | false |
| render | 覆盖组件渲染 | () => ReactNode \| ReactNode | |
| style | 样式 | CSSProperties | |


## 设计变量
Expand Down
4 changes: 2 additions & 2 deletions packages/semi-ui/hotKeys/_story/hotKeys.stories.jsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,13 +94,13 @@ export const target = () => {
}

export const listenerOptions = () => {
const hotKeys = [HotKeys.Keys.A]
const hotKeys = ['Shift', HotKeys.Keys.A]
const [cnt, setCnt] = useState(0)
const onHotKey = () => {
setCnt(cnt+1)
}
const options = {
once: true,
passive: true,
}

return (
Expand Down
22 changes: 21 additions & 1 deletion packages/semi-ui/hotKeys/_story/hotKeys.stories.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ export const renderButton = () => {
<div>
<pre id='pre'>{" cnt:" + cnt}</pre>
<HotKeys hotKeys={hotKeys} onHotKey={onHotKey} render={button}></HotKeys>
<HotKeys hotKeys={hotKeys} onHotKey={onHotKey}>{button()}</HotKeys>
</div>

);
Expand Down Expand Up @@ -86,7 +87,26 @@ export const target = () => {
<div>
{target}
<pre id='pre'>{cnt}</pre>
<HotKeys hotKeys={hotKeys} onHotKey={onHotKey} getListenerTarget={() => document.getElementById("test")}></HotKeys>
<HotKeys hotKeys={hotKeys} preventDefault onHotKey={onHotKey} getListenerTarget={() => document.getElementById("test")}></HotKeys>
</div>

);
}

export const listenerOptions = () => {
const hotKeys = ['Shift', HotKeys.Keys.A]
const [cnt, setCnt] = useState(0)
const onHotKey = () => {
setCnt(cnt+1)
}
const options = {
passive: true,
}

return (
<div>
<pre id='pre'>{cnt}</pre>
<HotKeys hotKeys={hotKeys} onHotKey={onHotKey} listenerOptions={options} preventDefault></HotKeys>
</div>

);
Expand Down

0 comments on commit 14bd943

Please sign in to comment.