ruby 注音是html中为东亚文字添加发音标注的语义化机制，与ruby编程语言无关；使用结构标注读音，需注意书写规范、浏览器兼容性及语义完整性。

ruby 注音不是 Ruby 语言本身的特性，而是 HTML 和排版领域中对东亚文字（如汉字、假名、谚文）添加发音标注的标准机制。它和 Ruby 编程语言完全无关，只是名字撞车——HTML 的 ruby 元素读作 /ˈruː.bi/，而编程语言 Ruby 也读作 /ˈruː.bi/，但二者毫无技术关联。

HTML 中 ruby 元素怎么写

用 <ruby></ruby> 包裹基础文字，用 <rt></rt> 标注读音，可选 <rp></rp> 提供括号兼容 fallback：

<ruby>漢<rt>ㄏㄢˋ</rt></ruby><ruby>東京<rt>トウキョウ</rt></ruby><ruby>서울<rt>서울</rt></ruby>

浏览器会把 <rt></rt> 内容以小号字体显示在基字上方（横排）或右方（竖排），样式可由 CSS 控制。

ruby 在不同语言中的常见错误写法

容易误以为要手写拼音/假名/谚文的“注音符号”本身（如 ㄅ、ア、ㄱ），其实不需要——<rt></rt> 里直接写对应文字即可：

• 错：<rt>ㄏ-ㄢ-ˋ</rt>（拆开注音符号加连字符）→ 应写 <rt>ㄏㄢˋ</rt>
• 错：<rt>トウ・キョウ</rt>（加中点分隔）→ 应写 <rt>トウキョウ</rt>
• 错：<rt>seo-ul</rt>（用拉丁转写）→ 应写 <rt>서울</rt>（原文字）

为什么 ruby 渲染不出来

常见原因不是语法错，而是环境限制：

• 部分旧版 Safari 或 IE 对 ruby 支持不完整，需检查 display: ruby 是否被重置
• CSS 中写了 font-size: 0 或 line-height: 0 会导致 <rt></rt> 不可见
• 没设 ruby-position: over（默认值），但在某些安卓 WebView 中可能被忽略
• 使用了 <rp></rp> 但未配对闭合，或嵌套层级错误（<rp></rp> 必须在 <rt></rt> 内且紧邻）

替代方案：什么时候不该用 ruby 元素

当目标是生成可复制、可搜索、无障碍友好的发音时，ruby 是首选；但若需要动态生成、服务端渲染或兼容极老环境，就得换思路：

• 用 aria-label 或 data-pronounce 属性存发音，靠 JS 插入浮动提示
• 用 span + CSS position: relative/absolute 模拟，但会丢失语义和屏幕阅读器支持
• 拼音场景下，避免把整段中文塞进一个 <ruby></ruby> —— 应按字或词粒度分别包裹，否则断行和点击区域异常

实际项目里最容易被忽略的是语义完整性：<ruby></ruby> 是内联级元素，不能包块级内容；<rt></rt> 必须是 <ruby></ruby> 的直接子元素；多音字必须人工指定，没有自动识别逻辑。这些细节不报错，但一出问题就难定位。