BeShell 文档

简体中文

English

简体中文

English

外观

类: Timeline (时间线)

约 1774 字大约 6 分钟

2026-09-06

构建固件和导入到JS

Timeline 类由 animator 模块提供：

import { Timeline } from 'animator'

简介

关键帧动画时间线

由 BeShell 主循环驱动的等间隔帧节拍，在指定帧设置 "对象.属性=值" 关键帧， 播放时跨关键帧自动插值（支持缓动）。

示例：

import { Timeline } from "animator"

const obj = { x: 0, y: 0 }
const tl = new Timeline(30, 90)         // 30fps, 90 帧(3 秒)

// 设置关键帧: 帧号, 目标对象, 属性, 值 [, 缓动 [, 缓动参数]]
tl.set(30, obj, "x", 100, "outQuad")
tl.set(60, obj, "x", 50)
// 属性表形式批量设置
tl.set(90, obj, { x: 0, y: [200, "inOutBounce"] })

tl.on("change", (frame)=> console.log(frame, obj.x, obj.y))
tl.on("stop", ()=> console.log("done"))
tl.play()

继承自 EventEmitter，提供 on()/off() 等事件监听方法。

事件

事件名回调参数说明
frameframe:number 当前帧序号每帧属性更新后触发（无论值是否变化，无监听时不触发）
changeframe:number 当前帧序号仅在有属性值实际变更的帧触发（先于 frame 事件）
stopframe:number 固定为 0停止时触发（手动 stop() 与播完自动停止均触发）
pauseframe:number 当前帧序号暂停时触发

类方法

方法 constructor

原型: constructor (fps:number=60, frames:number=0, repeat:boolean=false)

构造函数：创建时间线

参数:

  • fps

    类型number

    默认值60

    参数说明帧率，必须 > 0

  • frames

    类型number

    默认值0

    参数说明总帧数，0 = 不限（播放到 stop()）； set/add 的帧号超过总帧数时自动扩展

  • repeat

    类型boolean

    默认值false

    参数说明true 时播完总帧数后重新计数循环播放

返回值:

类型Timeline

说明时间线实例

方法 play

原型: play ()

从 stopped 态开始播放：帧计数归零，加入主循环，帧数达到总帧数时自动停止 （repeat=true 时重新计数继续播放）。播放期间对象被主循环持有， JS 侧丢失引用也会播完才销毁（fire-and-forget）

返回值:

undefined

方法 stop

原型: stop ()

停止播放：帧计数归零，挂起的 nextFrame() Promise 以 Error("timeline stopped") reject

返回值:

undefined

方法 pause

原型: pause ()

暂停播放：挂起的 nextFrame() Promise 保留，resume() 后继续

返回值:

undefined

方法 resume

原型: resume ()

从暂停处继续播放，重新起节拍

返回值:

undefined

方法 nextFrame

原型: nextFrame ()

等待下一帧：返回 Promise，在下一个帧 tick 时以当前帧序号解决

配合 await 实现帧率受控、严格等间隔的动画循环：

const tl = new Timeline(60)
tl.play()
while(running) {
    const frame = await tl.nextFrame()
    // 更新动画...
}

返回值:

类型Promise<number>

说明当前帧序号

方法 set

原型: set (frame:number, obj:object|array, prop:string|object, value:number, ease:string="linear", easeS:number=1.70158)

设置关键帧（替换语义：同帧同属性覆盖，ease 省略时重置为 linear）

支持三种输入形式：

// 单属性
tl.set(30, obj, "x", 100, "outQuad", 1.70158)
// 属性表
tl.set(30, obj, { x: 100, y: [200, "inOutBounce"] })
// 多对象
tl.set(30, [obj1, {x: 100}, obj2, {y: 50}])

缓动设在目标关键帧上，表示"如何到达该值"。

参数:

  • frame

    类型number

    参数说明帧号（超过总帧数时自动扩展总帧数）

  • obj

    类型object, array

    参数说明目标对象，或 [obj, prop表, ...] 多对象数组

  • prop

    类型string, object

    参数说明属性名，或属性表

  • value

    类型number

    参数说明目标值（单属性形式）

  • ease

    类型string

    默认值"linear"

    参数说明缓动类型名称（同 tween 函数名）

  • easeS

    类型number

    默认值1.70158

    参数说明缓动参数（仅 Back/Elastic 有效）

返回值:

undefined

方法 add

原型: add (frame:number, obj:object|array, prop:string|object, value:number, ease:string, easeS:number)

累加关键帧（合并语义：同帧同属性值累加，ease 省略时保留原设置）

输入形式同 set()

参数:

  • frame

    类型number

    参数说明帧号

  • obj

    类型object, array

    参数说明目标对象，或 [obj, prop表, ...] 多对象数组

  • prop

    类型string, object

    参数说明属性名，或属性表

  • value

    类型number

    参数说明累加值（单属性形式）

  • ease

    类型string

    参数说明缓动类型名称（省略时保留原设置）

  • easeS

    类型number

    参数说明缓动参数

返回值:

undefined

方法 unset

原型: unset (frame:number, obj:object, prop:string)

移除关键帧

tl.unset(frm)              // 移除该帧上的全部对象属性（该帧失去关键帧地位）
tl.unset(frm, obj, "x")    // 仅移除该帧上的某个对象属性

轨道变空时销毁并释放 JS 对象引用。

参数:

  • frame

    类型number

    参数说明帧号

  • obj

    类型object

    参数说明目标对象（可选，与 prop 一起提供时仅移除该属性）

  • prop

    类型string

    参数说明属性名（可选）

返回值:

undefined