DialKit 是一款开源的 UI 参数实时调参库，支持 React、Solid、Svelte、Vue 与原生 JavaScript。其中的Timeline 时间线功能让动画调参变得像视频剪辑一样直观：把动画片段（Clip）摆上时间轴，用鼠标拖拽调整起止时间、拉宽缩小持续时间、逐帧 Scrub 回放，还能实时缩放时间轴观察每一帧的细节。

告别"改代码 → 编译 → 刷新 → 反复试错"的循环，DialKit Timeline 让动画节奏、弹簧参数与缓动曲线都"看得见、摸得着"。

什么是 Timeline Dock：一个独立的动画时间线编辑器

Timeline Dock 停靠在整个视口的底部，与 DialKit 的参数面板（DialRoot）完全独立工作：

• 工具栏：播放/暂停、重播、预设管理、Copy 导出、收起
• 多时间线支持：页面上注册的所有时间线都会显示在同一个 Dock 中
• 可拖高：拖动 Dock 上边缘即可调整高度
• 生产环境默认隐藏：默认只在开发环境渲染编辑器 UI，不会干扰线上用户

官方示例项目中，example/src/PhotoStack.tsx 就是用类似照片来演示弹入、翻栈等过渡效果的，下面这张就是演示素材之一：

快速上手：三步挂起时间线

1️⃣ 在你的框架适配器中创建时间线（以 React 为例）：

import { DialTimeline, useDialTimeline } from "dialkit"; const timeline = useDialTimeline("Card", { enter: { at: 0, duration: 0.6, from: { y: 24, opacity: 0 }, to: { y: 0, opacity: 1 }, transition: { type: "spring", bounce: 0.2 }, }, });

2️⃣ 在 JSX 中挂载一次 Dock：<DialTimeline />

3️⃣ 把timeline.enter.current绑定到元素样式上，UI 就会跟随播放头实时变化。

各框架的适配器对照如下（详见 docs/timeline.md）：

💡at、duration、from/to会直接变成 Clip 编辑器里的可编辑控件，数值滑块的量程也会根据位置、旋转、缩放、透明度等常见属性自动推断。

Scrub 逐帧：拖住播放头，看清每一帧

Timeline Dock 的核心交互是一张手势表，记不住也没关系——直觉就是"像剪视频一样拖"：

Scrub 之所以有意义，靠的是每个 Clip 都暴露了current字段——在播放头位置的采样值。把current绑定到页面上，拖播放头时界面会逐帧跟随，弹簧的"回弹感"、缓动的快慢节奏，一眼就能确认。

时间轴缩放的最大倍率与刻度密度等细节，实现于 src/components/Timeline/DialTimeline.tsx。

拖拽移动片段，缩放调整时长

每个 Clip 都是时间轴上的一根彩色条，支持三种直接操作：

• 拖动整根条→ 修改它的开始时间（at）
• 拖动条的左右边缘→ 修改它的持续时间（duration），弹簧与缓动会随之重新计时
• 点击 Clip→ 打开编辑器，修改数值与转场曲线

对于物理弹簧（{ type: "spring" }），时长由弹簧的收敛时间推导，条上会显示~——此时通过修改物理参数（如bounce）来改变节奏，而不是硬拉时长。

一个 Clip 有四种常见写法，覆盖绝大多数动画场景：

序列动画的每段（segment）都显示在 Clip 行内：拖拽段与段之间的边界即可调整左侧段的时长，点击某一段可单独编辑它的值与曲线。

属性轨道与分组：组织复杂动画

当不同属性需要不同的节奏（比如scale延迟 0.12s 再动），用props给每个属性建独立轨道，各自拥有from/steps、过渡与delay；点击合成条可展开各属性行，拖动属性条即可编辑延迟。

更复杂的编排可以把 Clip 嵌套一层形成分组（Group），形成可折叠的图层结构——分组只组织编辑器，多个 Clip 的数值如何在同一元素上叠加，由你的应用代码决定。

完整的多分组示例（入场动画 + 循环轨道 + 脉冲组）可以参考 example/src/Timeline1.tsx，里面的loop: { from: 0.8 }用法值得留意。

循环播放与导出：把调好的效果带回生产

循环分两层：

• Clip 级loop: true：该片段在时间线结束前反复循环
• 时间线级loop：true从头回绕；{ from: 1.4 }则先完整播放开场，之后从 1.4s 处循环，循环片段会保留相位

调完之后，点击工具栏的Copy即可把调好的时长、过渡与数值连同一份接入说明复制到剪贴板。⚠️ 注意：调试期间绑定的是采样值current，删除 Dock 前记得将其替换为正式动画代码——只隐藏 Dock 时间线仍在运行。

预设与持久化同样可用：为时间线开启persist: true后，所有时长编辑与预设版本都会存入localStorage，刷新不丢失。

相关资源

• 官方时间线指南（计时、插值、循环、Dock API）：docs/timeline.md
• 快速上手与面板 API：README.md
• 时间线配置解析与取值核心：src/timeline-core.ts
• 各框架共享的取值与循环逻辑：src/timeline/adapter.ts
• 时间线状态存储：src/store/TimelineStore.ts
• 交互测试用例（拖拽、缩放、Scrub 行为）：src/timeline-core.test.ts、src/timeline-react.test.ts