ruby必须显式包裹rb和rt才能生效，缺一不可；多字须逐字拆分并一一对应；rp需成对用于降级兼容；CSS仅限line-height和font-size微调，禁用position等破坏语义的属性。
直接用 ruby 标签做汉字注音，不是“加个拼音”那么简单——它在自定义排版系统里是语义锚点，不是视觉装饰。结构错一个 rb，整段拼音就失效；CSS 少一行 line-height，Firefox 里拼音就压字；导出 PDF 时没 fallback，打印出来只剩光秃秃的汉字。
为什么 ruby 必须显式包裹 rb 和 rt
浏览器只认 rb+rt 这一对组合。写成 <ruby>汉<rt>hàn</rt></ruby> 看似省事，但 Chrome 115+、Safari 17.4+ 会降级为普通内联流，拼音贴在字右侧甚至被截断。原因很简单：rt 没有基字锚点，语义丢失。
-
rb不可省略，必须显式包裹每个被注音汉字，不能用纯文本替代 -
rt必须紧跟对应rb，不能跨rb共享（比如两个rb后跟一个rt） - 多字必须拆开：正确是
<ruby><rb>重</rb><rt>chóng</rt></ruby><ruby><rb>庆</rb><rt>qìng</rt></ruby>，错误是<ruby>重庆<rt>chóng qìng</rt></ruby> - 若需兼容老旧 WebView 或邮件客户端，
rp要成对出现：<rp>(</rp><rt>hàn</rt><rp>)</rp>，否则降级后可能裸露 “hàn”
ruby 在 CSS 排版中哪些样式动不得
想靠 margin-top 或 position: absolute 把拼音往上拉？这是最常见也最危险的操作。它绕过浏览器内置的 ruby 布局引擎，缩放、换字体、竖排时必然偏移，且破坏屏幕阅读器识别。
- 必须设
ruby { line-height: 1.8; }，防止 Firefox/Safari 中拼音被行高挤压或重叠 - 必须设
rt { font-size: 0.65em; line-height: 1; }，不依赖浏览器默认的 50% 缩放，避免字号失控 - 优先用标准属性：
rt { ruby-position: over; }（默认值，但显式声明更稳）、ruby { ruby-align: center; } - 禁用：
rt { position: absolute; }、ruby { display: block; }、ruby { float: left; }——这些会切断语义流
动态生成 ruby 结构时最容易漏掉的三件事
用 pinyin-pro 或自研 JS 拆字转拼音再拼 HTML，看似一步到位，实际落地常崩在细节上。
立即学习“前端免费学习笔记（深入）”；
- 没过滤标点和空格：
rb内容为空（如用户输入含\n或全角空格），DOM 结构断裂，渲染异常 - 拼音格式不统一：库返回
ni3 hao3，但显示需要带声调符号的nǐ hǎo，否则字体不支持时显示乱码 - HTML 注入风险：Vue 的
v-html或 React 的dangerouslySetInnerHTML直接拼字符串，一旦char是<div>或含&，整个 DOM 就被破坏 - 正确做法：封装组件（如
<RubyText :char="c" :pinyin="p" />），或用DOMPurify.sanitize(html, { ALLOWED_TAGS: ['ruby', 'rb', 'rt', 'rp'] })过滤后再注入
真正难的不是写出能看的拼音，而是让每个 rt 都精准钉在对应 rb 上，且在 Safari 的老 iPad、Firefox 的高分屏、wkhtmltopdf 的 PDF 导出里都不偏不漏——这要求你把 ruby 当作语义容器来维护，而不是当 div 来摆弄。
