Komaki Furigana

日语假名标注插件 · 作者：komaki · 版本：1.0.0

把选中的日语原文与手动输入的读音保存为标准 HTML Ruby。无需 Templater，无需账号、网络或 API Key。安装包已经编译，普通使用不需要 Node.js。

<ruby>日本語<rt>にほんご</rt></ruby>

安装（先看这里）

1. 解压 ZIP，找到里面的 komaki-furigana 文件夹。

2. 打开你的 Obsidian 仓库目录，把这个文件夹复制到 .obsidian/plugins/ 下。如果没有 plugins 文件夹，可以自己创建。

3. 确认三个必要文件位于下列位置，避免解压后多套一层同名文件夹：

   • 你的仓库/.obsidian/plugins/komaki-furigana/main.js
   • 你的仓库/.obsidian/plugins/komaki-furigana/manifest.json
   • 你的仓库/.obsidian/plugins/komaki-furigana/styles.css

4. 重启 Obsidian，进入 设置 → 第三方插件，开启第三方插件功能，在已安装列表中启用 Komaki Furigana。

5. 打开一篇笔记，切换到编辑模式，即可使用。

这是供手动安装的插件包，尚未发布到 Obsidian 社区插件目录，因此不能直接在社区插件搜索页安装。上面的 .obsidian 是默认配置目录；如果你修改过仓库配置目录名称，请使用实际的配置目录。

macOS 可按 ⌘ + Shift + . 显示隐藏文件夹。也可以从 Obsidian 第三方插件页面的文件夹按钮打开插件目录。手机端需要将同一文件夹放入手机上对应仓库的配置目录；本插件不依赖桌面专属接口，但尚未进行 Android / iOS 真机验证。

最快用法

1. 在编辑模式中选中 日本語。
2. 按 Ctrl + P（macOS：⌘ + P），搜索 Komaki Furigana。
3. 运行 添加 / 编辑假名。
4. 在读音框输入 にほんご，查看预览，按 Enter 或点击 保存标注。

也可以选中文字后右键，选择 添加 / 编辑假名，或者点击左侧工具栏的语言图标。

未选中文字时，窗口会让你同时填写原文和假名，保存到打开窗口时的光标位置。Esc 或取消不会改写笔记。假名为空时不会覆盖原文。

修改与移除

修改： 在源码中把光标放进已有 <ruby>…</ruby> 内，或选中其中的原文，再运行 添加 / 编辑假名。窗口会自动填入已有原文和读音，保存后更新这一条标注。

移除： 把光标放在标注内，运行 移除假名（保留原文）。也可以在编辑窗口中点击 移除标注。选中包含多条完整 Ruby 的正文后，移除命令可一次去掉多条注音。

如果选区只截断了多条标注中的一部分，插件会提示重新选择。常规编辑可以用 Obsidian 的撤销功能恢复；批量插入或移除作为一次文本修改处理。

你原先的 Templater 输出可以直接识别，不需要迁移。对带多个 <rt>、嵌套标签、自定义属性或复杂 HTML 的 Ruby，插件会保留原文，不强行重写。

批量标注

运行 批量标注（原文｜假名），每行填一组：

日本語｜にほんご
勉強｜べんきょう
学校｜がっこう

• 支持全角 ｜、半角 |、制表符三个分隔方式。
• 可以先在笔记里写好、选中这些行，再打开批量窗口；保存时会替换选区。
• 未选中文字时，会把标注插入原来的光标位置。
• 空行保留；源码中的单个换行如何显示，由 Markdown 渲染规则决定。
• 每次最多 200 组，每个原文或读音字段最多 500 个字符。
• 任意一行格式错误，整个批次都不会写入，并会显示具体行号。
• Ctrl / ⌘ + Enter 保存，Esc 取消。

快捷键

进入 设置 → 快捷键，搜索 Komaki Furigana，为以下命令自行指定快捷键：

插件不预占默认快捷键。你可以把常用的添加命令设为自己顺手且没有冲突的组合键。

显示与设置

• 阅读视图： 由 Obsidian 的 HTML 渲染显示 Ruby。
• 实时预览： 光标离开标注后显示注音；点击标注或将光标移入标注时显示源码。光标紧贴标注边缘时也会显示源码。
• 源码模式： 始终保留 <ruby> 源码，不隐藏标签。
• 字号： 可设为正文大小的 35%–85%，默认 55%。
• 位置： 可选择原文上方或下方。
• 隐藏假名： 隐藏读音但保留其占位，方便自测；不修改笔记。输入窗口的效果预览始终显示读音。
• 假名转换： 可在窗口里手动转平假名 / 片假名，也可设置保存时自动转换已输入的假名。转换不是自动推断汉字读音，默认保持输入。
• 兼容括号： 可为新标注加入 <rp>(</rp> 和 <rp>)</rp>，让不支持 Ruby 的阅读器显示后备括号。修改已有标注时保留原来的括号模式。
• 右键菜单： 可在设置中开关。

这些显示设置会应用到仓库里标准 Ruby 的阅读效果，包括旧笔记中的标注。停用插件后，标准 Ruby 数据仍保留在笔记中，可继续由支持 Ruby 的阅读器显示。

使用边界与保护

• 这是手动假名标注工具，不会根据汉字自动猜读音，也没有日语词典或在线注音服务。
• 只处理单行原文。请选择纯文字；输入窗口中的 Markdown 格式符号会作为文字保存，不会被当作嵌套格式渲染。
• 字符 <、>、&、引号会被转义，避免输入内容变成 HTML 标签。
• 代码围栏、行内代码、缩进代码、文档属性与 HTML 注释中的内容会被跳过。某些复杂 Markdown 结构可能被保守地视为代码。
• 同时存在多个选区时会要求保留一个选区，以免误改其他选区。
• 输入法正在组词、确认候选字或刚结束组词时，Enter 不会立即触发保存；可再次按 Enter 或点击保存。
• 窗口打开后，如果文件切换或笔记内容发生变化，插件会拒绝写入；窗口中的输入仍保留，可复制后重新操作。
• 若实时预览与主题或其他编辑器插件冲突，可在设置中关闭本插件的实时预览效果，添加和编辑功能仍然可用。
• 插件只修改本次操作的文本；设置保存在 Obsidian 为插件提供的 data.json 中。无遥测，无外部请求，不上传笔记。

文件与开发

普通使用只需三个必要文件，直接复制整个文件夹也可以。开发时在此目录执行：

npm ci
npm run build
npm test

浏览器集成测试使用真实 CodeMirror 编辑器和模拟的 Obsidian 宿主接口。运行该测试还需安装 Playwright 及其 Chromium：

npm install --no-save playwright
npx playwright install chromium
node tests/browser-smoke.cjs

开发接口依据 Obsidian 官方 API 与 官方插件示例。最低应用版本声明为 1.5.0。本包未在真实 Obsidian 桌面端或手机端进行完整验收；测试范围和结果见 VALIDATION.md。

许可证

MIT © 2026 komaki。详见 LICENSE。