search-syntax-pro/SHORTCUT_SETTINGS_FIX.md

Options 页面快捷键设置修复报告

修复日期

2025-11-11

问题概述

修复了 options 页面快捷键设置部分的两个关键问题：

1. 保存/取消按钮的国际化显示问题
2. 引擎切换快捷键的默认值显示问题

---

问题一：保存/取消按钮国际化问题

根本原因

位置: /src/components/ShortcutSettings.tsx 第 496, 503 行

问题分析:

• 代码使用了 t('common.saving'), t('common.save'), t('common.cancel') 等翻译键
• 但这些翻译键在 /src/i18n/translations.ts 中并未定义
• 导致 i18n 系统回退到硬编码的英文默认值 ('Saving...', 'Save', 'Cancel')
• 即使用户设置为中文界面，这些按钮依然显示英文

证据代码:

// ShortcutSettings.tsx:496
{saving ? t('common.saving', {}, 'Saving...') : t('common.save', {}, 'Save')}

// ShortcutSettings.tsx:503
{t('common.cancel', {}, 'Cancel')}

修复方案

在 /src/i18n/translations.ts 中添加缺失的翻译键：

// 中文翻译 (zh-CN)
'common.save': '保存',
'common.cancel': '取消',
'common.saving': '保存中...',
'common.edit': '编辑',
'common.reset': '重置',

// 英文翻译 (en-US)
'common.save': 'Save',
'common.cancel': 'Cancel',
'common.saving': 'Saving...',
'common.edit': 'Edit',
'common.reset': 'Reset',

额外收益: 同时添加了 common.edit 和 common.reset，这些在其他组件中也有使用，提高了代码的一致性。

---

问题二：引擎切换默认值显示问题

根本原因

位置: /src/components/ShortcutSettings.tsx 第 218, 483 行

问题分析:

1. 数据模型不一致:

   • 默认快捷键配置使用 actionParam (数字索引) 来指定引擎
   • UI 层期望使用 targetEngine (引擎名称字符串)
   • 当用户未自定义时，targetEngine 为 undefined

2. 初始化逻辑缺陷:

   // 原代码 (line 218)
   setTempEngine(shortcut.targetEngine as SearchEngine || null);
   // 当 targetEngine 为 undefined 时，tempEngine 设为 null
   

3. 显示逻辑降级错误:

   // 原代码 (line 483)
   value={tempEngine || shortcut.targetEngine as SearchEngine || 'baidu'}
   // 最终总是降级到 'baidu'，导致所有未自定义的快捷键都显示百度
   

4. 用户体验问题:

   • 实际配置: Ctrl+1 → Google, Ctrl+2 → Bing, Ctrl+3 → Twitter...
   • 显示结果: 所有快捷键的下拉框都定位到百度
   • 造成严重的认知歧义

修复方案

1. 添加辅助函数计算默认目标引擎

/**
 * 根据快捷键的 actionParam 获取默认目标引擎
 * actionParam 是引擎在支持列表中的索引
 */
const getDefaultTargetEngine = (shortcut: KeyboardShortcut): SearchEngine => {
  const supportedEngines = SearchAdapterFactory.getSupportedEngines();

  // 如果已经设置了 targetEngine，直接返回
  if (shortcut.targetEngine) {
    return shortcut.targetEngine as SearchEngine;
  }

  // 如果有 actionParam（引擎索引），使用它来获取对应的引擎
  if (typeof shortcut.actionParam === 'number' && shortcut.actionParam >= 0) {
    const engine = supportedEngines[shortcut.actionParam];
    if (engine) {
      return engine;
    }
  }

  // 降级：返回第一个引擎
  return supportedEngines[0];
};

设计亮点:

• 三层降级策略确保健壮性
• 优先使用显式配置 (targetEngine)
• 其次使用索引映射 (actionParam)
• 最后降级到第一个引擎

2. 更新编辑初始化逻辑

const startEdit = (id: string, shortcut: KeyboardShortcutWithId) => {
  // ...
  
  // 对于引擎切换快捷键，获取默认目标引擎
  if (shortcut.action === 'SWITCH_ENGINE') {
    setTempEngine(getDefaultTargetEngine(shortcut));
  } else {
    setTempEngine(null);
  }
  
  // ...
};

3. 更新选择器显示逻辑

<EngineSelector
  value={tempEngine || getDefaultTargetEngine(shortcut)}
  onChange={setTempEngine}
/>

4. 更新非编辑状态显示

{isEngineSwitch && (
  <span className="text-sm text-gray-600 dark:text-gray-400">
    → {t(`common.searchEngines.${getDefaultTargetEngine(shortcut)}`, {}, getDefaultTargetEngine(shortcut))}
  </span>
)}

---

修改的文件列表

1. /src/i18n/translations.ts

• 添加 common.save, common.cancel, common.saving, common.edit, common.reset 的中英文翻译
• 影响范围: 整个应用的按钮文本国际化

2. /src/components/ShortcutSettings.tsx

• 添加 SearchAdapterFactory 导入
• 新增 getDefaultTargetEngine 辅助函数
• 更新 startEdit 函数初始化逻辑
• 更新 EngineSelector 的 value 属性
• 更新非编辑状态的引擎显示逻辑
• 影响范围: 仅快捷键设置页面

---

测试验证建议

场景 1: 国际化验证

1. 打开 options 页面，切换到"快捷键"标签
2. 点击任意可自定义快捷键的"编辑"按钮
3. 验证"保存"和"取消"按钮的文本：
   • 中文语言下应显示"保存"和"取消"
   • 英文语言下应显示"Save"和"Cancel"
4. 点击"保存"，验证按钮文本变为"保存中..."或"Saving..."

场景 2: 引擎切换默认值验证

1. 确保未自定义任何引擎切换快捷键（或重置所有快捷键）
2. 依次点击编辑以下快捷键：
   • Ctrl+1: 应显示"百度"
   • Ctrl+2: 应显示"谷歌"
   • Ctrl+3: 应显示"必应"
   • Ctrl+4: 应显示"X (Twitter)"
   • Ctrl+5: 应显示"DuckDuckGo"
3. 验证非编辑状态下，快捷键右侧的引擎名称显示正确

场景 3: 自定义保存验证

1. 编辑 Ctrl+1，将引擎改为"谷歌"，保存
2. 重新编辑 Ctrl+1，验证下拉框定位到"谷歌"
3. 重置该快捷键，验证下拉框重新定位到"百度"

---

代码质量改进

类型安全

• 使用 TypeScript 类型守卫确保引擎类型正确
• 添加详细的 JSDoc 注释说明函数用途

性能优化

• getDefaultTargetEngine 函数设计为纯函数，无副作用
• 使用三层降级策略确保健壮性

可维护性

• 将引擎映射逻辑封装为独立函数，便于测试和复用
• 添加了 SearchAdapterFactory 的集中化引擎管理

一致性

• 统一了所有"保存/取消/编辑/重置"按钮的翻译键
• 确保所有引擎切换快捷键使用相同的默认值计算逻辑

---

风险评估

低风险

• 修改仅涉及 UI 层逻辑，不影响数据存储
• 添加的翻译键向后兼容，不会破坏现有功能
• 引擎映射逻辑有完善的降级机制

潜在影响

• 已自定义快捷键的用户不受影响（targetEngine 已存在）
• 未自定义的用户将看到正确的默认引擎显示

---

编译验证

✓ tsc 类型检查通过
✓ vite build 成功
✓ 无警告或错误

---

总结

本次修复解决了两个影响用户体验的关键问题：

1. 国际化完整性: 确保所有 UI 元素正确响应语言设置
2. 数据一致性: 修复了 actionParam 和 targetEngine 之间的映射逻辑

修复后的代码具有更好的：

• 用户体验: 正确的语言显示和引擎映射
• 代码质量: 类型安全、可维护、健壮
• 向后兼容: 不影响现有用户的自定义配置

建议在发布前进行完整的回归测试，特别是多语言环境下的快捷键设置功能。