多音字拼音标注必须人工判断语境并逐字精确标注，不可依赖自动分词或高频读音；需严格遵循ruby一对一结构、正确使用rp括号兼容旧环境，并确保轻声、变调等按规范原貌表达。
多音字必须人工判断语境，不能靠自动分词猜读音
浏览器和 ruby 标签本身不理解语义，否 在“否极泰来”里读 pǐ，在“是否”里读 fǒu，自动标注库（如 pinyin-pro）默认按高频音输出，大概率出错。你得自己查《现代汉语词典》或上下文逻辑，再手动写进 <rt></rt>。
常见踩坑点：
- 把拼音写成
fǒu/pǐ塞进一个<rt></rt>—— 屏幕阅读器会朗读全部，语义混乱 - 依赖 JS 库批量加注却没做人工复核 —— 特别是成语、专有名词、古文用法（如“长”在“长歌当哭”中读
cháng） - 用
data-pinyin或title当主力标注 —— 这些不被屏幕阅读器主动识别，仅作后备
每个字单独套 ruby，禁止跨字合并拼音
哪怕是一个词，也必须逐字拆开、一对一包裹。例如“中华人民共和国”，不能写成：
<ruby>中华人民共和国<rt>zhōng huá rén mín gòng hé guó</rt></ruby>
正确写法是按语义单位或单字切分，比如：
立即学习“前端免费学习笔记（深入）”；
<ruby>中<rp>( </rp><rt>zhōng</rt><rp> )</rp></ruby><ruby>华<rp>( </rp><rt>huá</rt><rp> )</rp></ruby><ruby>人<rp>( </rp><rt>rén</rt><rp> )</rp></ruby>…
理由很实际：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
-
ruby的渲染逻辑只认“基字 + 紧邻rt”这一对一关系，跨字会导致拼音悬空或错位 - 竖排时，跨字拼音会挤到整行右侧，完全不可读
- 轻声、变调（如“你好”的“好”读
hǎo，但“你好啊”的“好”常读hao）必须靠单字控制，无法统一处理
轻声、儿化、变调要用拼音原貌表达，不靠 CSS 或 JS 补救
拼音不是装饰，是语音线索。轻声不标调号（ma 而非 mā），儿化直接写 r（huār 而非 huā ér），上声变调（如“你好”的“你”实际读 nǐ → ní）除非教学需要，否则仍标本调 nǐ —— 因为 ruby 是标注“字音”，不是“语流音变”。
容易忽略的细节：
- 混入全角空格或中文顿号（、）进
<rt></rt>，Safari 会截断整个拼音 - 用数字标调（
ni3）虽能工作，但移动端字体支持差，推荐 Unicode 声调符（nǐ），且确保页面<meta charset="UTF-8">已声明 - 不要给
rt加position: absolute微调位置 —— 会破坏可访问性，NVDA 和 VoiceOver 将无法定位注音
旧环境 fallback 必须靠 rp 成对包裹括号，不能省略
如果你的项目还要跑在 Android 4.4 WebView 或某些政企定制内核里，rp 不是可选项。写成这样：
<ruby>长<rp>( </rp><rt>zhǎng</rt><rp> )</rp></ruby>
现代浏览器隐藏 rp，只显示“长zhǎng”；老环境则显示“长(zhǎng)”，至少可读。漏掉 rp，老环境直接丢弃 rt，只剩光秃秃的“长”，用户完全不知道该念啥。
注意两个硬约束：
-
rp必须成对，且紧贴rt两侧，顺序不能颠倒 - 括号类型要一致（不能左圆右方），但可以是
【】或〔〕，只要字体能正常渲染
真正难的从来不是怎么写标签，而是每个字背后得有人去翻词典、查语境、校验声调——机器标不出“行”在“银行”和“行动”里的区别，这一步绕不开。
