多音字注音必须人工判断语境后手动指定拼音，HTML ruby 标签不识别语义，无法自动推断读音；需按词义边界拆分标注，以《现汉》分词为准，严格遵循 HTML 语义约束与 rp/rt 结构规范。

多音字必须人工判断语境后指定拼音

HTML 的 ruby 标签本身不识别语义，也不做分词或读音推断。所谓“多音字注音”，本质是开发者根据上下文手动选择正确读音并写死在 rt 中。浏览器不会、也不能帮你判断“长”该读 cháng 还是 zhǎng。

常见错误是试图用 JS 自动查字典或调用拼音 API 做“智能标注”，结果在“行长”“长度”中全标成 zhǎng 或全标成 cháng，反而造成误读。

• 必须逐词审读：例如“发”在“发展”中读 fā，在“头发”中读 fà，不能只看单字
• 不能依赖输入法或 Word 的自动注音——它们常出错，且未考虑语境（如“重”在“重要”中读 zhòng，在“重复”中读 chóng）
• 若同一页面存在多个语境下的同一多音字（如既出现“好学”，又出现“好人”），需分别标注，不可复用同一组 ruby 模板

多音字标注要拆到最小语义单位，不是按字切

拼音标注的颗粒度取决于词义边界，不是机械地“一个字一套 ruby”。比如“中”在“中国”里读 zhōng，但在“中间”里仍读 zhōng；而“行”在“银行”里读 háng，就必须和“银”绑定为一个注音单元，不能拆成 银<rt>yín</rt> + 行<rt>háng</rt> 单独处理——否则语义断裂，屏幕阅读器会误读为两个孤立音节。

• 推荐以《现代汉语词典》分词为准：如“中华人民共和国”应拆为“中华/人民/共和国”，每词独立套 ruby
• 专有名词优先整体处理：“乌鲁木齐”不拆字，“乌wū鲁lǔ木mù齐qí”是错的；正确是按音节单位切分并尊重实际连读，标为“乌鲁wū lǔ木mù齐qí”也不对，标准应是“乌wū鲁lǔ木mù齐qí”（四音节逐字，因无轻声与变调）
• 轻声字必须显式写出不带调号的拼音，如“妈妈”标为 妈<rt>mā</rt>妈<rt>ma</rt>，不能写 ma1 或 má

动态生成时最容易漏掉的三件事

用 JS 生成带多音字的 ruby 结构时，90% 的失败源于忽略底层 HTML 语义约束，而非逻辑错误。

DeepBI DHTML 页面生成器

生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur

下载

立即学习“前端免费学习笔记（深入）”；

• rt 必须是 ruby 的直接子元素，不能包在 span 或 div 里——ruby>span>rt 是无效结构，拼音不渲染
• 拼音字符串必须用半角小写字母 + Unicode 声调符（如 ā、é），禁用数字标调（如 zhu1）或全角空格，否则 CSS 排版错位、iOS VoiceOver 朗读异常
• 每个 ruby 单元必须含且仅含一个基字（或一个词）+ 一个 rt + 成对 rp（如 <rp>(</rp><rt>hàn</rt><rp>)</rp>），少一个标签，旧浏览器 fallback 就失效

rp 标签不是可有可无的兼容补丁

很多开发者以为加了 rp 只是为了“让老浏览器看起来不那么丑”，其实它承担着关键的降级语义：没有 rp，IE8– 或某些定制 WebView 会把 rt 当作普通文本直接拼在汉字后面，变成“汉hàn”，完全破坏可读性。

真实场景中，哪怕只支持 Chrome/Firefox/Safari，也建议保留 rp——因为部分企业内网系统、政务终端、教育平板仍运行老旧内核，且这些环境往往更需要拼音辅助阅读。

• rp 必须成对出现，且紧邻 rt：顺序只能是 <rp>(</rp><rt>hàn</rt><rp>)</rp>
• 括号内容必须是 ASCII 字符，不能用中文括号（“（”“）”）或全角符号
• 现代浏览器自动隐藏 rp，无需 CSS 干预；但若用 display: none 强制隐藏，可能影响某些读屏软件的解析顺序

多音字标注最耗时的环节从来不是写代码，而是确认每一个字在当前语境下的唯一正确读音——这没法交给浏览器，也没法靠正则或词典 API 完全替代人工校对。