Ruby 注音是HTML中为东亚文字添加发音标注的语义化机制，与Ruby编程语言无关；使用<ruby><rt>结构标注读音，需注意书写规范、浏览器兼容性及语义完整性。
ruby 注音不是 Ruby 语言本身的特性，而是 HTML 和排版领域中对东亚文字（如汉字、假名、谚文）添加发音标注的标准机制。它和 Ruby 编程语言完全无关，只是名字撞车——HTML 的 ruby 元素读作 /ˈruː.bi/，而编程语言 Ruby 也读作 /ˈruː.bi/，但二者毫无技术关联。
HTML 中 ruby 元素怎么写
用 <ruby> 包裹基础文字，用 <rt> 标注读音，可选 <rp> 提供括号兼容 fallback：
<ruby>漢<rt>ㄏㄢˋ</rt></ruby> <ruby>東京<rt>トウキョウ</rt></ruby> <ruby>서울<rt>서울</rt></ruby>
浏览器会把 <rt> 内容以小号字体显示在基字上方（横排）或右方（竖排），样式可由 CSS 控制。
ruby 在不同语言中的常见错误写法
容易误以为要手写拼音/假名/谚文的“注音符号”本身（如 ㄅ、ア、ㄱ），其实不需要——<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>不可见 - 没设
ruby-position: over（默认值），但在某些安卓 WebView 中可能被忽略 - 使用了
<rp>但未配对闭合，或嵌套层级错误（<rp>必须在<rt>内且紧邻）
替代方案：什么时候不该用 ruby 元素
当目标是生成可复制、可搜索、无障碍友好的发音时，ruby 是首选；但若需要动态生成、服务端渲染或兼容极老环境，就得换思路：
- 用
aria-label或data-pronounce属性存发音，靠 JS 插入浮动提示 - 用
span+ CSSposition: relative/absolute模拟，但会丢失语义和屏幕阅读器支持 - 拼音场景下，避免把整段中文塞进一个
<ruby>—— 应按字或词粒度分别包裹，否则断行和点击区域异常
<ruby> 是内联级元素，不能包块级内容；<rt> 必须是 <ruby> 的直接子元素；多音字必须人工指定，没有自动识别逻辑。这些细节不报错，但一出问题就难定位。 
