282 lines
7.3 KiB
Markdown
282 lines
7.3 KiB
Markdown
# 键盘多语言/多布局功能 - 最终实施指南
|
||
|
||
## 📋 概述
|
||
|
||
本文档是键盘多语言/多布局功能的最终实施指南，包含所有必要的步骤和注意事项。
|
||
|
||
---
|
||
|
||
## ✅ 已完成的工作
|
||
|
||
### 代码实现
|
||
1. ✅ 配置中心外置（JSON + Manager）
|
||
2. ✅ 布局 JSON 配置补充（AZERTY、QWERTZ、注音布局）
|
||
3. ✅ 扩展侧布局切换逻辑
|
||
4. ✅ 主 App 配置管理器集成
|
||
5. ✅ 联想引擎分流框架
|
||
|
||
### 文件创建
|
||
所有必要的代码文件已创建并验证通过（运行 `check_files.sh` 查看）。
|
||
|
||
---
|
||
|
||
## 🚀 下一步操作（按顺序执行）
|
||
|
||
### 步骤 1: 在 Xcode 中添加新文件
|
||
|
||
**重要性**: ⭐⭐⭐⭐⭐（必须完成）
|
||
|
||
**操作指南**: 参考 `docs/xcode-file-addition-guide.md`
|
||
|
||
**需要添加的文件**:
|
||
1. `Shared/Resource/kb_input_profiles.json`
|
||
- Target: keyBoard + CustomKeyboard
|
||
2. `Shared/KBInputProfileManager.h`
|
||
- Target: keyBoard + CustomKeyboard
|
||
3. `Shared/KBInputProfileManager.m`
|
||
- Target: keyBoard + CustomKeyboard
|
||
4. `CustomKeyboard/Manager/KBKeyboardLayoutResolver.h`
|
||
- Target: CustomKeyboard
|
||
5. `CustomKeyboard/Manager/KBKeyboardLayoutResolver.m`
|
||
- Target: CustomKeyboard
|
||
|
||
**验证方法**:
|
||
```bash
|
||
# 在 Xcode 中编译
|
||
Cmd + B
|
||
```
|
||
|
||
---
|
||
|
||
### 步骤 2: 编译验证
|
||
|
||
**重要性**: ⭐⭐⭐⭐⭐（必须完成）
|
||
|
||
**操作步骤**:
|
||
1. 在 Xcode 中选择 scheme: `keyBoard`
|
||
2. 按 `Cmd + B` 编译主 App
|
||
3. 检查是否有编译错误
|
||
4. 在 Xcode 中选择 scheme: `CustomKeyboard`
|
||
5. 按 `Cmd + B` 编译扩展
|
||
6. 检查是否有编译错误
|
||
|
||
**常见问题**:
|
||
- 如果提示"找不到文件"，检查文件是否正确添加到 target
|
||
- 如果提示"重复符号"，检查 Build Phases > Compile Sources 是否有重复
|
||
|
||
---
|
||
|
||
### 步骤 3: 基础功能测试
|
||
|
||
**重要性**: ⭐⭐⭐⭐⭐（必须完成）
|
||
|
||
**测试清单**: 参考 `docs/testing-checklist.md`
|
||
|
||
**最小测试集**（必须通过）:
|
||
1. ✅ 主 App 语言选择界面正常显示
|
||
2. ✅ 单布局语言（英语）切换成功
|
||
3. ✅ 多布局语言（西班牙语）切换成功
|
||
4. ✅ 扩展侧英语 QWERTY 布局正确显示
|
||
5. ✅ 扩展侧西班牙语 AZERTY 布局正确显示
|
||
6. ✅ App Group 数据正确写入
|
||
|
||
**如果基础测试失败**:
|
||
- 检查日志输出，查找错误信息
|
||
- 确认 App Group 配置正确
|
||
- 确认文件正确添加到工程
|
||
|
||
---
|
||
|
||
### 步骤 4: 完善联想引擎（可选）
|
||
|
||
**重要性**: ⭐⭐⭐（建议完成）
|
||
|
||
**当前状态**: 已实现基础框架，但中文联想词库需要完善
|
||
|
||
**需要完善的部分**:
|
||
1. 繁体拼音联想：实现拼音到繁体字的映射
|
||
2. 注音联想：实现注音符号到繁体字的映射
|
||
3. 简体拼音联想：实现拼音到简体字的映射
|
||
|
||
**实现建议**:
|
||
- 可以使用现有的拼音输入法库（如 OpenCC）
|
||
- 或者创建简单的拼音/注音到汉字的映射表
|
||
- 参考 `KBSuggestionEngine.m` 中的 TODO 注释
|
||
|
||
**如果暂时不实现**:
|
||
- 拉丁字母联想（英语、西班牙语等）已经可以正常工作
|
||
- 中文输入可以先使用基础词库（已提供示例词汇）
|
||
|
||
---
|
||
|
||
### 步骤 5: 本地化资源补齐（可选）
|
||
|
||
**重要性**: ⭐⭐（建议完成）
|
||
|
||
**需要新增的文件**:
|
||
1. `Shared/Localization/es.lproj/Localizable.strings`
|
||
2. `Shared/Localization/pt.lproj/Localizable.strings`
|
||
3. `Shared/Localization/zh-Hant.lproj/Localizable.strings`
|
||
4. `Shared/Localization/id.lproj/Localizable.strings`
|
||
|
||
**如果暂时不实现**:
|
||
- 界面会显示英文文案
|
||
- 不影响核心功能
|
||
|
||
---
|
||
|
||
### 步骤 6: 完整测试
|
||
|
||
**重要性**: ⭐⭐⭐⭐（建议完成）
|
||
|
||
**测试清单**: 参考 `docs/testing-checklist.md`
|
||
|
||
**测试范围**:
|
||
1. 所有语言和布局的切换
|
||
2. 联想引擎切换
|
||
3. 皮肤下发
|
||
4. 异常情况处理
|
||
5. 性能测试
|
||
6. 回归测试
|
||
|
||
---
|
||
|
||
## 📊 实施优先级
|
||
|
||
### P0 - 必须完成（阻塞发布）
|
||
- [x] 代码实现
|
||
- [ ] 在 Xcode 中添加新文件
|
||
- [ ] 编译验证
|
||
- [ ] 基础功能测试
|
||
|
||
### P1 - 建议完成（影响用户体验）
|
||
- [ ] 完善联想引擎
|
||
- [ ] 完整测试
|
||
|
||
### P2 - 可选完成（锦上添花）
|
||
- [ ] 本地化资源补齐
|
||
|
||
---
|
||
|
||
## 🔍 验证检查点
|
||
|
||
### 检查点 1: 文件完整性
|
||
```bash
|
||
cd "/Users/mac/Desktop/项目/公司/KeyBoard"
|
||
./check_files.sh
|
||
```
|
||
预期输出: 所有文件检查通过 ✅
|
||
|
||
### 检查点 2: 编译成功
|
||
- 主 App 编译无错误 ✅
|
||
- 扩展编译无错误 ✅
|
||
|
||
### 检查点 3: 基础功能
|
||
- 语言切换成功 ✅
|
||
- 布局切换成功 ✅
|
||
- 键盘显示正确 ✅
|
||
|
||
### 检查点 4: 数据持久化
|
||
```objc
|
||
NSUserDefaults *appGroup = [[NSUserDefaults alloc] initWithSuiteName:@"group.com.loveKey.nyx"];
|
||
NSLog(@"ProfileId: %@", [appGroup stringForKey:@"AppGroup_SelectedKeyboardProfileId"]);
|
||
```
|
||
预期输出: 正确的 profileId ✅
|
||
|
||
---
|
||
|
||
## 🐛 常见问题排查
|
||
|
||
### 问题 1: 编译错误 "No such file or directory"
|
||
**原因**: 文件没有正确添加到 target
|
||
**解决方案**: 参考 `docs/xcode-file-addition-guide.md` 重新添加文件
|
||
|
||
### 问题 2: 键盘布局没有切换
|
||
**原因**: App Group 数据没有正确写入或读取
|
||
**解决方案**:
|
||
1. 检查 App Group 配置是否正确
|
||
2. 检查日志输出，查看 profileId 是否正确
|
||
3. 确认 `KBKeyboardLayoutResolver` 正确读取数据
|
||
|
||
### 问题 3: 联想功能不工作
|
||
**原因**: 联想引擎没有正确切换
|
||
**解决方案**:
|
||
1. 检查 `kb_updateSuggestionEngineType:` 是否被调用
|
||
2. 检查 `KBSuggestionEngine` 的 `engineType` 是否正确设置
|
||
3. 查看日志输出
|
||
|
||
### 问题 4: 注音布局显示不正确
|
||
**原因**: 注音符号可能需要特殊字体支持
|
||
**解决方案**:
|
||
1. 确认系统支持注音符号显示
|
||
2. 检查 `kb_keyboard_layout_config.json` 中的注音符号是否正确
|
||
3. 可能需要调整字体设置
|
||
|
||
---
|
||
|
||
## 📝 日志检查
|
||
|
||
在测试过程中，注意查看以下日志：
|
||
|
||
### 主 App 日志
|
||
```
|
||
[KBInputProfileManager] Loaded X profiles
|
||
[KBPersonInfoVC] Switching to profileId: xxx
|
||
```
|
||
|
||
### 扩展日志
|
||
```
|
||
[KBKeyboardView] Loaded profileId: xxx, layoutJsonId: xxx
|
||
[KBKeyboardLayoutResolver] layoutJsonId for profileId xxx: xxx
|
||
[KeyboardViewController] Detected profileId change: xxx -> xxx
|
||
[KBSuggestionEngine] Engine type set to: xxx
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 成功标准
|
||
|
||
### 最小可行产品（MVP）
|
||
- ✅ 主 App 可以选择语言和布局
|
||
- ✅ 扩展侧可以正确显示对应的键盘布局
|
||
- ✅ 英语和西班牙语（QWERTY/AZERTY/QWERTZ）正常工作
|
||
- ✅ 数据正确持久化到 App Group
|
||
|
||
### 完整功能
|
||
- ✅ 所有语言和布局都正常工作
|
||
- ✅ 繁体中文联想功能正常
|
||
- ✅ 注音输入功能正常
|
||
- ✅ 皮肤正确下发
|
||
- ✅ 无崩溃和性能问题
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
1. `keyboard-language-layout-handover.md` - 原始交接文档
|
||
2. `keyboard-language-layout-implementation-summary.md` - 实现总结
|
||
3. `xcode-file-addition-guide.md` - Xcode 文件添加指南
|
||
4. `testing-checklist.md` - 完整测试清单
|
||
|
||
---
|
||
|
||
## 🤝 需要帮助？
|
||
|
||
如果在实施过程中遇到问题：
|
||
|
||
1. 查看相关文档
|
||
2. 检查日志输出
|
||
3. 参考常见问题排查
|
||
4. 运行 `check_files.sh` 验证文件完整性
|
||
|
||
---
|
||
|
||
## ✨ 总结
|
||
|
||
本次实现已经完成了核心功能的代码编写，剩余工作主要是：
|
||
1. 在 Xcode 中添加文件（必须）
|
||
2. 编译和测试（必须）
|
||
3. 完善联想引擎（建议）
|
||
|
||
按照本指南的步骤操作，应该可以顺利完成整个功能的实施。祝你成功！🎉
|