标签必须包含子元素,否则整个块被忽略;须为直接子元素,只能在内且内容仅为括号;多字注音需逐字独立包裹,不可共用。

ruby 标签必须配 rt,否则整个块被忽略
只写 <ruby>汉</ruby> 是无效的——浏览器会跳过整个 <ruby></ruby> 块,文字照常显示,但拼音彻底消失。原因在于 <rt></rt> 是必需子元素,不是可选装饰。没有 <rt></rt>,<ruby></ruby> 就不具备语义,现代浏览器直接丢弃该结构。
常见错误包括:
• 服务端渲染时拼音为空,却仍输出空 <rt></rt>(屏幕阅读器可能读作“空白注音”)
• 把 <rt></rt> 放在 <span></span> 或 <div> 里,导致嵌套层级错误(<code><rt></rt> 必须是 <ruby></ruby> 的**直接子元素**)
rp 标签只能嵌在 rt 内部,且内容必须是纯括号
<rp></rp> 不是“加括号就完事”,它有硬性位置和内容约束:只能出现在 <rt></rt> 的开头或结尾,且里面只能是 (、)、[、] 等纯括号字符,多一个空格或字母都会导致 fallback 失效。
✅ 正确:<rt><rp>(</rp>hàn<rp>)</rp></rt>
❌ 错误:<rp>(</rp><rt>hàn</rt><rp>)</rp>(<rp></rp> 在 <rt></rt> 外,被忽略)
❌ 错误:<rt><rp>( </rp>hàn</rt>(含空格,部分浏览器不触发 fallback)
Chrome 会渲染 <rp></rp> 导致括号可见,Safari 则隐藏它。生产环境推荐服务端按 UA 移除 <rp></rp>,或用 CSS 强制隐藏:rp { display: none; }。
多字注音必须逐字独立包裹 ruby,不能共用 rt
常见错误是把多个汉字塞进一个 <ruby></ruby> 再配一个 <rt></rt>,比如:<ruby>汉字<rt>hàn zì</rt></ruby>。这会导致 Safari 渲染错位(对空格和换行更敏感),且语义不准确——每个汉字应有对应拼音。
正确写法是逐字嵌套:<ruby>汉<rt>hàn</rt></ruby><ruby>字<rt>zì</rt></ruby>。
• 不能嵌套另一个 <ruby></ruby>
• 不能跨字共享 <rt></rt>
• 推荐显式使用 <rb></rb> 包裹基字(如 <rb>汉</rb>),提升语义清晰度与解析稳定性
旧浏览器降级效果依赖 rp + rt 的严格配对,而非 UA 判断
<rp></rp> 的作用不是“告诉浏览器这是旧版”,而是靠浏览器是否支持 <ruby></ruby> 来决定是否隐藏它。支持的浏览器会隐藏 <rp></rp> 内容;不支持的(如 IE8–10、早期 Android WebView)则将其作为普通内联元素渲染,显示为括号。
因此,降级是否生效,取决于:
• <rt></rt> 是否存在且位置正确
• <rp></rp> 是否成对、紧贴 <rt></rt> 内部、内容仅为括号
• 没有额外空格、换行或不可见字符混入
真正容易被忽略的是:即使写了 <rp></rp>,如果 <rt></rt> 缺失或嵌套错误,整个 <ruby></ruby> 块会被忽略,降级路径根本不会触发——括号不会出现,拼音也不会显示,用户只看到裸字。











