ruby标签不能直接加淡入动画，因其是内联替换元素，opacity在旧版浏览器中不继承或不触发重绘，且rt无明确盒模型边界导致transition不可靠；正确做法是用span包裹并控制其opacity与visibility。
ruby标签本身不支持transition动画，直接加opacity和transition无效——必须包裹一层可动画的容器，再用CSS控制其子元素的淡入行为。
为什么ruby标签不能直接加淡入动画
ruby是内联替换元素（replaced inline element），浏览器对其渲染有特殊限制：opacity属性在部分旧版浏览器中不被继承或不触发重绘；更关键的是，ruby内部的rt（注音）默认行内显示、无明确盒模型边界，transition无法可靠绑定到它的视觉变化上。直接写ruby { opacity: 0; transition: opacity 0.3s; }在 Chrome 125+ 可能“看似有效”，但在 Safari 或 Firefox 中常表现为跳变或无反应。
- 不要对
ruby或rt单独设transition - 避免用
display: inline状态切换，它不支持过渡 -
visibility必须和opacity同步控制，否则会残留占位或点击穿透
正确做法：用span包裹ruby并控制其opacity
把ruby当作文本内容的一部分来处理，外层套一个span（或其他行内块级容器），让动画发生在该容器上：
<span class="ruby-fade"> <ruby>漢<rt>かん</rt></ruby> </span>
对应 CSS 必须显式声明初始态和过渡属性：
立即学习“前端免费学习笔记（深入）”；
.ruby-fade {
opacity: 0;
visibility: hidden;
transition: opacity 0.25s ease-out, visibility 0.25s;
}
.ruby-fade.show {
opacity: 1;
visibility: visible;
}- 初始
opacity: 0和visibility: hidden必须写在默认状态里，不能只写在.show中 -
transition要同时列opacity和visibility，否则visibility会瞬间生效，打断淡入过程 - 时长建议≤0.3s，过长会让注音延迟感明显，破坏阅读节奏
JS触发淡入时要注意DOMContentLoaded时机
如果用 JS 控制显示，别等window.onload——图片加载完成太晚，用户可能已开始阅读。应在 DOM 解析完毕后立即加类：
document.addEventListener('DOMContentLoaded', () => {
document.querySelectorAll('.ruby-fade').forEach(el => {
el.classList.add('show');
});
});- 不要用
setTimeout模拟延迟，不可靠且易与 CSS 动画冲突 - 若需逐个淡入（如古籍逐字注音），改用
animation-delay配合@keyframes，而非 JS 循环加类 - 避免在
rt上设font-size或line-height突变——这些会触发 layout，导致文字抖动
移动端 Safari 的兼容性补丁
iOS 16.6+ 修复了ruby的 opacity 支持，但 iOS 15 及更早版本仍存在渲染异常：即使外层span已淡入，rt可能短暂错位或模糊。此时需强制启用合成层：
.ruby-fade {
will-change: opacity;
/* 或 */
transform: translateZ(0);
}-
will-change: opacity比transform: translateZ(0)更轻量，优先使用 - 仅在必要时添加，滥用会导致内存占用上升
- 测试时务必在真机 Safari 上验证，模拟器不反映真实渲染行为
真正难的不是写对一行@keyframes，而是让ruby在不同字体、不同字号、不同行高下都保持注音位置稳定——动画只是表象，底层盒模型对齐才是淡入不破相的关键。
