ruby注音需严格遵循html结构、lang/dir/bdi协同及浏览器兼容性规范，任一环节断裂即导致失效；导出pdf时必须js降级为「汉(hàn)」格式。
ruby 标签在多语种混排网页中不是“写了就显示”，而是极易因 lang、dir、bdi、浏览器内核差异或结构松散直接失效——中文拼音不出现、日文假名错位、阿拉伯文混排时注音被拖拽到行尾，都是常态。
ruby 必须配 rt 才能渲染，且 rt 必须是 ruby 的直接子元素
只写 <ruby>汉</ruby> 浏览器会完全忽略注音逻辑；必须严格满足父子关系：<ruby>汉<rt>hàn</rt></ruby>。常见错误包括：
-
<ruby>汉</ruby><rt>hàn</rt>：rt 脱离父容器，所有现代浏览器均忽略 -
<ruby><span>汉</span><rt>hàn</rt></ruby>：rt 不是直接子元素，Safari 和 Firefox 降级为普通文本 - 用 React/Vue 动态插入时，若
rt被包裹在<template></template>或<div> 中，语义链断裂，屏幕阅读器跳过 <h3>lang 和 dir 必须按内容粒度显式声明，不能只靠 <a style="color:#f60; text-decoration:underline;" title="html" href="https://m.php.cn/zt/15763.html" target="_blank">html</a> lang</h3> <p>根节点 <code>只激活东亚排版引擎，但无法保正文本块内部方向与语音正确。混排场景下必须逐段控制：- 阿拉伯文段落含中文人名：
<p lang="ar" dir="rtl">مرحبا <bdi lang="zh-CN"><ruby>李<rt>lǐ</rt></ruby></bdi></p>——bdi隔离双向算法，lang指定语音规则 - 日文段落里夹汉字注音：
<p lang="ja">東京<ruby>北<rt>きた</rt></ruby>駅</p>，此时:lang(ja) rt需单独设font-size: 0.55em，否则比汉字小得过分 - 误写
lang="zh"或lang="cn"：Firefox/Safari 直接忽略 ruby 语义，当普通内联处理
跨浏览器渲染不一致必须靠内联样式硬控
Chrome 默认
rt缩放约 60%，Safari 约 50%，Firefox 则依赖继承，且三者对line-height处理完全不同。全局 CSS 类易被富文本样式覆盖，推荐直接内联：-
<rt style="font-size: 0.6em; line-height: 1.2;">hàn</rt>—— 避免拼音贴底或上下留白失控 -
<ruby style="line-height: 1.8;"></ruby>—— 强制撑开行高，防止 Firefox 裁掉rt顶部 - 禁用
ruby-position: under：移动端 Safari 完全不支持，只认over（默认） - 不要用
:lang(zh) rt { color: #666; }：Safari 17.4 中伪类不触发，应改用:lang(zh) ruby { color: #666; }+rt { color: inherit; }
导出 PDF 或打印时 ruby 必须降级，没有例外
wkhtmltopdf、Puppeteer、浏览器打印预览均未实现 ruby 布局模块——它们解析到
<rt></rt>就跳过，DOM 都不建。临时加@media print样式无用。- 导出前必须用 JS 遍历所有
ruby，提取rb和rt内容拼成「汉(hàn)」格式并替换节点 - 别用
innerHTML = ...暴力替换：先cloneNode(true)，再用textContent提取基字和拼音，避免 XSS 和结构破坏 - 若服务端生成 PDF，应在模板层就判断 UA 或环境，直接输出降级文本，而非依赖前端 JS
最常被忽略的一点：ruby 渲染不是“CSS 调整就能好”的问题，它是一条从 HTML 结构、lang/dir/bdi 协同、浏览器内核兼容性到导出链路的完整语义链——任一环节断裂，注音就消失或错乱。写完
<ruby><rb>汉</rb><rt>hàn</rt></ruby>只是起点，不是终点。 - 阿拉伯文段落含中文人名：
