document.timeline 是 Web Animations API 提供的只读属性，返回当前文档默认的 DocumentTimeline 实例，用于统一动画时间基准；它在 Chrome 60+、Edge 79+、Firefox 73+ 中可用，但 Safari（含 17 版）不支持，访问时返回 undefined。
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', <code>${performance.now()}</code>); /<em> 在 @keyframes 中通过 calc() 或 JS 注入变量驱动 </em>/但此法受限于 CSS 自定义属性无法直接驱动关键帧偏移。
容易踩的坑：
- 误以为
document.timeline可写入或可替换（它不可配置、不可重设） - 在 iframe 中误用顶层
document.timeline，实际应使用对应 iframe 的iframe.contentDocument.timeline（需同源） - 混淆
DocumentTimeline和AnimationTimeline接口（后者是抽象基类，不可直接实例化）
真正麻烦的不是怎么用，而是怎么优雅地绕过 Safari 的缺失——它不支持 document.timeline，也不支持 DocumentTimeline 构造函数，甚至连 Animation.timeline 属性都只是 getter（返回 null）。这意味着任何依赖时间线同步的交互动画，在 Safari 上必须接受“非严格同步”这个事实。
