多音字需为每个读音单独设置对，确保一一对应；lang属性必须为小写短横线格式如zh-CN，否则TTS无法识别中文多音字。
多音字必须拆成独立<ruby></ruby>单元，不能共用一个<rt></rt>
常见错误是把「长」字直接写成<ruby>长<rt>cháng</rt></ruby>，结果在需要同时标注「cháng」和「zhǎng」时，硬塞进同一个<rt></rt>里，比如<ruby>长<rt>cháng/zhǎng</rt></ruby>——这会让屏幕阅读器无法区分对应关系，浏览器渲染时也只当一个注音块处理，换行或缩放后极易错位。
正确做法是让每个读音都拥有自己的<rb></rb>和<rt></rt>，并放在同一层<ruby></ruby>内：
<ruby><rb>长</rb><rt>cháng</rt><rb>长</rb><rt>zhǎng</rt></ruby>
- 每个
<rb></rb>包裹一个原始汉字（哪怕重复），确保基字锚点明确 - 每个
<rt></rt>严格一对一绑定一个<rb></rb>，不可跨字、不可合并 - 避免用空格或斜杠分隔拼音，那只是视觉提示，不构成语义对齐
lang属性没设对，多音字根本不会被识别为中文上下文
如果或缺失、写错（如zh_cn、ZH-CN），VoiceOver/NVDA 就不会加载中文 TTS 引擎，「行长」里的「长」可能全被读成cháng，连多音字判断逻辑都不会触发。
必须检查：
立即学习“前端免费学习笔记（深入）”；
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
-
document.documentElement.lang是否为小写+短横线格式，例如zh-CN（不是zh、Chinese或zh_Hans） - 服务端模板或 SSR 渲染是否在
标签上动态注入了合法值 - SPA 切换语言时，是否同步修改了
document.documentElement.lang而非仅改body
动态生成时<rb></rb>漏写或嵌套断裂，导致注音漂移
用pypinyin或前端框架生成注音 HTML 时，最容易犯的错是：只给拼音加<rt></rt>，却忘了给每个汉字补<rb></rb>。例如 Vue 中这样写：v-html="`<ruby>${char}<rt>${pinyin}</rt></ruby>`"，一旦char含 HTML 特殊字符（如&、），还会引发解析错误甚至 XSS。
安全做法：
- 用正则或 Unicode 字符遍历，确保输入字符串中每个汉字都被
<rb></rb>包裹（包括 emoji、全角标点前后） - 在框架中封装为原子组件，如
<ruby-pair char="重" pinyin="chóng"></ruby-pair>，模板内部固定结构 - React 中确认
<rt></rt>是<ruby></ruby>的**直接子节点**，中间不能有 Fragment 或文本节点
CSS 没配ruby-align: center，多音字注音左右偏移
Safari 16 及更早版本不实现ruby-align默认值，Chrome/Firefox 在text-align: right容器里也会覆盖默认居中。结果就是「长」字的两个<rt></rt>一个贴左、一个飘右，完全不对齐。
必须显式声明：
ruby { ruby-align: center; -webkit-ruby-align: center; }
ruby rt { font-size: 0.6em; line-height: 1; }
ruby { line-height: 1.2; }
-
ruby-align要全局设置，别只加在某个 class 上 -
rb元素不可省略——没有它，ruby-align就失去作用对象 - 只调
font-size不管用，必须协同控制line-height，否则拼音会被挤压变形
<rb></rb>，每个<rb></rb>都要配一个<rt></rt>，所有这些都要在 DOM 层级上严格嵌套，且lang和 CSS 都得兜底配合。漏掉任意一环，错位就不是“看起来不太对”，而是语义失效、语音错读、响应式崩坏。 
