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')
- 即使用户设置为中文界面，这些按钮依然显示英文

**证据代码**:
```typescript
// ShortcutSettings.tsx:496
{saving ? t('common.saving', {}, 'Saving...') : t('common.save', {}, 'Save')}

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

### 修复方案

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

```typescript
// 中文翻译 (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. **初始化逻辑缺陷**:
   ```typescript
   // 原代码 (line 218)
   setTempEngine(shortcut.targetEngine as SearchEngine || null);
   // 当 targetEngine 为 undefined 时，tempEngine 设为 null
   ```

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

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

### 修复方案

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

```typescript
/**
 * 根据快捷键的 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. 更新编辑初始化逻辑

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

#### 3. 更新选择器显示逻辑

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

#### 4. 更新非编辑状态显示

```typescript
{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` 已存在）
- 未自定义的用户将看到正确的默认引擎显示

---

## 编译验证

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

---

## 总结

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

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

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

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