标注单字拼音必须用显式包裹每个汉字，否则浏览器无法建立“字—音”对应关系，导致渲染错位、屏幕阅读器失效，且多音字、轻声、变调等须人工校正，css排版与混排处理亦不可缺。
直接用 <ruby></ruby> 标注单字拼音是可行的，但用于拼音教学时，必须按字粒度严格拆分、显式包裹 <rb></rb>，否则学生看到的不是“字—音”对应关系，而是错位或堆叠的无效输出。
为什么 <ruby>汉字<rt>pīn yīn</rt></ruby> 在教学中会失效
这种写法漏掉了 <rb></rb>，浏览器无法识别哪个文本是基字，多数现代浏览器（Chrome 110+、Firefox 115+、Safari 17+）会忽略 <rt></rt> 或降级为平铺显示，比如渲染成“汉字pīn yīn”，完全破坏教学意图。
-
<rb></rb>不可省略——它是语义锚点，告诉辅助技术“这是被注音的对象” - 没有
<rb></rb>，<rt></rt>就像无根浮萍，屏幕阅读器不会将其与汉字关联 - 学生练习跟读时，若拼音位置飘移或重叠，会干扰音节切分训练
多音字与轻声必须人工判定，不能依赖自动分词
拼音教学的核心是建立“形—音—义”映射，而 <ruby></ruby> 只负责呈现，不参与语义判断。例如“长”在“长度”中读 cháng，在“长大”中读 zhǎng，自动工具无法上下文感知。
- 避免用 pypinyin 默认模式生成“重庆” →
zhòng qìng（错误），应手动校正为chóng qìng - 轻声必须去掉声调符号：如“妈妈”标为
mā ma，不是mā mā - “一”“不”的变调要按实际朗读写：
yí wàn（一万）、bù qù（不去），不能照搬字典音
教学页面必须加最小 CSS，否则拼音不可见或被截断
默认状态下，<rt></rt> 字号与基字相同、无垂直偏移，学生根本看不出哪部分是拼音——这不是 bug，是规范设计：必须用 CSS 显式启用排版逻辑。
- 至少加
rt { font-size: 0.6em; }，否则拼音和汉字一样大，失去注音意义 - 父容器设
line-height: 1.6，防止拼音顶部被上一行文字裁掉 - 禁用
overflow: hidden或text-overflow: ellipsis，否则拼音可能被截断 - 不要用
position: absolute微调位置——不同设备缩放后极易错位，且破坏可访问性
混排文本（含数字、英文、标点）必须分块处理
真实教学材料常含例句如“第3课：Python变量名=‘你好’”，其中数字、英文、引号、等号都不能加拼音，但若不分块，正则或自动工具容易把 ' 或 = 错当汉字处理，导致 <rb></rb> 和 <rt></rt> 数量不等，整个结构崩溃。
- 用正则
/[\u4e00-\u9fff]+|[^\u4e00-\u9fff]+/g切分汉字块与非汉字块 - 仅对汉字块调用拼音库（如 pypinyin 的
lazy_pinyin(text, tone_marks='marks')） - 非汉字块原样插入，不包裹任何
<ruby></ruby>，避免语义污染 - 特别注意全角标点（如「」、『』）和 emoji：它们不属于 \u4e00-\u9fff 范围，必须归入非汉字块
最易被忽略的是：教学场景下，每个 <rb></rb> 后必须紧跟且仅一个 <rt></rt>，多一个空格、换行、注释都会让某些 Safari 版本跳过渲染；而学生反复朗读时，如果拼音因 line-height 过小被压扁，他们第一反应不是“拼音错了”，而是“这个字读音怪”，问题根源却藏在 CSS 里。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
