[RFC] 100 - Hotkey setting panel 快捷键设置面板 #7111

canisminor1990 · 2025-03-23T11:21:07Z

canisminor1990
Mar 23, 2025
Maintainer

背景

一方面解决目前快捷键过于隐晦，没有统一入口查看支持哪些快捷键，另一方面支持自定义配置解决个性化快捷键诉求。同时，Windows 和 Mac 用户习惯的快捷键表示和组合方式存在差异，需要提供平台适配的解决方案。

本特性旨在构建一个直观、功能完善的快捷键设置面板，让用户可以查看和自定义应用快捷键，同时确保设置的快捷键不会与系统或浏览器快捷键冲突，从而提供一致且用户友好的体验。

设计思路

快捷键系统的设计围绕以下几个核心原则展开：

平台适应性：使用 KeyMapEnum 与 combineKeys 实现自动识别用户操作系统（Windows/Mac），并相应调整快捷键的显示样式（例如，Windows 显示 "Ctrl+S"，Mac 显示 "⌘+S"）
作用域管理：

将快捷键划分为全局作用域（GLOBAL_HOTKEY_SCOPE）和聊天作用域（CHAT_HOTKEY_SCOPE）
基于上下文自动启用/禁用相关作用域的快捷键

分组组织：

将快捷键按照系统（System）、布局（Layout）和会话（Conversation）三大类进行组织
为每个分组下的快捷键提供清晰的描述和标题

冲突管理：

检测并防止重复的快捷键设置
部分系统级快捷键支持特定标记（如不可编辑）
提供重置选项恢复默认设置

状态持久化：

使用 UserStore 保存用户自定义的快捷键配置
在应用重启后自动恢复用户设置

架构设计

系统架构图

┌──────────────────────────────────────────────────────────────────────────────────────────┐
│                                         UI 层                                             │
│  ┌───────────────────────┐  ┌───────────────────────┐  ┌───────────────────────────┐     │
│  │     HotkeySetting     │  │    HotkeyInput        │  │      其他UI组件           │     │
│  │ (设置界面自定义快捷键) │  │ (快捷键输入与冲突检测) │  │  (展示与快捷键相关的提示) │     │
│  └───────────┬───────────┘  └───────────┬───────────┘  └───────────────────────────┘     │
└──────────────┼───────────────────────────┼─────────────────────────────────────────────────┘
               │                           │
┌──────────────▼───────────────────────────▼─────────────────────────────────────────────────┐
│                                      作用域管理层                                            │
│  ┌───────────────────────────────────────────────────────────────────────────────┐          │
│  │                              HotkeysProvider                                   │          │
│  │                     (维护全局作用域状态与作用域激活逻辑)                         │          │
│  └───────────┬───────────────────────────────────────┬─────────────────────────────┘          │
│              │                                       │                                      │
│  ┌───────────▼────────────────┐         ┌────────────▼────────────┐                         │
│  │      全局作用域注册         │         │      聊天作用域注册      │                         │
│  │  (main/_layout/.../       │         │  (chat/_layout/.../     │                         │
│  │   RegisterHotkeys.tsx)    │         │   RegisterHotkeys.tsx)  │                         │
│  └───────────┬────────────────┘         └────────────┬────────────┘                         │
└──────────────┼─────────────────────────────────────────┼────────────────────────────────────┘
               │                                         │
┌──────────────▼─────────────────────────────────────────▼────────────────────────────────────┐
│                                    快捷键定义与Hook层                                         │
│  ┌───────────────────┐ ┌───────────────────┐ ┌────────────────────┐ ┌────────────────────┐  │
│  │  useHotkeyById    │ │  globalScope.ts   │ │   chatScope.ts     │ │  const/hotkeys.ts  │  │
│  │ (通用快捷键Hook)   │ │ (全局作用域Hooks)  │ │ (聊天作用域Hooks)  │ │(快捷键常量与注册表)│  │
│  └─────────┬─────────┘ └─────────┬─────────┘ └──────────┬─────────┘ └──────────┬─────────┘  │
└────────────┼───────────────────────┼──────────────────────┼────────────────────┼─────────────┘
             │                       │                      │                    │
┌────────────▼───────────────────────▼──────────────────────▼────────────────────▼─────────────┐
│                                      类型定义层                                                │
│  ┌─────────────────────────────────────────────────────────────────────────────────────┐      │
│  │                                  types/hotkey.ts                                     │      │
│  │   * HotkeyEnum - 快捷键ID枚举                                                        │      │
│  │   * HotkeyGroupEnum - 快捷键分组枚举                                                 │      │
│  │   * HotkeyItem - 快捷键项接口                                                        │      │
│  │   * HotkeyRegistration - 快捷键注册类型                                              │      │
│  └───────────────────────────────────────┬─────────────────────────────────────────────┘      │
└───────────────────────────────────────────┼─────────────────────────────────────────────────────┘
                                           │
┌──────────────────────────────────────────▼─────────────────────────────────────────────────────┐
│                                      状态管理层                                                  │
│  ┌───────────────────────────────┐   ┌───────────────────────────────────────────────────┐      │
│  │      UserStore                │   │                 settingsSelectors                  │      │
│  │  (用户快捷键配置存储)          │   │           (快捷键配置选择器与获取逻辑)               │      │
│  │                              │   │                                                     │      │
│  │  settings: {                 │   │  * getHotkeyById - 获取特定ID的快捷键                │      │
│  │    hotkey: UserHotkeyConfig  │   │  * currentSettings - 获取当前所有设置                │      │
│  │  }                           │   │                                                     │      │
│  └─────────────────┬─────────────┘   └────────────────────────┬──────────────────────────┘      │
└─────────────────────┼─────────────────────────────────────────┼────────────────────────────────┘
                     │                                         │
┌─────────────────────▼─────────────────────────────────────────▼────────────────────────────────┐
│                                      持久化层                                                   │
│  ┌─────────────────────────────────────────────────────────────────────────────────────┐       │
│  │                           localStorage/IndexedDB                                     │       │
│  │                       (保存用户自定义快捷键配置)                                       │       │
│  └─────────────────────────────────────────────────────────────────────────────────────┘       │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

数据流程

应用启动时，从 UserStore 加载用户快捷键设置
根据当前上下文 (全局或聊天) 激活相应的快捷键作用域
用户触发快捷键时，系统查找匹配的处理函数并执行对应逻辑
用户在设置面板修改快捷键时：

检测快捷键冲突
更新 UserStore 中的配置
立即应用新的快捷键设置

快捷键 const 定义

快捷键定义 `src/const/hotkeys.ts`

import { combineKeys } from '@lobehub/ui';
import { HotkeyEnum, HotkeyGroupEnum, HotkeyRegistration } from '@/types/hotkey';

export const HOTKEYS_REGISTRATION: HotkeyRegistration = [
  {
    group: HotkeyGroupEnum.System,
    id: HotkeyEnum.Search,
    keys: combineKeys([Key.Mod, 'k']),
    scopes: [HotkeyScopeEnum.Global],
  },
  {
    group: HotkeyGroupEnum.Essential,
    id: HotkeyEnum.ToggleLeftPanel,
    keys: combineKeys([KeyEnum.Mod, KeyEnum.Alt, KeyEnum.Left]),
    scopes: [HotkeyScopeEnum.Chat],
  },
  // ... 其他快捷键定义
];

快捷键类型定义 `src/types/hotkey.ts`

import { KeyMapEnum } from '@lobehub/ui/es/Hotkey';

export const KeyEnum = {
  ...KeyMapEnum,
  Number: '1-9',
} as const;

export const HotkeyEnum = {
  AddUserMessage: 'addUserMessage',
  EditMessage: 'editMessage',
  OpenChatSettings: 'openChatSettings',
  OpenHotkeyHelper: 'openHotkeyHelper',
  RegenerateMessage: 'regenerateMessage',
  SaveTopic: 'saveTopic',
  Search: 'search',
  SwitchAgent: 'switchAgent',
  ToggleLeftPanel: 'toggleLeftPanel',
  ToggleRightPanel: 'toggleRightPanel',
  ToggleZenMode: 'toggleZenMode',
} as const;

export const HotkeyGroupEnum = {
  Conversation: 'conversation',
  Essential: 'essential',
} as const;

export const HotkeyScopeEnum = {
  Chat: 'chat',
  // 默认全局注册的快捷键 scope
  // https://react-hotkeys-hook.vercel.app/docs/documentation/hotkeys-provider
  Global: 'global',
} as const;

export type HotkeyId = (typeof HotkeyEnum)[keyof typeof HotkeyEnum];
export type HotkeyGroupId = (typeof HotkeyGroupEnum)[keyof typeof HotkeyGroupEnum];
export type HotkeyScopeId = (typeof HotkeyScopeEnum)[keyof typeof HotkeyScopeEnum];

export interface HotkeyItem {
  // 快捷键分组用于展示
  group: HotkeyGroupId;
  id: HotkeyId;
  isDesktop?: boolean;
  // 是否是桌面端专用的快捷键
  keys: string;
  // 是否为不可编辑的快捷键
  nonEditable?: boolean;
  // 快捷键作用域
  scopes?: HotkeyScopeId[];
}

export type HotkeyRegistration = HotkeyItem[];

export type HotkeyI18nTranslations = Record<
  HotkeyId,
  {
    desc?: string;
    title: string;
  }
>;

快捷键 i18n `src/locales/default/hotkey.ts`

import { HotkeyI18nTranslations } from '@/types/hotkey';

const hotkey: HotkeyI18nTranslations = {
  addUserMessage: {
    desc: '将当前输入内容添加为用户消息，但不触发生成',
    title: '添加一条用户消息',
  },
  editMessage: {
    desc: '通过按住 Alt 并双击消息进入编辑模式',
    title: '编辑消息',
  },
  openChatSettings: {
    title: '打开会话设置',
  },
  regenerateMessage: {
    desc: '重新生成最后一条消息',
    title: '重新生成消息',
  },
  saveTopic: {
    desc: '保存当前话题并打开新话题',
    title: '开启新话题',
  },
  search: {
    title: '搜索',
  },
  switchAgent: {
    desc: '通过按住 Ctrl 加数字 0~9 切换固定在侧边栏的助手',
    title: '快捷切换助手',
  },
  toggleLeftPanel: {
    title: '显示/隐藏助手面板',
  },
  toggleRightPanel: {
    title: '显示/隐藏话题面板',
  },
  toggleZenMode: {
    title: '切换专注模式',
  },
};

export default hotkey;

快捷键 Hook 示例 `src/hooks/useHotkeys/chatScope.ts`

export const useSaveTopicHotkey = () => {
  const openNewTopicOrSaveTopic = useChatStore((s) => s.openNewTopicOrSaveTopic);
  const { mutate } = useActionSWR('openNewTopicOrSaveTopic', openNewTopicOrSaveTopic);
  return useHotkeyById(HotkeyEnum.SaveTopic, () => mutate());
};

// ...

// 注册聚合

export const useRegisterChatHotkeys = () => {
  const { enableScope, disableScope } = useHotkeysContext();

  // System
  useOpenChatSettingsHotkey();

  // Layout
  useToggleLeftPanelHotkey();
  useToggleRightPanelHotkey();
  useToggleZenModeHotkey();

  // Conversation
  useRegenerateMessageHotkey();
  useSaveTopicHotkey();
  useAddUserMessageHotkey();

  useEffect(() => {
    enableScope(HotkeyScopeEnum.Chat);
    return () => disableScope(HotkeyScopeEnum.Chat);
  }, []);

  return null;
};

作用域实现机制

快捷键作用域（Scope）是整个快捷键系统的核心控制机制，它解决了"在正确的上下文中提供正确的快捷键"的问题，以下详细介绍其实现原理和流程：

作用域基本概念

作用域本质上是快捷键的分组标识符，用于控制哪些快捷键在哪些界面环境中可用。我们的系统定义了两个主要作用域：

全局作用域（GLOBAL_HOTKEY_SCOPE = 'global'）：应用全局可用的快捷键
聊天作用域（CHAT_HOTKEY_SCOPE = 'chat'）：仅在聊天界面可用的快捷键

此外，每个快捷键ID也自动成为一个独立作用域，用于精细控制单个快捷键的启用/禁用状态。

作用域注册与生命周期

应用初始化阶段：

// 在应用根组件中注册HotkeysProvider
<HotkeysProvider initiallyActiveScopes={[HotkeyScopeEnum.Global]}>
  <App />
</HotkeysProvider>

此时只有全局作用域（'global'）中的快捷键是激活状态

进入聊天页面：

// 在聊天页面组件中
const { enableScope } = useHotkeysContext();

useEffect(() => {
  // 启用聊天作用域
  enableScope(HotkeyScopeEnum.Chat);

  // 组件卸载时可以选择性地禁用（我们的实现中依赖React组件树结构，未显式禁用）
  // return () => disableScope(HotkeyScopeEnum.Chat);
}, []);

快捷键定义与作用域关联：

 export const HOTKEYS_REGISTRATION: HotkeyRegistration = [
   {
     group: HotkeyGroupEnum.Essential,
     id: HotkeyEnum.Search,
     keys: combineKeys([KeyEnum.Mod, 'k']),
 	// 定义一个全局搜索快捷键
     scopes: [HotkeyScopeEnum.Global],
   },
   {
     group: HotkeyGroupEnum.Essential,
     id: HotkeyEnum.ToggleLeftPanel,
     keys: combineKeys([KeyEnum.Mod, KeyEnum.Alt, KeyEnum.Left]),
 	// 定义一个仅在聊天界面可用的快捷键
     scopes: [HotkeyScopeEnum.Chat],
   },
   {
 	group: HotkeyGroupEnum.Conversation,
 	id: HotkeyEnum.AddUserMessage,
 	keys: combineKeys([KeyEnum.Alt, KeyEnum.Enter]),
 	// 不通过 Scope 模式激活
   }

作用域控制流程详解

应用启动时：

HotkeysProvider 初始化快捷键系统
initiallyActiveScopes 属性激活全局作用域
全局作用域的快捷键（如搜索、切换面板等）立即可用

布局组件中的作用域注册：

全局布局（(main)/_layout/Desktop/index.tsx）提供全局快捷键作用域
聊天布局（chat/_layout/Desktop/index.tsx）通过 RegisterHotkeys 组件注册聊天作用域

快捷键处理流程：

用户按下组合键
系统检查该组合键对应的处理函数
验证该处理函数关联的作用域是否处于激活状态
只有作用域激活时才执行相应功能

自定义Hook简化作用域管理

我们的 useHotkeyById hook 封装了作用域管理细节：

export const useHotkeyById = (hotkeyId: HotkeyId, callback: HotkeyCallback, options?: Options) => {
  // 从用户配置获取快捷键值
  const hotkey = useUserStore(settingsSelectors.getHotkeyById(hotkeyId));

  const ref = useHotkeys(hotkey, callback, {
    // 默认设置
    enableOnFormTags: true,
    preventDefault: true,

    // 合并传入的选项
    ...options,

    // 关键：自动将快捷键ID添加到作用域列表
    // 这样每个快捷键既属于其功能组（如全局/聊天），又可以单独控制
    scopes: uniq([hotkeyId, ...(item?.scopes || []), ...(_options?.scopes || [])]),
  });

  return { id: hotkeyId, ref };
};

完整注册示例

export const HOTKEYS_REGISTRATION: HotkeyRegistration = [
  ...
  {
    group: HotkeyGroupEnum.ClearChat,
    id: HotkeyEnum.Search,
    keys: combineKeys([KeyEnum.Mod, KeyEnum.Delete]),
    scopes: [HotkeyScopeEnum.Global],
  },
  ...
]

在聊天页面注册快捷键 src/hooks/useHotkeys/chatScope.ts

export const useClearChatHotkey = () => {
  const clearMessages = useChatStore((s) => s.clearMessages);
  const { t } = useTranslation();

  return useHotkeyById(HotkeyEnum.ClearChat, showConfirm);
};

// 注册聚合

export const useRegisterChatHotkeys = () => {
  const { enableScope, disableScope } = useHotkeysContext();

  useClearChatHotkey();
  // ...其他快捷键

  useEffect(() => {
    enableScope(HotkeyScopeEnum.Chat);
    return () => disableScope(HotkeyScopeEnum.Chat);
  }, []);

  return null;
};

通过这种多层次的作用域管理，系统能够智能地在不同界面环境下提供适当的快捷键支持，并支持根据应用状态动态调整快捷键的可用性，同时保持代码的可维护性和扩展性。

布局中的作用域注册

全局作用域

全局快捷键注册 `src/app/[variants]/(main)/_layout/Desktop/RegisterHotkeys.tsx`

'use client';

import { useRegisterGlobalHotkeys } from '@/hooks/useHotkeys';

const RegisterHotkeys = () => {
  useRegisterGlobalHotkeys();
  return null;
};

export default RegisterHotkeys;

全局快捷键注入 Layout `src/app/[variants]/(main)/_layout/Desktop/index.tsx`

import { useTheme } from 'antd-style';
import dynamic from 'next/dynamic';
import { PropsWithChildren, memo } from 'react';
import { HotkeysProvider } from 'react-hotkeys-hook';
import { Flexbox } from 'react-layout-kit';

import { GLOBAL_HOTKEY_SCOPE } from '@/const/hotkeys';
import { BANNER_HEIGHT } from '@/features/AlertBanner/CloudBanner';
import { usePlatform } from '@/hooks/usePlatform';
import { featureFlagsSelectors, useServerConfigStore } from '@/store/serverConfig';

import RegisterHotkeys from './RegisterHotkeys';
import SideBar from './SideBar';

const CloudBanner = dynamic(() => import('@/features/AlertBanner/CloudBanner'));

const Layout = memo<PropsWithChildren>(({ children }) => {
  const { isPWA } = usePlatform();
  const theme = useTheme();

  const { showCloudPromotion } = useServerConfigStore(featureFlagsSelectors);

  return (
    <HotkeysProvider initiallyActiveScopes={[GLOBAL_HOTKEY_SCOPE]}>
      {showCloudPromotion && <CloudBanner />}
      <Flexbox
        height={showCloudPromotion ? `calc(100% - ${BANNER_HEIGHT}px)` : '100%'}
        horizontal
        style={{
          borderTop: isPWA ? `1px solid ${theme.colorBorder}` : undefined,
          position: 'relative',
        }}
        width={'100%'}
      >
        <SideBar />
        {children}
      </Flexbox>
      <RegisterHotkeys />
    </HotkeysProvider>
  );
});

Layout.displayName = 'DesktopMainLayout';

export default Layout;

会话作用域注册

会话快捷键注册 `src/app/[variants]/(main)/chat/_layout/Desktop/RegisterHotkeys.tsx`

import { useRegisterChatHotkeys } from '@/hooks/useHotkeys';

const RegisterHotkeys = () => {
  useRegisterChatHotkeys();
  return null;
};

export default RegisterHotkeys;

会话快捷键注入 Layout `src/app/[variants]/(main)/chat/_layout/Desktop/index.tsx`

import { Flexbox } from 'react-layout-kit';

import InitClientDB from '@/features/InitClientDB';

import { LayoutProps } from '../type';
import RegisterHotkeys from './RegisterHotkeys';
import SessionPanel from './SessionPanel';

const Layout = ({ children, session }: LayoutProps) => {
  return (
    <>
      <Flexbox
        height={'100%'}
        horizontal
        style={{ maxWidth: '100%', overflow: 'hidden', position: 'relative' }}
        width={'100%'}
      >
        <SessionPanel>{session}</SessionPanel>
        <Flexbox flex={1} style={{ overflow: 'hidden', position: 'relative' }}>
          {children}
        </Flexbox>
      </Flexbox>
      <InitClientDB bottom={60} />
      {/* ↓ cloud slot ↓ */}

      {/* ↑ cloud slot ↑ */}
      <RegisterHotkeys />
    </>
  );
};

Layout.displayName = 'DesktopChatLayout';

export default Layout;

基于UI状态的细粒度作用域控制示例 `src/features/ChatInput/Desktop/InputArea/index.tsx`

快捷键系统不仅支持页面级别的作用域管理，还可以实现基于组件状态的更精细作用域控制。以输入区域组件为例，它演示了如何根据交互状态动态控制快捷键的可用性：

const InputArea = memo<InputAreaProps>(({ onSend, value, loading, onChange }) => {
  const { enableScope, disableScope } = useHotkeysContext();

  // ...其他代码

  return (
    <div className={styles.textareaContainer}>
      <TextArea
        // ...其他属性
        onBlur={(e) => {
          onChange?.(e.target.value);
          disableScope(HotkeyEnum.AddUserMessage); // 当输入框失去焦点时禁用相关快捷键
        }}
        onFocus={() => {
          enableScope(HotkeyEnum.AddUserMessage); // 当输入框获得焦点时启用相关快捷键
        }}
        // ...其他事件处理
      />
    </div>
  );
});

这种实现展示了快捷键作用域控制的几个关键特性：

状态感知的作用域控制：

只在输入框获得焦点时启用 AddUserMessage 快捷键作用域
当输入框失去焦点时自动禁用该作用域，防止快捷键误触发

UI交互驱动的作用域管理：

将快捷键作用域的生命周期与UI组件的交互状态（如焦点）绑定
不同于页面级作用域，这种控制可以精确到单个UI元素的状态

防止冲突的精细控制：

通过精确控制作用域的启用/禁用时机，确保快捷键只在适当的上下文中激活
解决了同一快捷键在不同上下文中可能产生冲突的问题

用户体验优化：

确保快捷键行为符合用户直觉，只在用户关注特定UI元素时激活相关快捷键
提供了更符合预期的交互体验，减少意外操作

这种细粒度的作用域控制机制使得快捷键系统能够适应复杂的UI状态，为用户提供上下文相关的键盘交互体验，同时保持整体系统的可维护性和一致性。

设置面板实现

数据驱动型设置面板，新增快捷键后不需要更新，会自动按 const 中的排序和分组进行渲染

'use client';

import { Form, HotkeyInput, type ItemGroup } from '@lobehub/ui';
import isEqual from 'fast-deep-equal';
import { memo } from 'react';
import { useTranslation } from 'react-i18next';

import { HOTKEYS_REGISTRATION } from '@/const/hotkeys';
import { FORM_STYLE } from '@/const/layoutTokens';
import hotkeyMeta from '@/locales/default/hotkey';
import { useUserStore } from '@/store/user';
import { settingsSelectors } from '@/store/user/selectors';
import { HotkeyGroupEnum, HotkeyItem } from '@/types/hotkey';

type SettingItemGroup = ItemGroup;

const HOTKEY_SETTING_KEY = 'hotkey';

const HotkeySetting = memo(() => {
  const { t } = useTranslation(['setting', 'hotkey']);
  const [form] = Form.useForm();

  const settings = useUserStore(settingsSelectors.currentSettings, isEqual);
  const [setSettings] = useUserStore((s) => [s.setSettings]);

  const mapHotkeyItem = (item: HotkeyItem) => {
    const hotkeyConflicts = Object.entries(settings.hotkey)
      .map(([key, value]) => {
        if (key === item.id) return false;
        return value;
      })
      .filter(Boolean) as string[];

    return {
      children: (
        <HotkeyInput
          disabled={item.nonEditable}
          hotkeyConflicts={hotkeyConflicts}
          resetValue={item.keys}
        />
      ),
      desc: hotkeyMeta[item.id].desc ? t(`${item.id}.desc`, { ns: 'hotkey' }) : undefined,
      label: t(`${item.id}.title`, { ns: 'hotkey' }),
      name: [HOTKEY_SETTING_KEY, item.id],
    };
  };

  // 构建设置分组...

  return (
    <Form
      form={form}
      initialValues={settings}
      items={[system, conversation, layout]}
      itemsType={'group'}
      onValuesChange={setSettings}
      variant={'pure'}
      {...FORM_STYLE}
    />
  );
});

组件拆解

1. 常量定义组件

功能：定义快捷键的基本常量和默认配置
文件：src/const/hotkeys.ts
依赖：@lobehub/ui 提供的 KeyMapEnum 和 combineKeys
输出：

全局与聊天作用域常量
默认快捷键注册列表
特殊常量如 KEY_NUMBER

2. 类型定义组件

功能：提供快捷键相关的类型定义
文件：src/types/hotkey.ts
组成：

HotkeyEnum：快捷键标识符枚举
HotkeyGroupEnum：快捷键分组枚举
HotkeyItem 接口：描述单个快捷键项
HotkeyRegistration 类型：快捷键注册列表类型
HotkeyI18nTranslations 类型：国际化翻译类型

3. 快捷键Hook组件

功能：提供快捷键使用的自定义Hooks
文件：

src/hooks/useHotkeys/index.ts：导出所有Hook
src/hooks/useHotkeys/globalScope.ts：全局作用域Hook
src/hooks/useHotkeys/chatScope.ts：聊天作用域Hook

核心Hook：

useSwitchAgentHotkey：快速切换角色
useSaveTopicHotkey：保存会话主题
useRegenerateMessageHotkey：重新生成消息
useToggleLeftPanelHotkey：切换左侧面板
useToggleRightPanelHotkey：切换右侧面板
等等

4. 快捷键注册组件

功能：在适当的上下文中注册和激活快捷键
文件：

src/app/[variants]/(main)/_layout/Desktop/RegisterHotkeys.tsx：全局快捷键注册
src/app/[variants]/(main)/chat/_layout/Desktop/RegisterHotkeys.tsx：聊天作用域快捷键注册

实现方式：

使用 react-hotkeys-hook 提供的 HotkeysProvider 和作用域管理
通过 enableScope 动态激活相关作用域的快捷键

5. 快捷键设置面板

功能：允许用户查看和自定义快捷键
文件：未指定，但可能在设置页面中
核心组件：

Form 和 HotkeyInput：提供设置界面
冲突检测逻辑：防止设置重复快捷键
国际化支持：通过 i18n 提供多语言描述

6. 持久化组件

功能：保存用户自定义快捷键配置
实现：使用 UserStore 中的 settings.hotkey 字段
数据结构：

export type UserHotkeyConfig = Record<HotkeyId, string>;

// 存储在 UserSettings 中
export interface UserSettings {
  // ...其他设置
  hotkey: UserHotkeyConfig;
  // ...其他设置
}

访问方式：通过 selectors 提供便捷访问

const hotkey = useUserStore(settingsSelectors.getHotkeyById(HotkeyEnum.SaveTopic));

总结

该设计实现了一个完整的快捷键系统，具有以下特点：

分层设计：从底层常量定义到上层UI组件，结构清晰
平台感知：自动适配 Windows 和 Mac 的不同快捷键习惯
作用域管理：通过全局和聊天两个作用域合理组织快捷键
分组展示：将快捷键按功能分组，提高可读性
冲突处理：检测并防止快捷键冲突
持久化：保存用户自定义设置
可扩展性：设计支持轻松添加新的快捷键

整体架构符合关注点分离原则，便于后续维护和扩展。

进展

Hotkey 快捷键展示: https://ui.lobehub.com/components/hotkey
HotkeyInput 快捷键录制: https://ui.lobehub.com/components/hotkey-input
在 Tooltip 中增加快捷键展示支持: https://ui.lobehub.com/components/components/tooltip
✨ feat: add Hotkey Settings #7118

canisminor1990 · 2025-03-23T11:38:59Z

canisminor1990
Mar 23, 2025
Maintainer Author

1 reply

canisminor1990 Mar 23, 2025
Maintainer Author

经测试有些快捷键无法被覆盖，比如 ctrl+n ctrl+l

arvinxx · 2025-03-23T16:42:03Z

arvinxx
Mar 23, 2025
Maintainer

快捷键存储的数据结构是怎么样的？
需要把桌面端的快捷键也一并考虑进去。在桌面端下，有些快捷键注册可以在web里，但有些快捷键是需要直接注册到 electron 里。然后这里还会有一些冲突问题，比如把 cmd+w 注册到了 web 里，那么就可能会覆盖掉 electron 默认的 cmd+w 关闭窗口快捷键行为。
桌面端下是可以覆盖 ctrl + n 这些浏览器级的快捷键的，方式就是注册到 electron 的 main 端；
除了快捷键设置面板以外，感觉还需要一个快捷键 list 展示所有可用的快捷键，有些快捷操作是快捷键+鼠标的结合，有些是没法在配置面板里配置的；
Tooltip 组件里是不是可以考虑加个 shortcut 的 props，在 tooltip 里展示常用快捷键是一个挺常用的交互。但现在也有很多地方没把快捷键展示出来

0 replies

canisminor1990 · 2025-03-25T11:31:50Z

canisminor1990
Mar 25, 2025
Maintainer Author

如何添加新的快捷键：开发者指南

本指南将带您一步步地向 LobeChat 添加一个新的快捷键功能。我们将通过一个完整示例，演示从定义到实现的整个过程。

示例场景

假设我们要添加一个新的快捷键功能：快速清空聊天记录，快捷键为 Mod+Shift+Backspace。

步骤 1：更新快捷键常量定义

首先，在 src/types/hotkey.ts 中更新 HotkeyEnum：

export const HotkeyEnum = {
  // 已有的快捷键...
  AddUserMessage: 'addUserMessage',
  EditMessage: 'editMessage',
  
  // 新增快捷键
  ClearChat: 'clearChat', // 添加这一行
  
  // 其他已有快捷键...
} as const;

步骤 2：注册默认快捷键

在 src/const/hotkeys.ts 中添加快捷键的默认配置：

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 中添加对应的文本描述：

import { HotkeyI18nTranslations } from '@/types/hotkey';

const hotkey: HotkeyI18nTranslations = {
  // 现有翻译...
  
  // 添加新快捷键的翻译
  clearChat: {
    desc: '清空当前会话的所有消息记录',
    title: '清空聊天记录',
  },
  
  // 其他现有翻译...
};

export default hotkey;

如需支持其他语言，还需要在相应的语言文件中添加对应翻译。

步骤 4：创建并注册快捷键 Hook

在 src/hooks/useHotkeys/chatScope.ts 中添加新的 Hook：

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 按钮，可以添加快捷键提示：

import { Tooltip } from '@lobehub/ui';
import { DeleteOutlined } from '@ant-design/icons';
import { Button } from 'antd';
import { useTranslation } from 'react-i18next';

import { HotkeyEnum } from '@/types/hotkey';
import { useUserStore } from '@/store/user';
import { settingsSelectors } from '@/store/user/selectors';

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：测试新快捷键

启动开发服务器
打开聊天页面
按下设置的快捷键组合（Cmd+Shift+Backspace 或 Ctrl+Shift+Backspace）
确认功能正常工作
检查快捷键设置面板中是否正确显示了新快捷键

最佳实践

作用域考虑：根据功能决定快捷键应属于全局作用域还是聊天作用域
分组合理：将快捷键放在合适的功能组中（System/Layout/Conversation）
冲突检查：确保新快捷键不会与现有系统、浏览器或应用快捷键冲突
平台适配：使用 Key.Mod 而非硬编码 Ctrl 或 Cmd，以适配不同平台
提供清晰描述：为快捷键添加明确的标题和描述，帮助用户理解功能

按照以上步骤，您可以轻松地向系统添加新的快捷键功能，提升用户体验。如有特殊需求，如桌面专属快捷键，可以通过 isDesktop 标记进行区分处理。

常见问题排查

快捷键未生效：检查作用域是否正确，以及是否在 RegisterHotkeys 中调用了对应的 hook
快捷键设置面板未显示：确认在 HOTKEYS_REGISTRATION 中正确配置了快捷键
快捷键冲突：在 HotkeyInput 组件中可以检测到冲突，用户会看到警告
功能在某些页面失效：确认是否注册在了正确的作用域，以及相关页面是否激活了该作用域

通过这些步骤，您可以确保新添加的快捷键功能稳定、可靠且用户友好。

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[RFC] 100 - Hotkey setting panel 快捷键设置面板 #7111

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 3 comments 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Select a reply

Uh oh!

Uh oh!

[RFC] 100 - Hotkey setting panel 快捷键设置面板 #7111

Uh oh!

Uh oh!

canisminor1990 Mar 23, 2025 Maintainer

背景

设计思路

架构设计

系统架构图

数据流程

快捷键 const 定义

快捷键定义 src/const/hotkeys.ts

快捷键类型定义 src/types/hotkey.ts

快捷键 i18n src/locales/default/hotkey.ts

快捷键 Hook 示例 src/hooks/useHotkeys/chatScope.ts

作用域实现机制

作用域基本概念

作用域注册与生命周期

作用域控制流程详解

自定义Hook简化作用域管理

完整注册示例

布局中的作用域注册

全局作用域

全局快捷键注册 src/app/[variants]/(main)/_layout/Desktop/RegisterHotkeys.tsx

全局快捷键注入 Layout src/app/[variants]/(main)/_layout/Desktop/index.tsx

会话作用域注册

会话快捷键注册 src/app/[variants]/(main)/chat/_layout/Desktop/RegisterHotkeys.tsx

会话快捷键注入 Layout src/app/[variants]/(main)/chat/_layout/Desktop/index.tsx

基于UI状态的细粒度作用域控制示例 src/features/ChatInput/Desktop/InputArea/index.tsx

设置面板实现

组件拆解

1. 常量定义组件

2. 类型定义组件

3. 快捷键Hook组件

4. 快捷键注册组件

5. 快捷键设置面板

6. 持久化组件

总结

进展

Replies: 3 comments · 1 reply

Uh oh!

canisminor1990 Mar 23, 2025 Maintainer Author

Uh oh!

canisminor1990 Mar 23, 2025 Maintainer Author

Uh oh!

Uh oh!

arvinxx Mar 23, 2025 Maintainer

Uh oh!

Uh oh!

canisminor1990 Mar 25, 2025 Maintainer Author

如何添加新的快捷键：开发者指南

示例场景

步骤 1：更新快捷键常量定义

步骤 2：注册默认快捷键

步骤 3：添加国际化翻译

步骤 4：创建并注册快捷键 Hook

步骤 5：给相应 UI 元素添加 Tooltip 提示（可选）

步骤 6：测试新快捷键

最佳实践

常见问题排查

canisminor1990
Mar 23, 2025
Maintainer

快捷键定义 `src/const/hotkeys.ts`

快捷键类型定义 `src/types/hotkey.ts`

快捷键 i18n `src/locales/default/hotkey.ts`

快捷键 Hook 示例 `src/hooks/useHotkeys/chatScope.ts`

全局快捷键注册 `src/app/[variants]/(main)/_layout/Desktop/RegisterHotkeys.tsx`

全局快捷键注入 Layout `src/app/[variants]/(main)/_layout/Desktop/index.tsx`

会话快捷键注册 `src/app/[variants]/(main)/chat/_layout/Desktop/RegisterHotkeys.tsx`

会话快捷键注入 Layout `src/app/[variants]/(main)/chat/_layout/Desktop/index.tsx`

基于UI状态的细粒度作用域控制示例 `src/features/ChatInput/Desktop/InputArea/index.tsx`

Replies: 3 comments 1 reply

canisminor1990
Mar 23, 2025
Maintainer Author

canisminor1990 Mar 23, 2025
Maintainer Author

arvinxx
Mar 23, 2025
Maintainer

canisminor1990
Mar 25, 2025
Maintainer Author