电子课件中ruby注音须逐字包裹，仅支持「单字+单rt」结构；多音字、生僻字需人工标注；PDF导出时需用rp降级或服务端预渲染；LMS平台可能过滤ruby标签，应确认白名单或改用带aria-label的span；VoiceOver朗读需严格规范ruby结构以防错序。
电子课件里用 ruby 标签做生字注音，必须逐字包裹
电子教学课件（如 HTML 课件、SCORM 包、LMS 内嵌页面）中，ruby 标签只对「单字 + 单 rt」结构可靠生效。常见错误是把整词塞进一个 ruby：比如写 <ruby>苹果<rt>píng guǒ</rt></ruby>，结果 Safari 可能只给「果」标音，或拼音挤成一行贴在末尾。
正确做法是强制拆解：<ruby>苹<rt>píng</rt></ruby><ruby>果<rt>guǒ</rt></ruby>。
原因在于：ruby 的语义是「基字与其注音的原子对」，浏览器按 DOM 顺序一对一匹配；词级拼写只是视觉习惯，不是结构规则。
列表要点：
• 多音字（如「长」「重」）必须按上下文手动指定，不能靠 JS 自动推断
• 生僻字如「饕」「餮」需人工校对拼音，ruby 不解析声调逻辑
• CMS 或课件编辑器若支持变量插入（如 {{word}}），务必确保每个变量对应独立 ruby 块，而非批量替换后套一层
课件导出 PDF 或打印时 ruby 注音常消失
多数 PDF 导出工具（如 wkhtmltopdf、浏览器「另存为 PDF」）不识别 ruby 的语义渲染逻辑，直接忽略 rt，导致打印版课件无拼音。
临时补救方案是加降级 fallback：
• 必须用 rp 包括括号，且成对出现：<ruby>你<rt>nǐ</rt><rp>(</rp><rp>)</rp></ruby>
• 现代浏览器隐藏 rp，但 PDF 工具会原样输出「你(nǐ)」，至少保留可读性
• 避免在 rp 里加空格或换行，否则导出后括号错位
更稳妥的做法是服务端预渲染：用 Python/Node.js 脚本将 ruby 结构展开为 span 堆叠（上层拼音 + 下层汉字），再导出——但这会丢失语义和屏幕阅读器支持
课件在 LMS 平台（如 Moodle、Canvas）中 ruby 渲染异常
LMS 平台常对用户提交的 HTML 做白名单过滤或自动清理，ruby、rt、rp 可能被删掉或转义为纯文本。
验证方式：在平台编辑器中粘贴 <ruby>汉<rt>hàn</rt></ruby> 后，用开发者工具检查元素是否仍为 ruby 节点；若变成 <ruby>...</ruby>，说明被过滤。
应对策略：
• 提前联系平台管理员，确认 HTML 标签白名单是否包含 ruby、rt、rp
• 若平台禁用，改用 span 模拟，但必须加 aria-label 和 role="text" 补充语义：<span role="text" aria-label="hàn">汉</span>
• 避免在富文本编辑器中「所见即所得」模式下拖拽插入，改用「源码模式」粘贴
学生用 iPad VoiceOver 朗读课件时 ruby 注音顺序错乱
iOS VoiceOver 默认按 DOM 顺序朗读，但若 ruby 结构不规范（如 rt 缺失、rb 与 rt 数量不等、或中间插入 br），可能跳过注音、重复读基字、甚至把拼音读到下一句开头。
关键修复点：
• 每个 ruby 内严格只含一个基字（推荐显式用 rb 包裹）+ 一个 rt + 一对 rp
• 禁止在 ruby 内换行或加空格：<ruby>好<rt>hǎo</rt></ruby> ✅，<ruby>好<rt>hǎo</rt></ruby> ❌（换行符干扰 DOM 解析）
• 测试时务必关闭「朗读光标」，用三指滑动全文，确认每字后紧接其拼音，无遗漏或错序
注意：部分老旧 LMS 移动 App 会剥离 ruby 语义，仅保留纯文本，此时只能依赖降级括号或外挂 TTS 插件
立即学习“前端免费学习笔记（深入）”；
