HTML中ruby标签在电子书制作中的妙用-html教程-PHP中文网

ruby 是电子书实现字级发音锚定、多语言混排和无障碍朗读的关键结构，必须严格遵循 epub 3.0+ 规范：显式包裹 rb、rt 为 rb 同级兄弟、强制包含 rp、禁用相对字体单位、用绝对值控制字号与行高。

html中ruby标签在电子书制作中的妙用

ruby 标签在电子书制作中不是“锦上添花”的装饰手段，而是解决**字级发音锚定、多语言混排语义、无障碍朗读基础**的关键结构——但它一旦用错，就会在 Kindle、Apple Books、EPUB 阅读器里直接降级为乱序平铺文字，甚至被屏幕阅读器跳过。

为什么电子书里 `ruby` 不能只写 `<ruby>汉<rt>hàn</rt></ruby>`

多数 EPUB 阅读器（尤其是 Kindle 的 Mobipocket 渲染引擎和旧版 Apple Books）会把缺失 rb 的 ruby 当作普通内联容器处理，导致 rt 内容紧贴汉字右侧输出，变成“汉hàn”这种不可读形式。这不是样式问题，是语义解析失败。

rb 必须显式包裹每个被注音汉字，不能省略
rt 必须是 rb 的**直接同级兄弟节点**，不能嵌套在 rb 内或跨 rb 共享
EPUB 3.0+ 规范明确要求 ruby 结构为 <ruby><rb>…</rb><rt>…</rt></ruby>，否则校验失败

`rp` 不是可选项，是电子书兼容性的底线

Kindle（特别是 Paperwhite 10 及更早型号）、Calibre 的 EPUB 转 MOBI 流程、部分安卓阅读 App（如 Moon+ Reader 旧版）完全不识别 ruby，但会原样渲染 rp 中的内容。漏掉 rp，用户看到的就是“汉hàn”；加上它，至少能显示成“汉(hàn)”，保留基本可读性。

Doc To HTML

使用 MinerU 文档处理引擎将 Word 文档（.doc、.docx）转换为保留结构和格式的干净 HTML。

下载

必须写成 <rp>(</rp><rt>hàn</rt><rp>)</rp>，括号字符必须纯文本，不能带空格或 HTML 实体
不要用 ( 替代 (，某些阅读器无法解码
多个 ruby 连续出现时，rp 能防止相邻拼音粘连（如“你好”变成“你(hǎo)好”而非“你(hǎo好)”）

EPUB 中 `ruby` 的 CSS 控制必须绕开 `font-size: xx%`

EPUB 阅读器对相对单位（em、%）的继承逻辑极不统一：iBooks 可能按父级字号缩放 rt，而 Kindle 则固定为 12px。用百分比会导致拼音在不同设备上忽大忽小、甚至压字或悬空。

推荐用绝对单位：rt { font-size: 11px; line-height: 1; }
必须重置 ruby 的行高：ruby { line-height: 1.6; }，否则多行段落中拼音会挤占下一行空间
禁用 vertical-align 和 margin-top，它们在 EPUB 渲染中不可靠；改用标准属性 ruby-position: over
所有样式需写在 <style></style> 块内，外部 CSS 文件在部分阅读器中会被忽略

动态注入拼音时，`ruby` 结构断裂比样式错位更致命

电子书常需从词典 API 或本地 JSON 批量生成拼音。若用字符串拼接（如 `<ruby><rb>${char}</rb><rt>${pinyin}</rt></ruby>`），遇到汉字含 &、、<code>" 时，DOM 解析立即中断，后续所有 ruby 全部失效。

服务端生成时，必须用 XML 安全方式插入（如 Python 的 xml.etree.ElementTree）
客户端 JS 注入前，先用 DOMPurify.sanitize() 过滤，仅允许 ruby、rb、rt、rp
空拼音字段必须跳过整个 ruby 块，不能留空 <rt></rt>——某些 TTS 引擎会读出“空白注音”
多音字必须人工校对或接入分词词典，ruby 不做上下文判断，“长”字不会自动在“长度”里读 cháng

真正难的不是写出合法结构，而是让同一份 HTML 在 Kindle、iOS Books、Android 阅读器、语音朗读工具里都保持“字-音严格对齐+降级后仍可读”。这要求每层 ruby 都经得起 DOM 校验、CSS 重置、字符转义三重过滤——少一个 rb，少一对 rp，少一次转义，就可能让整页注音在某台设备上彻底失效。