Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feat: new hot key params #2603

Open
wants to merge 2 commits into
base: release
Choose a base branch
from
Open

Feat: new hot key params #2603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9f10862
feat: implement children and listenerOptions for hotkey
Dec 2, 2024
14bd943
docs: update Hotkeys API docs
Dec 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 93 additions & 10 deletions content/plus/hotkeys/index-en-US.md
View file
Open in desktop
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
Open in desktop
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
22 changes: 21 additions & 1 deletion packages/semi-ui/hotKeys/_story/hotKeys.stories.jsx
View file
Open in desktop
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
Loading
Loading