hotkey

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Adding Keyboard Shortcuts Guide

添加键盘快捷键指南

Steps to Add a New Hotkey

添加新热键的步骤

1. Update Hotkey Constant

1. 更新热键常量

src/types/hotkey.ts

typescript

export const HotkeyEnum = {
  // existing...
  ClearChat: 'clearChat', // Add new
} as const;

在

src/types/hotkey.ts

文件中：

typescript

export const HotkeyEnum = {
  // existing...
  ClearChat: 'clearChat', // Add new
} as const;

2. Register Default Hotkey

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],
  },
];

在

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. Add i18n Translation

3. 添加国际化翻译

src/locales/default/hotkey.ts

typescript

const hotkey: HotkeyI18nTranslations = {
  clearChat: {
    desc: '清空当前会话的所有消息记录',
    title: '清空聊天记录',
  },
};

在

src/locales/default/hotkey.ts

文件中：

typescript

const hotkey: HotkeyI18nTranslations = {
  clearChat: {
    desc: '清空当前会话的所有消息记录',
    title: '清空聊天记录',
  },
};

4. Create and Register Hook

4. 创建并注册Hook

src/hooks/useHotkeys/chatScope.ts

typescript

export const useClearChatHotkey = () => {
  const clearMessages = useChatStore((s) => s.clearMessages);
  return useHotkeyById(HotkeyEnum.ClearChat, clearMessages);
};

export const useRegisterChatHotkeys = () => {
  useClearChatHotkey();
  // ...other hotkeys
};

在

src/hooks/useHotkeys/chatScope.ts

文件中：

typescript

export const useClearChatHotkey = () => {
  const clearMessages = useChatStore((s) => s.clearMessages);
  return useHotkeyById(HotkeyEnum.ClearChat, clearMessages);
};

export const useRegisterChatHotkeys = () => {
  useClearChatHotkey();
  // ...other hotkeys
};

5. Add Tooltip (Optional)

5. 添加提示框（可选）

tsx

const clearChatHotkey = useUserStore(settingsSelectors.getHotkeyById(HotkeyEnum.ClearChat));

<Tooltip hotkey={clearChatHotkey} title={t('clearChat.title', { ns: 'hotkey' })}>
  <Button icon={<DeleteOutlined />} onClick={clearMessages} />
</Tooltip>

tsx

const clearChatHotkey = useUserStore(settingsSelectors.getHotkeyById(HotkeyEnum.ClearChat));

<Tooltip hotkey={clearChatHotkey} title={t('clearChat.title', { ns: 'hotkey' })}>
  <Button icon={<DeleteOutlined />} onClick={clearMessages} />
</Tooltip>

Best Practices

最佳实践

Scope: Choose global or chat scope based on functionality
Grouping: Place in appropriate group (System/Layout/Conversation)
Conflict check: Ensure no conflict with system/browser shortcuts
Platform: Use
```
Key.Mod
```
instead of hardcoded
```
Ctrl
```
or
```
Cmd
```
Clear description: Provide title and description for users

作用域：根据功能选择全局或聊天作用域
分组：将热键放入合适的分组（系统/布局/会话）
冲突检查：确保与系统/浏览器快捷键无冲突
平台适配：使用
```
Key.Mod
```
而非硬编码的
```
Ctrl
```
或
```
Cmd
```
清晰描述：为用户提供标题和描述信息

Troubleshooting

故障排查

Not working: Check scope and RegisterHotkeys hook
Not in settings: Verify HOTKEYS_REGISTRATION config
Conflict: HotkeyInput component shows warnings
Page-specific: Ensure correct scope activation

无法生效：检查作用域和RegisterHotkeys钩子
未显示在设置中：验证HOTKEYS_REGISTRATION配置
冲突问题：HotkeyInput组件会显示警告信息
页面特定：确保激活了正确的作用域