mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-26 13:19:34 +07:00
163 lines
4.9 KiB
Plaintext
163 lines
4.9 KiB
Plaintext
---
|
||
alwaysApply: false
|
||
---
|
||
|
||
# 如何添加新的快捷键：开发者指南
|
||
|
||
本指南将带您一步步地向 LobeChat 添加一个新的快捷键功能。我们将通过一个完整示例，演示从定义到实现的整个过程。
|
||
|
||
## 示例场景
|
||
|
||
假设我们要添加一个新的快捷键功能：**快速清空聊天记录**，快捷键为 `Mod+Shift+Backspace`。
|
||
|
||
## 步骤 1：更新快捷键常量定义
|
||
|
||
首先，在 `src/types/hotkey.ts` 中更新 `HotkeyEnum`：
|
||
|
||
```typescript
|
||
export const HotkeyEnum = {
|
||
// 已有的快捷键...
|
||
AddUserMessage: 'addUserMessage',
|
||
EditMessage: 'editMessage',
|
||
|
||
// 新增快捷键
|
||
ClearChat: 'clearChat', // 添加这一行
|
||
|
||
// 其他已有快捷键...
|
||
} as const;
|
||
```
|
||
|
||
## 步骤 2：注册默认快捷键
|
||
|
||
在 `src/const/hotkeys.ts` 中添加快捷键的默认配置：
|
||
|
||
```typescript
|
||
import { KeyMapEnum as Key, combineKeys } from '@lobehub/ui';
|
||
|
||
// ...现有代码
|
||
|
||
export const HOTKEYS_REGISTRATION: HotkeyRegistration = [
|
||
// 现有的快捷键配置...
|
||
|
||
// 添加新的快捷键配置
|
||
{
|
||
group: HotkeyGroupEnum.Conversation, // 归类到会话操作组
|
||
id: HotkeyEnum.ClearChat,
|
||
keys: combineKeys([Key.Mod, Key.Shift, Key.Backspace]),
|
||
scopes: [HotkeyScopeEnum.Chat], // 在聊天作用域下生效
|
||
},
|
||
|
||
// 其他现有快捷键...
|
||
];
|
||
```
|
||
|
||
## 步骤 3：添加国际化翻译
|
||
|
||
在 `src/locales/default/hotkey.ts` 中添加对应的文本描述：
|
||
|
||
```typescript
|
||
import { HotkeyI18nTranslations } from '@/types/hotkey';
|
||
|
||
const hotkey: HotkeyI18nTranslations = {
|
||
// 现有翻译...
|
||
|
||
// 添加新快捷键的翻译
|
||
clearChat: {
|
||
desc: '清空当前会话的所有消息记录',
|
||
title: '清空聊天记录',
|
||
},
|
||
|
||
// 其他现有翻译...
|
||
};
|
||
|
||
export default hotkey;
|
||
```
|
||
|
||
如需支持其他语言，还需要在相应的语言文件中添加对应翻译。
|
||
|
||
## 步骤 4：创建并注册快捷键 Hook
|
||
|
||
在 `src/hooks/useHotkeys/chatScope.ts` 中添加新的 Hook：
|
||
|
||
```typescript
|
||
export const useClearChatHotkey = () => {
|
||
const clearMessages = useChatStore((s) => s.clearMessages);
|
||
const { t } = useTranslation();
|
||
|
||
return useHotkeyById(HotkeyEnum.ClearChat, showConfirm);
|
||
};
|
||
|
||
// 注册聚合
|
||
|
||
export const useRegisterChatHotkeys = () => {
|
||
const { enableScope, disableScope } = useHotkeysContext();
|
||
|
||
useOpenChatSettingsHotkey();
|
||
// ...其他快捷键
|
||
useClearChatHotkey();
|
||
|
||
useEffect(() => {
|
||
enableScope(HotkeyScopeEnum.Chat);
|
||
return () => disableScope(HotkeyScopeEnum.Chat);
|
||
}, []);
|
||
|
||
return null;
|
||
};
|
||
```
|
||
|
||
## 步骤 5：给相应 UI 元素添加 Tooltip 提示（可选）
|
||
|
||
如果有对应的 UI 按钮，可以添加快捷键提示：
|
||
|
||
```tsx
|
||
import { DeleteOutlined } from '@ant-design/icons';
|
||
import { Tooltip } from '@lobehub/ui';
|
||
import { Button } from 'antd';
|
||
import { useTranslation } from 'react-i18next';
|
||
|
||
import { useUserStore } from '@/store/user';
|
||
import { settingsSelectors } from '@/store/user/selectors';
|
||
import { HotkeyEnum } from '@/types/hotkey';
|
||
|
||
const ClearChatButton = () => {
|
||
const { t } = useTranslation(['hotkey', 'chat']);
|
||
const clearChatHotkey = useUserStore(settingsSelectors.getHotkeyById(HotkeyEnum.ClearChat));
|
||
|
||
// 获取清空聊天的方法
|
||
const clearMessages = useChatStore((s) => s.clearMessages);
|
||
|
||
return (
|
||
<Tooltip hotkey={clearChatHotkey} title={t('clearChat.title', { ns: 'hotkey' })}>
|
||
<Button icon={<DeleteOutlined />} onClick={clearMessages} />
|
||
</Tooltip>
|
||
);
|
||
};
|
||
```
|
||
|
||
## 步骤 6：测试新快捷键
|
||
|
||
1. 启动开发服务器
|
||
2. 打开聊天页面
|
||
3. 按下设置的快捷键组合（`Cmd+Shift+Backspace` 或 `Ctrl+Shift+Backspace`）
|
||
4. 确认功能正常工作
|
||
5. 检查快捷键设置面板中是否正确显示了新快捷键
|
||
|
||
## 最佳实践
|
||
|
||
1. **作用域考虑**：根据功能决定快捷键应属于全局作用域还是聊天作用域
|
||
2. **分组合理**：将快捷键放在合适的功能组中（System/Layout/Conversation）
|
||
3. **冲突检查**：确保新快捷键不会与现有系统、浏览器或应用快捷键冲突
|
||
4. **平台适配**：使用 `Key.Mod` 而非硬编码 `Ctrl` 或 `Cmd`，以适配不同平台
|
||
5. **提供清晰描述**：为快捷键添加明确的标题和描述，帮助用户理解功能
|
||
|
||
按照以上步骤，您可以轻松地向系统添加新的快捷键功能，提升用户体验。如有特殊需求，如桌面专属快捷键，可以通过 `isDesktop` 标记进行区分处理。
|
||
|
||
## 常见问题排查
|
||
|
||
- **快捷键未生效**：检查作用域是否正确，以及是否在 RegisterHotkeys 中调用了对应的 hook
|
||
- **快捷键设置面板未显示**：确认在 HOTKEYS_REGISTRATION 中正确配置了快捷键
|
||
- **快捷键冲突**：在 HotkeyInput 组件中可以检测到冲突，用户会看到警告
|
||
- **功能在某些页面失效**：确认是否注册在了正确的作用域，以及相关页面是否激活了该作用域
|
||
|
||
通过这些步骤，您可以确保新添加的快捷键功能稳定、可靠且用户友好。
|