ruby标签仅是拼音容器，不提供自动转拼音功能，需依赖前后端拼音库预生成“hàn zì”格式，并逐字包裹rb/rt、添加rp降级、避免样式破坏原生排版。
ruby 标签本身不支持自动拼音，必须先生成拼音再套结构
直接用 ruby 标签无法把“汉字”变成“hàn zì”——它只是容器，不带任何汉字转拼音能力。所有 rt 里的内容都得你手动填、脚本预生成，或调用第三方库输出后插入。常见错误是以为写个 <ruby>汉<rt></rt></ruby>，再靠 CSS 或 JS “激活”拼音，结果 rt 为空，浏览器就当没这回事。
- 前端必须依赖拼音库，如
pinyin-pro（推荐）、js-pinyin或chinese2pinyin - 后端可用 Python 的
pypinyin、Ruby 的pinyingem，但注意返回格式：多数默认是数组["han4", "zi4"]，需转成带声调小写 + 空格，如"hàn zì" - 别用
innerHTML +=拼接带引号的字符串，容易引号冲突；用模板字面量或document.createElement更安全 - 拼音含单引号（如法语词“d’après”混入）时，确保字符串编码为 UTF-8，且 HTML 声明了
<meta charset="utf-8">
逐字包裹 ruby 是唯一可靠结构，不能偷懒合并
想标“中华人民共和国”，不能写成 <ruby>中华人民共和国<rt>zhōng huá rén mín gòng hé guó</rt></ruby>。这样 Safari 会把一长串拼音堆在第一个字上方，Chrome 可能折行错位，屏幕阅读器也读不准音节边界。
- 必须拆到字级：
<ruby><rb>中</rb><rt>zhōng</rt></ruby><ruby><rb>华</rb><rt>huá</rt></ruby>... - 显式写
rb比纯文本基字更稳妥：部分安卓 WebView 和旧版 Edge 对<ruby>中<rt>zhōng</rt></ruby>支持不稳定，加rb明确语义可提升兼容性 - 多音字（如“长”“重”“乐”）无法自动判断，工具里得提供手动覆盖入口，比如给每个
ruby加data-pinyin="cháng"属性，供 JS 优先读取 - 避免在
rt里塞空格、全角符号或 HTML 实体，只放纯文本拼音，否则 Safari 可能渲染异常
样式要克制，优先用标准属性而非 hack 定位
很多人一上来就给 rt 加 position: absolute 或 margin-top: -0.6em，结果换字体、缩放、竖排时全乱。浏览器内置的 ruby 排版引擎比你手算更准。
- 必须设
ruby rt { font-size: 0.65em; line-height: 1; }，否则拼音和基字一样大，或因行高撑开导致错位 - 用
ruby-position: over（而非vertical-align: super）确保垂直对齐逻辑由浏览器控制 - 加
ruby-align: center让拼音水平居中于对应汉字，默认值虽是 center，但 Safari 15–16 需显式声明才稳定 - 禁用
display: block、width、overflow: hidden在ruby或rt上，否则破坏内建盒模型，尤其影响换行行为
rp 标签不是装饰，是降级可用性的关键开关
不加 rp，老环境（如 Android 4.4 WebView、Outlook 桌面版邮件）会把拼音平铺在汉字后面，变成“汉字hàn zì”，完全不可读。这不是样式问题，是语义 fallback 缺失。
- 必须成对使用：
<rp>(</rp><rt>hàn</rt><rp>)</rp>，括号不限于()，但前后必须一致（如用【】就全用） - 现代浏览器自动隐藏
rp，只显示拼音；老浏览器则显示“汉(hàn)”，保留基本可读性 - 不要把
rp写在rt外面，或漏掉右括号——顺序错乱会导致整个ruby被忽略 - 若项目明确不需兼容已淘汰平台（如 IE、Android 4.x），可省略
rp，但别误以为它是“可有可无的美化项”
wǒ men 还是 wǒ mén、“一”在“一万”里读 yí 还是 yī，这些规则得靠人工校验或额外规则引擎，ruby 标签本身一个字都不会管。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
