多音字必须逐字拆解、一对一绑定rb和rt，不可将多音塞入同一rt；rb标签不可省略，否则Safari对齐失效；动态生成需过滤非汉字字符并确保rb与rt数量匹配。
多音字不能靠一个 <ruby></ruby> 套住整个词再塞多个拼音——必须按实际读音逐字拆解、一对一绑定 <rb></rb> 和 <rt></rt>，否则屏幕阅读器会跳过、CSS 对齐失效、Safari 渲染错位。
为什么「长」字不能写成 <ruby>长<rt>cháng/zhǎng</rt></ruby>
这种写法把两个读音塞进同一个 <rt></rt>，语义上等于告诉浏览器“这个字同时读两种音”，但语音合成器无法选择，屏幕阅读器通常只朗读第一个音或直接跳过。更严重的是，<rt></rt> 必须与单个基字形成明确锚点，混写会导致 Safari 和旧版 Edge 完全丢失对齐逻辑，拼音可能飘到字左侧或换行错位。
正确做法是人工判断上下文后，只保留该语境下的唯一读音：
- 「长度」→
<ruby><rb>长</rb><rt>cháng</rt></ruby> - 「长大」→
<ruby><rb>长</rb><rt>zhǎng</rt></ruby> - 若需并列展示多音（如教学对比），用两个独立
<ruby></ruby>并排：<ruby><rb>长</rb><rt>cháng</rt></ruby><ruby><rb>长</rb><rt>zhǎng</rt></ruby>
rb 标签不是可选的，它是 Safari 对齐生效的前提
Safari 16 及更早版本（包括大量 iOS WebView）不实现 ruby-align: center 的默认行为，且当 <rb></rb> 缺失时，<rt></rt> 会失去基线锚点——结果就是拼音左贴汉字、垂直偏移、甚至整行错位。这不是样式问题，是渲染引擎根本找不到对齐依据。
立即学习“前端免费学习笔记（深入）”；
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
实操必须每字套 <rb></rb>，哪怕单字也不省略：
- 错误：
<ruby>重<rt>chóng</rt></ruby>（Safari 中拼音常左偏） - 正确：
<ruby><rb>重</rb><rt>chóng</rt></ruby> - 两字词如「苹果」必须拆开：
<ruby><rb>苹</rb><rt>píng</rt><rb>果</rb><rt>guǒ</rt></ruby>
动态生成时最容易崩的三个点
用 pinyin-pro 或 pypinyin 批量加注时，结构断裂比样式错乱更致命：
-
非汉字字符未过滤：遇到数字、英文、标点就调
lazy_pinyin()，返回空列表，导致<rb></rb>和<rt></rt>数量不匹配。必须先正则切块：re.findall(r'[\u4e00-\u9fff]+|[^\u4e00-\u9fff]+', text)，只对汉字块处理 -
Vue/React 中 v-html 或 dangerouslySetInnerHTML 拼字符串：若原始汉字含
&或，会破坏 DOM 结构。应封装为组件，props 传纯文本，模板固定结构：<code><ruby-pair :char="'长'" :pinyin="'zhǎng'"></ruby-pair> -
React 中插入 Fragment 或空格：
<rt></rt>必须是<ruby></ruby>的**直接子节点**，中间插>或空格，语义即失效，读屏软件识别不到注音
轻声、儿化、变调不能靠自动推断，得手动写准
<ruby></ruby> 不做语音规则计算，只忠实地呈现你给的内容。常见误区：
- 「我们」不能标
wǒ mén，必须按实际读音写wǒ men（第二个字轻声，不带调号） - 「花儿」标
huār，不是huā ér；「一会儿」标yí huìr，不是yī huì ér - 「一」在去声前变调为
yì（如「一个」→yí gè），必须人工判断后填入，库不会自动改
最易被忽略的是：拼音里的声调符号（如 ā）必须用 Unicode 字符，不能写成 a1，否则字体不支持时显示为方框，且 Safari 对 font-size 缩放行为会异常。
