企业官网建设流程全解析

用MIT授权的azooKey打造你自己的日语输入法：二次开发关键注意事项全解析

【免费下载链接】azooKeyazooKey is an open-source Japanese keyboard for iPhone and iPad, written in Swift and powered by its own kana-kanji conversion engine. It provides live conversion, flexible key layouts, and a clean SwiftUI interface for a smooth typing experience.项目地址: https://gitcode.com/gh_mirrors/az/azooKey

📌一句话简介：azooKey 是一款 MIT 授权、用 Swift 编写的开源日语输入法（iPhone/iPad 日语键盘），内置自研假名-汉字转换引擎（Zenzai）、实时转换与灵活按键布局，界面基于 SwiftUI 打造。凭借宽松的 MIT 许可证，你可以合法地以它为底座，打造属于自己的日语输入法。这篇文章就是二次开发前必读的"避坑指南"。

🚀 第一步：获取代码并跑起来

在main分支开发前，先克隆仓库。⚠️ azooKey 使用了 Git 子模块，必须加--recursive，否则构建会失败：

git clone https://gitcode.com/gh_mirrors/az/azooKey --recursive

• 需要Apple Developer 账号（免费即可）和最新版 Xcode
• 打开azooKey.xcodeproj，按 Xcode 提示完成签名，Command+R 运行
• 首次启动会引导你安装键盘扩展，跟着提示操作即可

项目结构一图看懂

想深入理解架构，推荐精读官方文档 docs/overview.md，里面还附了一张关键术语表（Candidate、Composing、Custard 等）。

🖲️ 先认识一下：你继承的是一款怎样的键盘

azooKey 是フリック（甩动/点按）输入日语键盘，支持实时转换、候选栏、自定义按键与自定义标签页，下面就是它的自定义快捷短语面板（Custard）实际效果：

你二次开发时，将继承上面这套完整交互体验——这正是选择 azooKey 作为底座的理由。

⚠️ 注意一：必须修改的硬编码常量

这是官方在 docs/advice_for_azooKey_based_development.md 里明确要求处理的事项，否则你的 App 会和 azooKey 本体"撞车"：

1. App Group ID：主 App 与键盘扩展靠它共享数据，定义在 SharedStore.swift
2. 误变換报告的 Google Form ID：散落在 ReportSubmissionHelper.swift 等多处
3. URL Scheme、推荐自定义标签页的 API 地址等

💡 建议：全局搜索azooKey、docs.google.com等关键词，逐一替换或禁用。

⚠️ 注意二：官方明确"不支持"的功能

在评估方案前，先认清 azooKey 的能力边界（官方声明暂无计划支持）：

• 🚫トグル入力（多段按压/九宫格手机输入）——如果你要面向老年用户或习惯老式输入法的群体，需自己实现
• 🚫なぞり入力（滑动手势输入）——日语、英语均不支持，官方表示目前技术成本过高

好在假名-汉字转换模块的输入是假名流，理论上你可以用自己的 UI 把多段按压的结果"喂"给它，但键盘 UI 层需要自己实现。

⚠️ 注意三：iOS 版本支持策略

官方政策见 docs/policies/ios_support.md：最多支持到 2 个世代之前的 iOS。你的衍生产品是否沿用该策略，要根据自己的用户群自行决定——若面向大量旧设备用户，请提前评估 SwiftUI 最低版本带来的改造成本。

🧪 跑测试：改完代码别忘验证

测试入口在 docs/tests.md：把 Xcode 的 Scheme 切换到azooKeyTests，然后 Command+U 即可运行。

git switch -c feat/your-feature # 基于 main 切分支 # 修改代码 → Xcode Build & Run 验证 → commit & push

代码风格由 SwiftLint 统一约束（参考 docs/CONTRIBUTING.md），Xcode 集成后可自动格式化，避免合并冲突。

🔧 建议重构的三处实现

官方坦诚指出以下"历史包袱"，二次开发时顺手解决会让你未来轻松不少：

📱 键盘布局：旋转与浮动模式是重灾区

官方在 docs/keyboard_layout_behavior.md 中特别警告：设备旋转和浮动模式是 Keyboard Extension 布局最容易出 Bug 的场景，且"每个 iOS 更新都可能把旋转布局弄坏"。azooKey 为"竖/横 × iPhone/iPad"共 4 套布局，你先获取键盘区域宽度，再反推高度与各组件尺寸。预留充足的真机（不同尺寸机型）调试时间。

🍮 扩展你的键盘：CustardKit

azooKey 把自定义标签页（Custard）拆成了独立包 AzooKeyCore/Sources/CustardKit/，其 README 明确了兼容性方针：

• ✅ 新 App 必须能读旧格式 JSON
• ❌ 不要求旧 App 读新格式 JSON
• ⚠️ QWERTY 专用系统键（shift、空格等）仅限pc_style+grid_fit界面组合，其他组合在 encode/decode 时会校验拒绝

另外，部分高级功能（剪贴板历史、震动反馈、联系人转换等，见 docs/settings.md）依赖**完全访问（Full Access）**权限，你的产品里同样需要设计好对应的引导流程。

✅ 最后的合规清单（MIT 许可证）

azooKey 采用 MIT 授权（见 LICENSE），核心义务只有一条：

在所有副本或软件的重要部分中，保留原版权声明与许可声明。

也就是说：署名保留、可商用、可闭源分发，但不能宣称 azooKey 的作者为你的产品缺陷背书（许可证明确 "AS IS"、无任何担保）。发布前请核对：

• 版权声明未删除
• App Group ID 等硬编码已替换
• 不依赖 azooKey 的 Form/URL 等外部服务
• 测试（azooKeyTests scheme）通过

🎯总结：azooKey 给了你一个"即插即用"的高质量日语输入法底座——自研变词、实时转换、SwiftUI 界面、Custard 扩展机制。只要处理好硬编码替换、能力边界、版本策略、存储重构这四件事，你就能站在成熟开源项目之上，快速打造出真正属于你自己的日语输入法。祝开发顺利！

【免费下载链接】azooKeyazooKey is an open-source Japanese keyboard for iPhone and iPad, written in Swift and powered by its own kana-kanji conversion engine. It provides live conversion, flexible key layouts, and a clean SwiftUI interface for a smooth typing experience.项目地址: https://gitcode.com/gh_mirrors/az/azooKey