根本原因是浏览器仅在等特定语言环境下启用ruby布局引擎,若lang属性缺失、错误或未全局更新,则rt标签被当作普通文本处理,CSS样式无效。

ruby 标签里多音字没显示拼音,大概率不是代码写错了,而是浏览器压根没把它当注音结构来解析——尤其在动态插入、语言切换或混排场景下,ruby 会直接退化成普通内联元素。
为什么多音字标注后 rt 完全不渲染
根本原因常被忽略:浏览器只在 (或 ja、ko)环境下才启用 ruby 布局引擎。如果页面初始是 lang="en",或者 JS 切换语言时只改了某个 div 的 lang 属性而没同步更新 document.documentElement.lang,那所有 rt 都会被当成普通文本流处理,CSS 里的 font-size: 0.6em 也无效。
- 检查
标签的lang属性是否为zh-CN、zh-TW或ja,不能是zh或空值 - 用 JS 动态切换语言时,必须执行
document.documentElement.lang = "zh-CN",只改子元素没用 - Safari 和 Firefox 对此最敏感;Chrome 虽能显示,但屏幕阅读器仍跳过
rt
ruby 多音字写法本身是否合法
HTML 不管读音对不对,只认结构。所谓“多音字标注”,本质是人工决策该标哪个音——ruby 本身不支持条件渲染或自动变调。你得自己决定:
- 单字多音(如“行”):按上下文选一个音,
<ruby>行<rt>xíng</rt></ruby>或<ruby>行<rt>háng</rt></ruby>,不能塞两个rt - 词级标注(如“银行”读 yín háng,“行走”读 xíng zǒu):整个词包一层
ruby,<ruby>银行<rt>yín háng</rt></ruby> - 需要同时展示两种读音?只能用额外 DOM,比如加
title或悬浮提示,ruby不支持一对多rt
CSS 没生效导致 rt 看不见的典型配置漏项
即使结构和 lang 都对了,rt 还是隐形或叠在字上,八成是 CSS 缺关键声明:
立即学习“前端免费学习笔记(深入)”;
-
ruby rt必须显式设font-size,默认值是继承父级,结果拼音和汉字一样大,视觉上“看不见” - 加
ruby { line-height: 2; }或ruby rt { margin-top: -0.3em; },否则小字号拼音会被行高挤压消失 - 避免用
position: absolute调位置——破坏可访问性,且 Safari 下容易错位 - 移动端窄屏时,若多音字在词尾(如“重”在“重庆”末尾),需外层加
white-space: nowrap防止断行错位
导出 PDF 或打印时拼音彻底消失
这不是 bug,是现实限制:wkhtmltopdf、Puppeteer 和浏览器原生打印预览,全部不实现 ruby 布局模块。它们解析到 <rt></rt> 就跳过,DOM 都不建。
- 导出前必须用 JS 遍历所有
ruby,提取rb(或直接文本)和对应rt内容,拼成“重(chóng)”这类降级文本 - 别用
innerHTML替换,先cloneNode(true),再用textContent分别取汉字和拼音,保证语义不丢 - 如果用 Playwright 生成 PDF,记得关掉
printBackground: false这类干扰项,它不影响ruby渲染,因为压根不支持
真正卡住人的地方,往往不在“怎么标多音字”,而在“标完之后谁还看得见”——lang 属性、CSS 基础声明、导出链路这三环,漏一环,前面所有拼音都白写。



















