hotkey

キーボードショートカット追加ガイド

新しいホットキーを追加する手順

1. ホットキー定数を更新する

packages/types/src/hotkey.ts で、HotkeyId ユニオンに新しい ID を追加します。これは、HotkeyEnum の型定義の基準となる唯一の情報源です。

export type HotkeyId =
  | 'addUserMessage'
  // existing...
  | 'saveTopic';

2. デフォルトのホットキーを登録する

packages/const/src/hotkeys.ts では、KeyEnum と combineKeys はすでにこのファイル内で定義されているため、インポートは不要です。HotkeyEnum と HOTKEYS_REGISTRATION にエントリーを追加します。

export const HotkeyEnum = {
  // existing...
  SaveTopic: 'saveTopic',
} as const satisfies Record<string, HotkeyId>;

export const HOTKEYS_REGISTRATION: HotkeyRegistration = [
  // existing...
  {
    group: HotkeyGroupEnum.Conversation,
    id: HotkeyEnum.SaveTopic,
    keys: combineKeys([KeyEnum.Alt, 'n']),
    scopes: [HotkeyScopeEnum.Chat],
  },
];

3. i18n 翻訳を追加する

packages/locales/src/default/hotkey.ts で次のようにします。

const hotkey: HotkeyI18nTranslations = {
  saveTopic: {
    desc: '保存当前话题并新建一个话题',
    title: '保存话题',
  },
};

4. フックを作成して登録する

src/hooks/useHotkeys/chatScope.ts で次のようにします。

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

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

5. ツールチップを追加する（任意）

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

<Tooltip hotkey={saveTopicHotkey} title={t('saveTopic.title', { ns: 'hotkey' })}>
  <Button icon={<SaveOutlined />} onClick={openNewTopicOrSaveTopic} />
</Tooltip>;

ベストプラクティス

1. スコープ：機能に応じて、グローバルまたはチャットのスコープを選択します
2. グループ分け：適切なグループ（System/Layout/Conversation）に配置します
3. 競合の確認：システムやブラウザーのショートカットと競合しないことを確認します
4. プラットフォーム：Ctrl や Cmd をハードコードせず、KeyEnum.Mod を使用します
5. 明確な説明：ユーザー向けにタイトルと説明を設定します

トラブルシューティング

• 動作しない：スコープと RegisterHotkeys フックを確認します
• 設定に表示されない：HOTKEYS_REGISTRATION の設定を確認します
• 競合する：HotkeyInput コンポーネントに警告が表示されます
• ページ固有の動作：正しいスコープが有効になっていることを確認します