多音字必须人工定音，ruby仅映射结构不解析语义；rb与rt须严格一对一，rp必须前置且顺序正确；CSS仅限调整字体、行高和书写模式，禁用破坏流式布局的属性。

多音字必须手动指定读音，ruby 不会自动判断

浏览器和 HTML 标准不解析语义，ruby 只负责结构映射，不识别“重”在“重庆”里读 Chóngqìng、在“重要”里读 zhòng。你给哪个字标什么音，完全取决于你写的 内容。常见错误是直接粘贴整段文字后让工具“自动注音”，结果“长”标成 cháng（实际是 zhǎng）、“发”标成 fā（实际是 fà），全是错的。

实操建议：

• 先通读全文，对存疑字查《现代汉语词典》或权威拼音库（如 Python 的 pypinyin 带 heteronym=False + 人工校验）
• 避免用“/”分隔多音（如 fā/fà），屏幕阅读器无法朗读，也不符合语义规范
• 对教材、儿童读物等场景，建议在 上加 data-pinyin 属性备用：发fà

批量生成时，rb 和 rt 必须严格一对一

动态拼接 HTML 时最容易出错：把一串汉字全塞进 ，只配一个 ，比如 银行yín háng。这会导致部分浏览器只给“行”标音，或整个结构被忽略——因为规范要求每个基文单位（rb 或裸文本）对应唯一一个 rt。

正确做法是逐字/逐词拆解后分别包裹：

• 单字词：银yín行háng
• 固定词组（需整体读音）：银行yín háng（此时“银行”视为一个语义单位）
• JavaScript 批量处理时，用数组 map 而非字符串 replace：text.split('').map(char => `${char}${pinyinMap[char]}`).join('')

旧版 Safari 和 NVDA 屏幕阅读器需要 rp 包裹括号

不加 ，iOS Safari 15 以下、某些 Windows 屏幕阅读器可能直接把拼音当普通文本读出来，或者显示为乱序括号。这不是样式问题，是可访问性失效。

DeepBI DHTML 页面生成器

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

下载

兼容写法必须包含 rp，且顺序不能错：

• 错误：好hǎo()（rp 在 rt 后，部分读屏器跳过）
• 正确：好(hǎo)
• 如果用 JS 动态生成，别漏掉 rp 标签，哪怕只是空节点：`${char}(${py})`

ruby 的样式微调不能破坏原生布局逻辑

很多人想调高拼音位置或加粗字体，就用 position: absolute 把 rt 提上去，结果导致打印失真、响应式错位、NVDA 朗读顺序混乱。HTML5 的 ruby 是语义容器，它的排版逻辑由浏览器内置渲染引擎控制。

安全可控的 CSS 方式只有这些：

• 改大小和颜色：rt { font-size: 0.7em; color: #666; }
• 调垂直间距：ruby { line-height: 2; }（增大基线距离，避免遮挡）
• 强制横排（防竖排页面干扰）：rt { writing-mode: horizontal-tb; }
• 禁止用 display: block、float、transform 等破坏流式布局的属性

真正卡住进度的，往往不是写不出循环生成 ruby 的代码，而是没意识到多音字必须人工定音、rb/rt 数量必须相等、rp 顺序错一位就会让读屏器失效——这些点不提前踩坑，后面调试花的时间远超写代码本身。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！