多音字必须人工判断语境后手动标注唯一读音，ruby仅负责呈现、不处理逻辑；需用rb明确基线、rt设具体字号，禁用absolute；动态生成须确保结构合规、避免XSS。
多音字在 HTML 中不能靠自动识别，必须人工判断语境后手动指定拼音；ruby 标签本身不处理读音逻辑，只负责把“你认定的读音”准确、可访问地呈现出来。
多音字必须按上下文逐字标注，不能合并或模糊写法
浏览器和屏幕阅读器无法从“否”中知道该读哪个音，这种写法会破坏语义，也违背 W3C 规范对 rt 的“一对一”要求。
- 错误示例：
<ruby>否<rt>fǒu/pǐ</rt></ruby>—— 拼音混排，语音引擎跳过或朗读错误 - 正确做法：根据实际语境选唯一读音，如“否极泰来”中写
<ruby>否<rt>pǐ</rt></ruby> - 若需提示多音可能性（如教学场景），应在
ruby外补充说明，或用data-pinyin属性备用：<ruby data-pinyin="fǒu pǐ">否<rt>pǐ</rt></ruby>
rb 不可省略，否则 Safari 和旧版 Edge 会错位
看似简洁的 <ruby>长<rt>cháng</rt></ruby> 在 Safari 16 及更早版本中，rt 会失去基线锚点，导致拼音左贴、右飘甚至垂直偏移——因为 rb 是浏览器计算对齐位置的必要参照。
- 单字也必须显式包裹：
<ruby><rb>长</rb><rt>cháng</rt></ruby> - 双音节词如“长大”，两个字读音不同，必须拆开：
<ruby><rb>长</rb><rt>zhǎng</rt><rb>大</rb><rt>dà</rt></ruby> - 动态生成时（如 React/Vue），确保
rb是ruby的直接子节点，中间不能插 Fragment 或空格
样式必须协同设置，否则 ruby-align 形同虚设
只写 ruby { ruby-align: center; } 不够，Safari 16 以下默认不生效，Chrome/Firefox 在 RTL 或 text-align: right 下也会失效；更常见的是拼音被截断或上下压叠，根源在 font-size 和 line-height 没配对。
立即学习“前端免费学习笔记（深入）”；
- 全局重置建议：
ruby { ruby-align: center; -webkit-ruby-align: center; line-height: 1.2; } -
rt必须设具体字号：rt { font-size: 0.6em; line-height: 1.2; }（不用百分比，避免缩放偏差） - 禁用
position: absolute覆盖原生布局——它会让屏幕阅读器忽略rt，且响应式下极易错位
动态生成时最容易踩的三个坑
用 pypinyin、pinyin-pro 等库批量加注，结构断裂比样式问题更致命。
- 汉字与拼音数量不一致：遇到 emoji、全角标点、组合字符（如「ā」）时，正则切分要严格，推荐用
re.findall(r'[\u4e00-\u9fff]+|[^\u4e00-\u9fff]+', text)分块处理 -
v-html或dangerouslySetInnerHTML直接拼字符串易 XSS，且 会被转义：错误写法v-html="`<ruby>${char}<rt>${pinyin}</rt></ruby>`" - React 中
<rt></rt>必须是<ruby></ruby>的**直接子节点**，不能包在<span></span>或 Fragment 里，否则语义丢失
最常被忽略的一点：多音字标注不是技术问题，而是语言判断前置任务——没有上下文，再规范的 HTML 结构也救不了读音错误。别指望 JS 库自动猜对“行”在“银行”和“行走”里的读音。
