当前位置：首页 > 文章列表 > 文章 > 前端 > 如何通过HTML的document.timeline获取文档的默认时间线对象用于同步动画

如何通过HTML的document.timeline获取文档的默认时间线对象用于同步动画

2026-05-03 21:18:46 0浏览收藏

document.timeline 是什么，它真的存在吗

document.timeline 是 Web Animations API 提供的只读属性，返回当前文档的默认时间线（DocumentTimeline 实例）。但它不是所有浏览器都支持——Chrome 60+、Edge 79+、Firefox 73+ 支持；Safari 目前（截至 Safari 17）仍不支持，会返回 undefined。

常见错误现象：

在 Safari 中直接访问 document.timeline 报 TypeError: Cannot read property 'currentTime' of undefined
动画同步逻辑在 Chrome 正常，Safari 完全不执行

使用场景：需要让多个 Animation 对象共享同一时间基准（比如拖拽时暂停所有动画、全局时间偏移控制），而不是各自依赖系统时钟。

务必先做存在性检查：

const timeline = document.timeline || new DocumentTimeline();

但注意：new DocumentTimeline() 是实验性特性（仅 Chromium 系列支持），不能作为通用降级方案。更稳妥的做法是用 performance.now() 手动模拟时间线，或改用 CSS @keyframes + animation-play-state 控制。

如何用 document.timeline.currentTime 同步多个动画

document.timeline.currentTime 返回毫秒级高精度时间戳（基于页面启动后的单调时钟），比 Date.now() 更适合动画同步。

实操建议：

不要直接赋值给 currentTime（它是只读的）
要“同步”，本质是让多个 Animation 的 startTime 基于同一参考点计算

示例：统一以 timeline 当前时间为起点播放两个动画

const tl = document.timeline;
const anim1 = elem1.animate(keyframes, opts);
const anim2 = elem2.animate(keyframes, opts);
anim1.startTime = tl.currentTime;
anim2.startTime = tl.currentTime;

若需暂停/恢复全部动画，可记录 tl.currentTime 差值，再批量调整各 Animation.startTime

性能影响：频繁读取 currentTime 开销极小，但若在每帧 requestAnimationFrame 中反复读取并重设 startTime，可能引发布局抖动（尤其当动画目标元素触发重排时）。

兼容性 fallback：没有 document.timeline 怎么办

当 document.timeline 为 undefined（如 Safari、旧版 Firefox），无法获得标准时间线，但仍有两种实用替代路径：

方案一：用 performance.now() 模拟时间线基准
```
const fakeTimeline = {
currentTime: performance.now()
};
```
然后在 requestAnimationFrame 中持续更新 fakeTimeline.currentTime。缺点是无法与 CSS 动画原生同步（CSS 动画仍走系统时钟）。

方案二：放弃时间线同步，改用 CSS 自身机制

document.documentElement.style.setProperty('--anim-time', ${performance.now()});
/ 在 @keyframes 中通过 calc() 或 JS 注入变量驱动 /

但此法受限于 CSS 自定义属性无法直接驱动关键帧偏移。

容易踩的坑：

误以为 document.timeline 可写入或可替换（它不可配置、不可重设）
在 iframe 中误用顶层 document.timeline，实际应使用对应 iframe 的 iframe.contentDocument.timeline（需同源）
混淆 DocumentTimeline 和 AnimationTimeline 接口（后者是抽象基类，不可直接实例化）

真正麻烦的不是怎么用，而是怎么优雅地绕过 Safari 的缺失——它不支持 document.timeline，也不支持 DocumentTimeline 构造函数，甚至连 Animation.timeline 属性都只是 getter（返回 null）。这意味着任何依赖时间线同步的交互动画，在 Safari 上必须接受“非严格同步”这个事实。

今天关于《如何通过HTML的document.timeline获取文档的默认时间线对象用于同步动画》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！