多音字必须人工定音，ruby仅映射结构不解析语义；rb与rt须严格一对一，rp必须前置且顺序正确；CSS仅限调整字体、行高和书写模式，禁用破坏流式布局的属性。
多音字必须手动指定读音，ruby 不会自动判断
浏览器和 HTML 标准不解析语义，ruby 只负责结构映射，不识别“重”在“重庆”里读 Chóngqìng、在“重要”里读 zhòng。你给哪个字标什么音，完全取决于你写的 <rt></rt> 内容。常见错误是直接粘贴整段文字后让工具“自动注音”，结果“长”标成 cháng（实际是 zhǎng）、“发”标成 fā（实际是 fà），全是错的。
实操建议：
- 先通读全文，对存疑字查《现代汉语词典》或权威拼音库（如 Python 的
pypinyin带heteronym=False+ 人工校验） - 避免用“/”分隔多音（如
<rt>fā/fà</rt>），屏幕阅读器无法朗读，也不符合语义规范 - 对教材、儿童读物等场景，建议在
<ruby></ruby>上加data-pinyin属性备用：<ruby data-pinyin="fà">发<rt>fà</rt></ruby>
批量生成时，rb 和 rt 必须严格一对一
动态拼接 HTML 时最容易出错：把一串汉字全塞进 <ruby></ruby>，只配一个 <rt></rt>，比如 <ruby>银行<rt>yín háng</rt></ruby>。这会导致部分浏览器只给“行”标音，或整个结构被忽略——因为规范要求每个基文单位（rb 或裸文本）对应唯一一个 rt。
正确做法是逐字/逐词拆解后分别包裹：
立即学习“前端免费学习笔记（深入）”；
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 单字词：
<ruby>银<rt>yín</rt></ruby><ruby>行<rt>háng</rt></ruby> - 固定词组（需整体读音）：
<ruby>银行<rt>yín háng</rt></ruby>（此时“银行”视为一个语义单位） - JavaScript 批量处理时，用数组 map 而非字符串 replace：
text.split('').map(char => `<ruby>${char}<rt>${pinyinMap[char]}</rt></ruby>`).join('')
旧版 Safari 和 NVDA 屏幕阅读器需要 rp 包裹括号
不加 <rp></rp>，iOS Safari 15 以下、某些 Windows 屏幕阅读器可能直接把拼音当普通文本读出来，或者显示为乱序括号。这不是样式问题，是可访问性失效。
兼容写法必须包含 rp，且顺序不能错：
- 错误：
<ruby>好<rt>hǎo</rt><rp>(</rp><rp>)</rp></ruby>（rp在rt后，部分读屏器跳过） - 正确：
<ruby>好<rp>(</rp><rt>hǎo</rt><rp>)</rp></ruby> - 如果用 JS 动态生成，别漏掉
rp标签，哪怕只是空节点：`<ruby>${char}<rp>(</rp><rt>${py}</rt><rp>)</rp></ruby>`
ruby 的样式微调不能破坏原生布局逻辑
很多人想调高拼音位置或加粗字体，就用 position: absolute 把 rt 提上去，结果导致打印失真、响应式错位、NVDA 朗读顺序混乱。HTML5 的 ruby 是语义容器，它的排版逻辑由浏览器内置渲染引擎控制。
安全可控的 CSS 方式只有这些：
- 改大小和颜色：
rt { font-size: 0.7em; color: #666; } - 调垂直间距：
ruby { line-height: 2; }（增大基线距离，避免遮挡） - 强制横排（防竖排页面干扰）：
rt { writing-mode: horizontal-tb; } - 禁止用
display: block、float、transform等破坏流式布局的属性
ruby 的代码，而是没意识到多音字必须人工定音、rb/rt 数量必须相等、rp 顺序错一位就会让读屏器失效——这些点不提前踩坑，后面调试花的时间远超写代码本身。 
