ruby标签在多语种词典中必须配合lang和bdi使用，否则中文拼音、日文假名、韩文谚文会互相干扰；rb不可省略，导出PDF时需JS降级替换rt内容。
ruby 标签在多语种词典网页里不能直接复用单语结构，否则中文拼音、日文假名、韩文谚文会互相干扰，注音错位、屏幕阅读器读错、打印导出消失——根本原因是浏览器按 lang 和 ruby 的语义链联动渲染，不是“写了就显示”。
多语言混排时 ruby 必须配合 lang 和 bdi 使用
词典页面常出现「أحمدruby 不加控制，Safari 会把拼音 “lǐ” 拖进阿拉伯文字流右侧，Chrome 可能垂直偏移，屏幕阅读器则用阿拉伯语引擎读拼音。必须显式隔离方向和语音：
-
<bdi><ruby lang="zh-Hans"><rb>李</rb><rt>lǐ</rt></ruby></bdi>——bdi阻断 RTL 影响，lang="zh-Hans"锁定语音规则 - 禁止给
bdi加dir属性：<bdi dir="auto">是冗余的，bdi默认就是dir="auto"且带unicode-bidi: isolate - 多个语言块并列时，每个
ruby都要独立设lang，不能靠父级<html lang="zh-CN">继承——Firefox/Safari 会降级为普通内联元素
rb 不可省略，否则 Safari 和安卓 WebView 注音错位
很多人写 <ruby>汉<rt>hàn</rt></ruby>，在 Chrome 看似正常，但 Safari 17.4+ 和部分 Android WebView 会把拼音贴在字右侧甚至合并到下个字上。现代规范要求基字必须由 rb 显式包裹：
- 正确：
<ruby><rb>汉</rb><rt>hàn</rt></ruby> - 错误：
<ruby>汉<rt>hàn</rt></ruby>（缺失rb，语义锚点丢失） - 多音字如“长”，必须按上下文手动拆开：
<ruby><rb>长</rb><rt>cháng</rt></ruby>度vs生<ruby><rb>长</rb><rt>zhǎng</rt></ruby>，ruby 不解析语义
导出 PDF 或打印时 rt 内容消失，必须 JS 降级替换
wkhtmltopdf、Puppeteer、浏览器打印预览均不实现 ruby 布局模块，遇到 <rt> 直接跳过 DOM 构建，结果是“汉”字有、“hàn”拼音无。不能靠 CSS 修复，必须运行时生成 fallback 文本：
立即学习“前端免费学习笔记（深入）”；
- 遍历所有
ruby节点，提取rb.textContent和rt.textContent，拼成"汉(hàn)" - 别用
innerHTML = ...暴力替换，先node.cloneNode(false)，再用textContent安全拼接，防 XSS - 仅在触发导出/打印前执行，日常浏览仍保留原
ruby结构以保障语义和可访问性
连续多个 ruby 在 iOS Safari 上出现微小间距异常
词典常用「一ruby 间插入不可见空隙，导致视觉断连。这不是 bug，是渲染引擎对 inline 元素 baseline 计算的细微差别：
- 父容器设
font-size: 0，子元素ruby单独重设字号（如font-size: 16px），消除继承间隙 - 避免用
margin或letter-spacing强行拉近——缩放或换字体后立刻失效 - 禁用
ruby { display: inline-flex }：破坏语义，屏幕阅读器无法识别注音关系
真正难的不是写对结构，而是每次新增一个词条，都要同步检查 rb 是否包裹、lang 是否匹配、bdi 是否隔离、导出逻辑是否覆盖——漏掉任意一环，多语种词典就从“专业工具”变成“视觉幻觉”。
