Ruby标签必须严格嵌套：与须为直接子元素且同级并列，不可用span替代；注音需按语义单元对齐，禁用逐字拆分；Windows字体支持弱，应优先选用Yu Gothic等专用字体；结构合规才保障无障碍朗读与语义价值。
ruby标签的基本结构必须严格嵌套
HTML的 不是简单包裹文字就能生效的标签，它需要明确的语义分层：汉字主体用 （ruby text），两者必须同级并列在 内部。浏览器只认这种结构，写成 漢字かんじ 是无效的。
常见错误现象：rt 标签被忽略、注音和汉字错位、整段文字换行异常——基本都是因为嵌套不合法或用了非标准元素替代 。
-
必须直接子元素，不能隔一层 - 一个
中可含多组） - 若需注音多个连续汉字（如「東京都」→「とうきょうと」），应按词切分，而非逐字：每个
中文环境下的显示兼容性问题
Chrome、Edge、Safari（macOS/iOS 15.4+）原生支持 ，但 Firefox 直到 115 版才默认开启完整支持；更关键的是，Windows 系统默认中文字体（如微软雅黑、SimSun）对 ruby 排版支持极弱——即使 HTML 结构正确，rt 也会紧贴汉字底部、挤占行高，甚至被截断。
解决路径不是加 CSS 强行定位，而是优先启用支持 ruby 的字体：
- 在
font-family中前置"Yu Gothic"（Windows）、"Hiragino Kaku Gothic Pro"（macOS）、"Noto Sans CJK JP"（跨平台） - 避免用
font-size: 0.5em或line-height手动缩放rt，这会破坏可访问性（屏幕阅读器依赖原生结构） - 测试时务必在真实 Windows 设备上打开，仅靠 Chrome DevTools 的设备模拟不可靠
处理长注音或拗音时的断字逻辑
日语注音常含促音（っ）、拨音（ん）、拗音（きゃ/しゅ等），这些在 ruby 中不能拆开——比如「学ぶ」要注为「まなぶ」，不是「ま な ぶ」；「東京」是「とうきょう」，不是「と う き ょ う」。否则会导致 内容过长、挤压
实现 Markdown↔ HTML 互转，支持导出 PDF，用于用户请求的文档格式转换。
实操建议：
- 注音字符串必须与汉字语义单元严格对齐，一个
- 禁用自动罗马字转假名工具生成的逐字注音（如把「日本語」转成「にほんご」没问题，但转成「に・ほ・ん・ご」就破坏了结构）
- 遇到「〜する」类动词变形（如「勉強する」→「べんきょうする」），整个「勉強する」应作为一个
，而不是只给「勉強」注音
无障碍与SEO注意事项
天然支持屏幕阅读器朗读注音（如 VoiceOver 会先读汉字再读 rt），但前提是结构干净。任何额外 wrapper、display: none 隐藏 rt、或用伪元素伪造注音，都会切断这个通路。
搜索引擎目前不索引 内容，所以别指望靠注音提升关键词排名；但结构合规的 ruby 能增强页面语义权重，尤其对多语言教育类站点有长期价值。
- 不要用
aria-label重复内容——冗余且可能被双读 - 若需 fallback（如旧 IE），用
包裹假名，再在外层加做视觉降级（例如小字号灰色字），而不是 JS 动态插入 - 注意
标签只用于括号 fallback（如），现代浏览器已无需它，加了反而增加 DOM 负担
实际混排中最容易被忽略的，是汉字与假名之间没有空格、全角/半角混用导致的渲染偏移——哪怕结构完全正确，一个不小心混入半角空格或零宽字符，都可能让 rt 整体右移一像素，而这个偏差在高密度排版里会层层放大。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
