ruby标签必须嵌套rb与rt才生效，单独使用rt无效；基文须用rb显式包裹，rb与rt须一一对应、顺序严格；多字需分组独立ruby，不可合并；声调用unicode预组合字符；动态生成时须确保rb包裹；旧浏览器需rp降级。
ruby 标签必须嵌套 rb + rt 才能生效
单独写 <ruby>汉<rt>hàn</rt></ruby> 是无效的——浏览器会忽略 <rt></rt>，或把拼音平铺在汉字后面。HTML 规范要求基文（汉字）必须显式包裹在 <rb></rb> 里，且 <rb></rb> 和 <rt></rt> 必须一一对应、顺序严格。
正确结构只能是：
<ruby><rb>汉</rb><rt>hàn</rt></ruby>
-
<rb></rb>不可省略，不能用普通文本或<span></span>替代 - 多个字必须各自独立套一层
<ruby></ruby>，比如“中国”要写成两组，不是一组<rb>中国</rb><rt>zhōng guó</rt> - 如果中间插入换行、空格或块级标签（如
<div>），会中断语义关联，导致渲染失败 <h3>多音字和词组必须人工拆字标注</h3> <p><code><ruby></ruby>不识别上下文，不会自动选音。“长”在“长江”读cháng，在“长辈”读zhǎng，你填什么就显示什么。词组如“重庆”也不能靠一个<rt></rt>覆盖两个字——否则拼音会挤在一起、声调错位、CSS 无法单独控制每个字的注音样式。推荐做法：
- 按字拆开：
<ruby><rb>重</rb><rt>chóng</rt></ruby><ruby><rb>庆</rb><rt>qìng</rt></ruby> - 声调用 Unicode 预组合字符（如
ā、ǚ），不要用组合符（ǘ），后者在部分字体/浏览器中渲染不稳定 - 避免把整句拼音塞进一个
<rt></rt>，比如<rt>wo men dou shi you xiu de ren</rt>—— 这会导致语音合成工具（TTS）无法按字切分，朗读错误
动态生成拼音时容易漏掉 DOM 结构校验
用 JavaScript 拼接字符串生成
<ruby></ruby>时，常见错误是直接拼"<ruby>" + char + "<rt>" + pinyin + "</rt></ruby>"，结果产出的是<ruby>汉<rt>hàn</rt></ruby>—— 缺少<rb></rb>，结构非法。正确做法必须保证每个字都被
<rb></rb>包裹：- 用模板字符串显式写出
<rb>${char}</rb> - 不要依赖拼音库自动补结构，例如
pinyin-pro的pinyin()只返回字符串，不生成 HTML - 输入法组合输入（如中文输入法打字过程中的“正在输入”状态）会触发
compositionstart/compositionend，需拦截，否则未完成的字会提前被标注
旧浏览器 fallback 要用 rp，但现代项目可省略
IE 全系、Android 4.3 WebView、Outlook Desktop 等完全不解析
<ruby></ruby>，它们会丢弃<rt></rt>和<rp></rp>，但保留其中的文本内容。所以加<rp>(</rp>和<rp>)</rp>后，在降级场景下能变成“汉(hàn)”，比“汉hàn”可读性高。不过当前（2026 年）主流环境已基本支持
<ruby></ruby>，是否加<rp></rp>取决于目标用户：- 面向教育类网站、政务系统等仍需兼容 IE 或老旧邮件客户端 → 加
<rp></rp> - 纯现代 Web 应用（Chrome/Firefox/Safari 最新版 + iOS/Android 主流 WebView）→ 可省略，减少冗余标签
- 注意 Safari 对连续多个
<ruby></ruby>的行内间距处理异常，必要时用font-size: 0父容器 + 子元素重设字号微调
- 按字拆开：
