多音字标注须先分词，不能字对字硬套；“重庆”应标为词级读音Chóngqìng，而非单字本音chóng/qìng；HTML中ruby支持单字、词级、语境变调三种合法结构。
多音字标注必须先分词，不能字对字硬套
直接给每个汉字加 ruby 标注，会把“重庆”标成“重(chóng)庆(qìng)”，但实际读音是 Chóngqìng——这是词级读音，不是单字本音。浏览器不自动分词，也不查《现代汉语词典》，你得自己决定“这里是词还是字”。常见错误是拿输入法拼音直接贴上去，比如把“银行”标成“银(yín)行(háng)”，而作为机构名应读“yín háng”，作动词才读“yǐn xíng”。
用 ruby 标注多音字的三种合法结构
HTML 的 ruby 不强制要求一对一，关键看语义层级：
- 单字本音（教学/字典场景）：
<ruby>重<rt>chóng</rt></ruby> - 词级固定读音（地名、专有名词）：
<ruby>重庆<rt>Chóngqìng</rt></ruby> - 语境变调（如“一”“不”）：
<ruby>一个<rt>yí gè</rt></ruby>，不能拆成两个ruby，否则破坏语义连贯性
注意：rt 必须与它所修饰的文本在 DOM 逻辑顺序上紧邻，但不需要物理相邻——中间插个空格或 不影响解析；但若插入其他标签（如 <span></span>），读屏软件可能跳过或误读。
动态生成时最容易崩的三个点
用 JS 拼接 ruby 结构时，以下情况会导致样式失效或语音引擎崩溃：
DeepBI DHTML 页面生成器
下载
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
- 拼音字符串含空格或标点未转义：写
"yí gè"没问题，但写"yí, gè"或"yí（gè）"会被当非法字符截断 - DOM 插入时用了
innerHTML而非textContent+appendChild：如果拼音里有或 <code>&，innerHTML会二次解析，可能闭合错标签 - 没处理零宽空格或软连字符：从 OCR 或 PDF 提取的文本常带
\u200B，它卡在汉字和rt之间，会让ruby关系断裂
CSS 控制多音字标注样式的实际限制
ruby 的显示行为受浏览器实现差异影响大，别指望用 CSS 改变基线对齐或拼音间距：
-
ruby-position: under在 Safari 和 Firefox 表现一致，但在 Chrome 128+ 需加display: ruby才生效 - 无法用
line-height单独拉高拼音行距，必须用ruby { line-height: 1.2; }整体调控 - 移动端 iOS Safari 对
rt的字体大小缩放不敏感，建议显式写rt { font-size: 0.6em; }
真正难的不是写对标签，而是判断“这个词在这里到底怎么读”——这一步没法交给 HTML，得靠人工校验或接入权威词典 API，否则自动生成的拼音再漂亮也没用。
