多音字必须依语境人工选定单读音标注，禁用“/”分隔；教学需并列时须用多个；动态生成须正则提取汉字块再注音；不可省，须成对，拼音用Unicode声调符，CSS须显式声明ruby-align和font-size。
多音字不能靠一个 <rt></rt> 塞多个读音糊弄过去——浏览器不会自动选，屏幕阅读器会全念出来，用户看到的是混乱信息。
多音字必须人工判断后单读音标注
HTML 的 <ruby></ruby> 不做语义推理，它只忠实地把每个 <rt></rt> 和对应汉字绑定。所谓“多音字标注”，本质是「根据上下文选一个正确读音，再用标准结构呈现」。
- 错误写法：
<ruby>长<rt>cháng/zhǎng</rt></ruby>—— 语音引擎会读成 “cháng slash zhǎng”，语义失效 - 正确做法：查语境，“长度”中用
<ruby>长<rt>cháng</rt></ruby>，“成长”中用<ruby>长<rt>zhǎng</rt></ruby> - 若需并列展示多音（如教学场景），必须拆成多个
<rb></rb>+<rt></rt>并排：<ruby><rb>长</rb><rt>cháng</rt><rb>长</rb><rt>zhǎng</rt></ruby>
动态生成时最常踩的坑：拼音和汉字数量不一致
用 pinyin-pro 或 pypinyin 自动加注，很容易在标点、emoji、全角数字处翻车——这些字符没拼音，但代码仍按字符串长度循环，导致 <rb></rb> 和 <rt></rt> 数量错位，整个 <ruby></ruby> 渲染断裂。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 正确切分逻辑：先用正则
/[\u4e00-\u9fff]+/g提取连续汉字块，对每块逐字调用lazy_pinyin()，非汉字字符原样保留 - 避免直接
text.split('')→ 它会把 emoji 或组合字符（如「ā」）错误切开 - Vue/React 中严禁用
v-html或dangerouslySetInnerHTML拼接未转义字符串，&、会破坏 DOM 结构
样式和兼容性上容易被忽略的硬约束
看似只是加个拼音，但 Safari 16 及更早版本、旧安卓 WebView 对 <ruby></ruby> 的支持极脆弱，漏掉任一环节都可能导致拼音消失或错位。
立即学习“前端免费学习笔记（深入）”；
-
<rb></rb>不能省：Safari 中漏掉<rb></rb>，ruby-align: center失效，拼音飘左/偏移 -
<rp></rp>必须成对且紧邻<rt></rt>：如<rp>( </rp><rt>hàn</rt><rp>)</rp>，否则旧浏览器 fallback 失败 - 拼音必须用半角小写字母 + Unicode 声调符（如
zhōng），禁用数字标调（zhong1）——移动端字体支持差，易错位 - CSS 必须显式设
ruby { ruby-align: center; }，不能依赖默认值；rt { font-size: 0.6em; }也得写死，百分比缩放各浏览器不一致
真正难的不是写对一个字，而是整段混排文本里，每个汉字都得有对应、合法、可访问的 <rb></rb> 和 <rt></rt>，且不能被外部样式或模板引擎悄悄吃掉。一旦出问题，往往不是“不显示”，而是“看起来像对了，但读屏器跳过、打印错位、PDF 导出丢失”。
