多音字标注必须人工判断上下文并手动指定读音，ruby标签仅负责渲染预设拼音，不识别语义；每个ruby块须一对一映射单个确定读音，禁用斜杠混排；字级与词级标注结构不同，轻声需显式写为无调字母；rp标签是兼容旧环境的关键fallback机制；动态生成时须分词/逐字构建独立ruby块，不可整句拼接。
多音字必须人工判断上下文，不能靠自动拼写
HTML 的 ruby 标签本身不识别语义，也不会查词典或分析句子结构。所谓“多音字标注”，本质是开发者根据上下文手动选对读音，再用结构表达出来。比如“行”在“银行”中读 xíng，在“行列”中读 háng，浏览器不会帮你切换——它只负责把你在 <rt></rt> 里写的那个拼音，稳稳地摆在汉字上方。
常见错误是往一个 <rt></rt> 里塞多个读音，像 <ruby>行<rt>xíng/háng</rt></ruby>。这会导致屏幕阅读器朗读混乱，CSS 排版错位，且违反 HTML 规范中“一对一映射”的要求。
- 每个
ruby块只对应一个确定读音，上下文变了就得换结构 - 若需提示多音可能性，可用
title属性或额外文案说明，如<ruby data-pinyin="xíng|yín|háng">行<rt>xíng</rt></ruby> - 避免用斜杠、顿号、括号混入
<rt></rt>内容——这些字符会被原样渲染，破坏排版和可访问性
单字多音 vs 词级连读，结构写法完全不同
“长”字单独出现时，无法确定读音；但放在“长度”或“成长”里，语义锁定后就只能标一种。这时你要决定：是按字注音（强调本音），还是按词注音（反映实际读法）。两种都合法，但结构不同，影响渲染与语音输出。
- 字级标注（逐字标本音）：
<ruby>长<rt>cháng</rt></ruby><ruby>度<rt>dù</rt></ruby> - 词级标注（整体标口语读音）：
<ruby>长度<rt>chángdù</rt></ruby>（注意中间无空格，用 Unicode 声调符） - 轻声必须显式写出不带调字母，如“妈妈”应为
<ruby>妈<rt>mā</rt></ruby><ruby>妈<rt>ma</rt></ruby>，不是má或mǎ
rp 标签不是装饰，旧环境不加它拼音会裸奔
如果你的项目仍需兼容 Android 4.x WebView、IE9 或某些定制内核，漏掉 <rp></rp> 就等于放弃 fallback。现代浏览器会隐藏 <rp></rp> 内容，只显示 <rt></rt>；而老环境则把 <rt></rt> 当普通文本丢弃，只留下汉字——除非你用 <rp></rp> 把拼音包进括号里。
立即学习“前端免费学习笔记（深入）”；
- 标准写法必须成对且紧邻：
<ruby>否<rp>(</rp><rt>pǐ</rt><rp>)</rp></ruby> - 括号类型可换（如【】），但前后必须一致，且不能用全角符号
- 如果明确不支持 IE/Android 4.x，可省略
<rp></rp>，但别误以为它是“样式辅助”——它是语义降级的关键开关
动态生成拼音时，最易踩的坑是结构错位
用 pinyin-pro 或 pinyin-js 自动加注时，很多人直接把整个句子的拼音数组拼成字符串塞进一个 <rt></rt>，结果所有拼音堆在第一个字头上。正确做法是：先分词或逐字切开，再为每个汉字/词生成独立的 ruby 块。
- 不要：
<ruby>重庆火锅<rt>Chóngqìng huǒguō</rt></ruby>（错位，语义模糊） - 要：
<ruby>重庆<rt>Chóngqìng</rt></ruby><ruby>火锅<rt>huǒguō</rt></ruby>（词级） - 或：
<ruby>重<rt>chóng</rt></ruby><ruby>庆<rt>qìng</rt></ruby><ruby>火<rt>huǒ</rt></ruby><ruby>锅<rt>guō</rt></ruby>（字级） - 动态插入前务必校验 DOM 结构是否闭合，避免
<rt></rt>被父元素截断或嵌套错误
ruby 只忠实地执行你给它的答案。 
