多音字需人工指定唯一正确读音,不可堆叠;ruby须一对一单字标注,强制包含rp括号,禁用破坏基线的CSS。

多音字必须人工指定读音,不自动判断上下文
浏览器不会根据前后字推测“长”该读 cháng 还是 zhǎng,“行”该读 xíng 还是 háng。你写什么,它就渲染什么。ruby 只负责结构表达,不参与语义解析。所以标注前得先查证——比如“重庆”的“重”在地名中固定读 Chóngqìng,不是 Zhòngqìng。
常见错误是把多个读音堆进一个 rt 里:<ruby>重<rt>chóng/zhòng</rt></ruby>。这会导致语音合成器卡住、屏幕阅读器跳读、CSS 样式错乱。正确做法是只保留当前语境下唯一正确的读音。
- 查《现代汉语词典》或权威地名/人名读音库确认首选音
- 遇到教学场景需对比多音,用多个独立
ruby块 + 文字说明,例如:<ruby>长<rt>cháng</rt></ruby>(长度)<ruby>长<rt>zhǎng</rt></ruby>(成长) - 避免用
data-pinyin或注释替代rt——这些对读屏软件无效,也不触发 ruby 排版逻辑
单字标注必须一对一,不能跨字符合并
ruby 的基本单元是「一个汉字 + 一个 rt」。哪怕两个字本是一个词,只要你想标本音(而非词音),就得拆开。比如“一”在“一个”中变调为 yí,但单独作为字级注音时,应标本调 yī;而“一会儿”的“一”必须标 yī,因为这里是轻声前的原调。
错误写法:<ruby>一会儿<rt>yī huì ér</rt></ruby> —— 汉字 3 个,拼音 3 个音节,但结构上没对齐,浏览器无法保证每个拼音对应哪个字。
立即学习“前端免费学习笔记(深入)”;
- 逐字符处理:用
pypinyin.lazy_pinyin()获取每个 Unicode 字符对应的拼音,再 zip 对齐 - 跳过非汉字字符(数字、英文字母、标点),不生成
ruby,否则rb/rt数量错位 - emoji、组合字符(如带声调的 ā)要小心:它们算一个字符,但 pypinyin 可能不识别,建议预过滤或 fallback 到空
rt
rp 标签不是可选装饰,旧环境不加会丢拼音
在 iOS Safari 15.4 之前、Android WebView 4.3、部分政务内网浏览器中,rt 会被直接忽略。如果没有 rp,用户看到的就是裸汉字,拼音完全不可见。这不是样式问题,是 DOM 渲染逻辑差异。
标准写法必须成对且紧邻:<ruby>否<rp>( </rp><rt>pǐ</rt><rp> )</rp></ruby>。现代浏览器会隐藏 rp 内容,只显示拼音;老浏览器则显示为「否(pǐ)」。
- 不要省略
rp,尤其面向教育、政务、老年用户场景 -
rp必须包裹括号符号,不能是空格或中文全角括号 - 避免在
rp和rt之间插入换行或空格,某些解析器会因此中断匹配
CSS 控制 ruby 排版时最易踩的坑
ruby-align: center 看似合理,但实际会让拼音偏左或偏右,尤其在等宽字体或中英文混排时。更稳的方式是依赖浏览器默认对齐(多数现代引擎已优化),仅微调 font-size 和 line-height。
致命错误是给 ruby 设 line-height: 2 或 vertical-align: top —— 这会破坏基线对齐,导致拼音悬浮、汉字下沉、多行文本错位。
- 优先用
ruby { font-size: 1em; }和rt { font-size: 0.7em; }控制比例 - 禁用
display: inline-block或float在ruby上,会切断注音流式布局 - 响应式场景下,用
clamp()控制rt字号,避免小屏拼音挤成一团
ruby 结构一旦生成,就不再具备语义回溯能力——它只是“你告诉浏览器怎么排”,不是“浏览器帮你理解怎么读”。



















