keyboard/docs/quick-reference.md

键盘多语言/多布局功能 - 快速参考

🎯 核心功能

支持的语言和布局

语言	布局选项	ProfileId 示例
英语	QWERTY	en_US_qwerty
西班牙语	QWERTY / AZERTY / QWERTZ	es_ES_azerty
葡萄牙语	QWERTY	pt_PT_qwerty
繁体中文	拼音 / 注音全键盘 / 注音标准	zh_Hant_TW_bopomofo_full
印尼语	QWERTY	id_ID_qwerty

---

📁 关键文件

新增文件（需要添加到 Xcode）

Shared/
├── Resource/
│   └── kb_input_profiles.json          # 配置文件
├── KBInputProfileManager.h             # 管理器头文件
└── KBInputProfileManager.m             # 管理器实现

CustomKeyboard/
└── Manager/
    ├── KBKeyboardLayoutResolver.h      # 解析器头文件
    └── KBKeyboardLayoutResolver.m      # 解析器实现

修改文件

CustomKeyboard/
├── Resource/
│   └── kb_keyboard_layout_config.json  # 新增布局配置
├── View/
│   ├── KBKeyboardView.h/m              # 布局切换逻辑
│   └── KBKeyBoardMainView.h/m          # 布局重载方法
├── Manager/
│   └── KBSuggestionEngine.h/m          # 联想引擎分流
└── KeyboardViewController.m            # 布局检查逻辑

keyBoard/
└── Class/Me/VC/
    └── KBPersonInfoVC.m                # 配置管理器集成

---

🔑 关键 API

主 App 侧

// 获取所有语言配置
[[KBInputProfileManager sharedManager] allProfiles];

// 根据语言代码获取配置
[[KBInputProfileManager sharedManager] profileForLanguageCode:@"es"];

// 根据 profileId 获取布局 JSON ID
[[KBInputProfileManager sharedManager] layoutJsonIdForProfileId:@"es_ES_azerty"];

扩展侧

// 获取当前 profileId
[[KBKeyboardLayoutResolver sharedResolver] currentProfileId];

// 获取布局 JSON ID
[[KBKeyboardLayoutResolver sharedResolver] layoutJsonIdForProfileId:profileId];

// 获取联想引擎类型
[[KBKeyboardLayoutResolver sharedResolver] suggestionEngineForProfileId:profileId];

// 重新加载布局
[keyboardView reloadLayoutWithProfileId:profileId];

// 切换联想引擎
[[KBSuggestionEngine shared] setEngineTypeFromString:@"pinyin_traditional"];

---

🔄 数据流

主 App → 扩展

用户选择语言/布局
    ↓
KBPersonInfoVC 写入 App Group
    ↓
AppGroup_SelectedKeyboardProfileId = "es_ES_azerty"
AppGroup_SelectedKeyboardLanguageCode = "es"
AppGroup_SelectedKeyboardLayoutVariant = "azerty"
    ↓
扩展读取 App Group
    ↓
KBKeyboardLayoutResolver 解析 profileId
    ↓
layoutJsonId = "letters_azerty"
suggestionEngine = "latin"
    ↓
KBKeyboardView 加载布局
KBSuggestionEngine 切换引擎

---

🧪 快速测试

1. 验证文件完整性

cd "/Users/mac/Desktop/项目/公司/KeyBoard"
./check_files.sh

2. 验证 App Group 数据

NSUserDefaults *appGroup = [[NSUserDefaults alloc] initWithSuiteName:@"group.com.loveKey.nyx"];
NSLog(@"ProfileId: %@", [appGroup stringForKey:@"AppGroup_SelectedKeyboardProfileId"]);
NSLog(@"LanguageCode: %@", [appGroup stringForKey:@"AppGroup_SelectedKeyboardLanguageCode"]);
NSLog(@"LayoutVariant: %@", [appGroup stringForKey:@"AppGroup_SelectedKeyboardLayoutVariant"]);

3. 验证布局切换

1. 主 App 切换到"Español · AZERTY"
2. 打开备忘录，调出键盘
3. 检查第一行是否为: a z e r t y u i o p

---

🐛 快速排查

问题	检查项	解决方案
编译错误	文件是否添加到 target	重新添加文件
布局不切换	App Group 数据是否写入	检查日志
联想不工作	引擎类型是否切换	检查日志
注音显示异常	JSON 配置是否正确	检查配置文件

---

📊 实施进度

• 代码实现
• 添加文件到 Xcode
• 编译验证
• 基础测试
• 完善联想引擎
• 完整测试

---

📚 文档索引

文档	用途
final-implementation-guide.md	完整实施指南
xcode-file-addition-guide.md	Xcode 文件添加
testing-checklist.md	完整测试清单
keyboard-language-layout-implementation-summary.md	实现总结

---

💡 提示

• 优先完成 P0 任务（添加文件、编译、基础测试）
• 联想引擎可以后续完善
• 遇到问题先查看日志输出
• 使用 check_files.sh 验证文件完整性