motion-canvas

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Motion Canvas

Base Scene Template

基础场景模板

import {makeScene2D} from '@motion-canvas/2d';

export default makeScene2D(function* (view) {

});

import {makeScene2D} from '@motion-canvas/2d';

export default makeScene2D(function* (view) {

});

Generator Functions & Animation Flow

生成器函数与动画流程

```
function*
```
defines a generator function
```
yield
```
pauses until next frame
```
yield*
```
delegates to another generator (composition)

export default makeScene2D(function* (view) {
  const circle = createRef<Circle>();
  view.add(<Circle ref={circle} width={100} height={100} fill={'red'} />);

  yield* circle().position.x(300, 1);
  yield* circle().position.x(-300, 1);
});

Reusable animation pattern:

function* flicker(circle: Circle, duration: number): ThreadGenerator {
  const colors = ['#e13238', '#e6a700', '#99C47A'];
  for (const color of colors) {
    circle.fill(color);
    yield* waitFor(duration);
  }
}
yield* flicker(myCircle(), 0.5);

```
function*
```
用于定义生成器函数
```
yield
```
暂停执行，直到下一帧
```
yield*
```
委托给另一个生成器（组合复用）

export default makeScene2D(function* (view) {
  const circle = createRef<Circle>();
  view.add(<Circle ref={circle} width={100} height={100} fill={'red'} />);

  yield* circle().position.x(300, 1);
  yield* circle().position.x(-300, 1);
});

可复用动画模式：

function* flicker(circle: Circle, duration: number): ThreadGenerator {
  const colors = ['#e13238', '#e6a700', '#99C47A'];
  for (const color of colors) {
    circle.fill(color);
    yield* waitFor(duration);
  }
}
yield* flicker(myCircle(), 0.5);

Signals System

信号系统

import {createSignal} from '@motion-canvas/core';

const radius = createSignal(3);

radius();            // Get → 3
radius(5);           // Set → 5
yield* radius(4, 2); // Tween to 4 over 2 seconds

Computed signals:

const area = createSignal(() => Math.PI * radius() * radius());

Signals in JSX:

<Circle width={() => radius() * 2} height={() => radius() * 2} />
yield* radius(200, 1); // Circle updates automatically

Vector signals:

const position = Vector2.createSignal(Vector2.up);
yield* position(Vector2.zero, 1);

Reset to default:

import {DEFAULT} from '@motion-canvas/core';
signal(DEFAULT);             // Instant reset
yield* signal(DEFAULT, 2);   // Tween to default

import {createSignal} from '@motion-canvas/core';

const radius = createSignal(3);

radius();            // 获取值 → 3
radius(5);           // 设置值 → 5
yield* radius(4, 2); // 在2秒内缓动到4

计算信号：

const area = createSignal(() => Math.PI * radius() * radius());

JSX中的信号：

<Circle width={() => radius() * 2} height={() => radius() * 2} />
yield* radius(200, 1); // 圆形会自动更新

向量信号：

const position = Vector2.createSignal(Vector2.up);
yield* position(Vector2.zero, 1);

重置为默认值：

import {DEFAULT} from '@motion-canvas/core';
signal(DEFAULT);             // 立即重置
yield* signal(DEFAULT, 2);   // 缓动到默认值

References (Refs)

引用（Refs）

createRef (single node):

const circle = createRef<Circle>();
<Circle ref={circle} width={100} height={100} fill={'red'} />
yield* circle().scale(2, 0.3);

makeRef (arrays):

const circles: Circle[] = [];
{range(10).map(index => (
  <Circle ref={makeRef(circles, index)} x={index * 50} width={40} height={40} />
))}
yield* all(...circles.map(c => c.scale(1.5, 0.5)));

createRefMap (keyed):

const labels = createRefMap<Txt>();
<Txt ref={labels.a} text="Label A" />
<Txt ref={labels.b} text="Label B" />
yield* labels.a().text('Updated A', 0.3);

createRef（单个节点）：

const circle = createRef<Circle>();
<Circle ref={circle} width={100} height={100} fill={'red'} />
yield* circle().scale(2, 0.3);

makeRef（数组）：

const circles: Circle[] = [];
{range(10).map(index => (
  <Circle ref={makeRef(circles, index)} x={index * 50} width={40} height={40} />
))}
yield* all(...circles.map(c => c.scale(1.5, 0.5)));

createRefMap（键值对）：

const labels = createRefMap<Txt>();
<Txt ref={labels.a} text="Label A" />
<Txt ref={labels.b} text="Label B" />
yield* labels.a().text('Updated A', 0.3);

Scene Hierarchy

场景层级

view.add(<Circle />);               // Add to view
container().add(<Circle />);         // Add to node
container().insert(<Circle />, 0);   // Insert at index
circle().remove();                   // Remove
container().removeChildren();        // Remove all children
circle().reparent(newParent());      // Move to new parent

Z-order:

moveUp()

moveDown()

moveToTop()

moveToBottom()

moveTo(2)

Querying:

import {is} from '@motion-canvas/2d';
const textNodes = view.findAll(is(Txt));
const firstCircle = view.findFirst(is(Circle));

view.add(<Circle />);               // 添加到视图
container().add(<Circle />);         // 添加到节点
container().insert(<Circle />, 0);   // 插入到指定索引位置
circle().remove();                   // 移除节点
container().removeChildren();        // 移除所有子节点
circle().reparent(newParent());      // 移动到新父节点

Z轴层级：

moveUp()

moveDown()

moveToTop()

moveToBottom()

moveTo(2)

节点查询：

import {is} from '@motion-canvas/2d';
const textNodes = view.findAll(is(Txt));
const firstCircle = view.findFirst(is(Circle));

Save / Restore State

保存/恢复状态

yield* circle().save();
yield* all(circle().position.x(300, 1), circle().scale(2, 1));
yield* circle().restore(1); // Animate back to saved state

yield* circle().save();
yield* all(circle().position.x(300, 1), circle().scale(2, 1));
yield* circle().restore(1); // 动画恢复到保存的状态

Time Events & Waiting

时间事件与等待

import {waitFor, waitUntil, useDuration} from '@motion-canvas/core';

yield* waitFor(2);                    // Wait 2 seconds
yield* waitUntil('voice-line-2');     // Wait for named event
const dur = useDuration('segment');   // Get event duration

import {waitFor, waitUntil, useDuration} from '@motion-canvas/core';

yield* waitFor(2);                    // 等待2秒
yield* waitUntil('voice-line-2');     // 等待指定命名事件
const dur = useDuration('segment');   // 获取事件时长

Utilities

工具函数

Random:

useRandom(42)

→

.nextInt(10, 100)

.nextFloat(0, 1)

Logging:

useLogger()

→

.debug()

.info()

.warn()

.error()

; also

debug('msg')

Hooks:

useScene()

→

.getSize()

;

useTime()

Range:

range(5)

→

[0,1,2,3,4]

;

range(2,5)

→

[2,3,4]

Threads:

// Spawn a background thread (do NOT yield — spawn starts it automatically)
const task = spawn(function* () {
  yield* loop(Infinity, function* () {
    yield* circle().rotation(360, 2);
    circle().rotation(0);
  });
});

// Cancel a running thread
cancel(task);

// Wait for a thread to finish
yield* join(task);

yield a(); // run a without waiting for a
yield* waitFor(0.5); // wait 0.5s
yield* b(1); // run b

随机数：

useRandom(42)

→

.nextInt(10, 100)

.nextFloat(0, 1)

日志：

useLogger()

→

.debug()

.info()

.warn()

.error()

; 也可使用

debug('msg')

钩子：

useScene()

→

.getSize()

;

useTime()

范围生成：

range(5)

→

[0,1,2,3,4]

;

range(2,5)

→

[2,3,4]

线程：

// 启动后台线程（无需yield — spawn会自动启动）
const task = spawn(function* () {
  yield* loop(Infinity, function* () {
    yield* circle().rotation(360, 2);
    circle().rotation(0);
  });
});

// 取消运行中的线程
cancel(task);

// 等待线程完成
yield* join(task);

yield a(); // 执行a但不等待完成
yield* waitFor(0.5); // 等待0.5秒
yield* b(1); // 执行b并等待完成

Shape Components

图形组件

Circle:

<Circle width={200} height={200} fill={'#e13238'} stroke={'#fff'} lineWidth={4}
  startAngle={0} endAngle={270} closed={false} />

Rect:

<Rect width={300} height={200} fill={'#68ABDF'} radius={10} smoothCorners cornerSharpness={0.6} />

Line:

<Line points={[[0,0],[100,100],[200,50]]} stroke={'#fff'} lineWidth={4}
  lineDash={[20,10]} lineCap={'round'} lineJoin={'round'} startArrow endArrow arrowSize={12} />

Polygon:

<Polygon sides={6} size={200} fill={'#99C47A'} />

Grid:

import {Grid} from '@motion-canvas/2d';

<Grid width={'100%'} height={'100%'} stroke={'#333'} lineWidth={1} spacing={80} start={0} end={1} />

Animate with

start

end

(0-1) for drawing/erasing effects.

Path (SVG path data):

import {Path} from '@motion-canvas/2d';

<Path data={'M 0 -100 L 29 -40 L 95 -31 Z'} stroke={'#e6a700'} lineWidth={3} />

Supports morphing:

yield* path().data(newPathData, 1);

Circle（圆形）：

<Circle width={200} height={200} fill={'#e13238'} stroke={'#fff'} lineWidth={4}
  startAngle={0} endAngle={270} closed={false} />

Rect（矩形）：

<Rect width={300} height={200} fill={'#68ABDF'} radius={10} smoothCorners cornerSharpness={0.6} />

Line（线条）：

<Line points={[[0,0],[100,100],[200,50]]} stroke={'#fff'} lineWidth={4}
  lineDash={[20,10]} lineCap={'round'} lineJoin={'round'} startArrow endArrow arrowSize={12} />

Polygon（多边形）：

<Polygon sides={6} size={200} fill={'#99C47A'} />

Grid（网格）：

import {Grid} from '@motion-canvas/2d';

<Grid width={'100%'} height={'100%'} stroke={'#333'} lineWidth={1} spacing={80} start={0} end={1} />

可通过动画

start

end

（0-1）实现绘制/擦除效果。

Path（路径，基于SVG路径数据）：

import {Path} from '@motion-canvas/2d';

<Path data={'M 0 -100 L 29 -40 L 95 -31 Z'} stroke={'#e6a700'} lineWidth={3} />

支持形态变换：

yield* path().data(newPathData, 1);

Filters

滤镜

import {blur, brightness, grayscale, sepia, contrast, saturate, hue, invert} from '@motion-canvas/2d';

<Rect filters={[blur(5), brightness(1.5)]} />
yield* rect().filters([blur(0), grayscale(1)], 1); // Animated

See Filters for full details.

import {blur, brightness, grayscale, sepia, contrast, saturate, hue, invert} from '@motion-canvas/2d';

<Rect filters={[blur(5), brightness(1.5)]} />
yield* rect().filters([blur(0), grayscale(1)], 1); // 带动画的滤镜切换

详情请查看 Filters。

Gradients

渐变

import {Gradient} from '@motion-canvas/2d';

const grad = new Gradient({
  type: 'linear',
  from: [-100, 0], to: [100, 0],
  stops: [{offset: 0, color: '#e13238'}, {offset: 1, color: '#68ABDF'}],
});
<Rect fill={grad} />

See Gradients for radial and conic types.

import {Gradient} from '@motion-canvas/2d';

const grad = new Gradient({
  type: 'linear',
  from: [-100, 0], to: [100, 0],
  stops: [{offset: 0, color: '#e13238'}, {offset: 1, color: '#68ABDF'}],
});
<Rect fill={grad} />

详情请查看 Gradients 了解径向渐变和锥形渐变类型。

Path Components

路径组件

Ray:

<Ray from={[0,0]} to={[300,200]} endArrow />

— animate with

start(1,1)

end(0,1)

CubicBezier:

<CubicBezier p0={..} p1={..} p2={..} p3={..} />

QuadBezier:

<QuadBezier p0={..} p1={..} p2={..} />

Spline:

<Spline points={[..]} />

— smooth curves Knot:

new Knot([x,y], sharpness)

— adjust curve sharpness within Spline

Ray（射线）：

<Ray from={[0,0]} to={[300,200]} endArrow />

— 可通过

start(1,1)

end(0,1)

实现动画 CubicBezier（三次贝塞尔曲线）：

<CubicBezier p0={..} p1={..} p2={..} p3={..} />

QuadBezier（二次贝塞尔曲线）：

<QuadBezier p0={..} p1={..} p2={..} />

Spline（样条曲线）：

<Spline points={[..]} />

— 平滑曲线 Knot（节点）：

new Knot([x,y], sharpness)

— 调整Spline中的曲线锐利度

Text Rendering

文本渲染

See Txt for full details.

<Txt text={'Hello World'} fontSize={64} fontFamily={'Inter'} fill={'#ffffff'} wrap={true} />

详情请查看 Txt。

<Txt text={'Hello World'} fontSize={64} fontFamily={'Inter'} fill={'#ffffff'} wrap={true} />

Custom Components

自定义组件

export class Switch extends Node {
  @initial(false) @signal()
  public declare readonly initialState: SimpleSignal<boolean, this>;

  public constructor(props?: SwitchProps) {
    super({...props});
  }

  public *toggle(duration: number) { /* animation logic */ }
}

Decorators (import from

@motion-canvas/2d

@signal()

@initial(value)

@colorSignal()

@vector2Signal()

import {Node, NodeProps, initial, signal} from '@motion-canvas/2d';

export class Switch extends Node {
  @initial(false) @signal()
  public declare readonly initialState: SimpleSignal<boolean, this>;

  public constructor(props?: SwitchProps) {
    super({...props});
  }

  public *toggle(duration: number) { /* 动画逻辑 */ }
}

装饰器（从

@motion-canvas/2d

导入）：

@signal()

@initial(value)

@colorSignal()

@vector2Signal()

import {Node, NodeProps, initial, signal} from '@motion-canvas/2d';

Scene Transitions

场景过渡

import {slideTransition, fadeTransition, Direction} from '@motion-canvas/core';
yield* slideTransition(Direction.Left);

All transitions (from

@motion-canvas/core

```
slideTransition(Direction.Left)
```
— slide in from direction
```
fadeTransition(duration?)
```
— cross-fade
```
zoomInTransition(area, duration?)
```
— zoom into a BBox area
```
zoomOutTransition(area, duration?)
```
— zoom out from a BBox area
```
waitTransition(duration?)
```
— wait without visual transition

Directions: Top, Bottom, Left, Right, TopLeft, TopRight, BottomLeft, BottomRight

Custom:

import {useTransition} from '@motion-canvas/core';
const transition = useTransition(ctx => { /* current */ }, ctx => { /* previous */ });
yield* transition(1);

import {slideTransition, fadeTransition, Direction} from '@motion-canvas/core';
yield* slideTransition(Direction.Left);

所有过渡效果（来自

@motion-canvas/core

）：

```
slideTransition(Direction.Left)
```
— 从指定方向滑入
```
fadeTransition(duration?)
```
— 交叉淡入淡出
```
zoomInTransition(area, duration?)
```
— 缩放到指定BBox区域
```
zoomOutTransition(area, duration?)
```
— 从指定BBox区域缩放退出
```
waitTransition(duration?)
```
— 仅等待，无视觉过渡

方向枚举： Top, Bottom, Left, Right, TopLeft, TopRight, BottomLeft, BottomRight

自定义过渡：

import {useTransition} from '@motion-canvas/core';
const transition = useTransition(ctx => { /* 当前场景逻辑 */ }, ctx => { /* 上一场景逻辑 */ });
yield* transition(1);

Advanced Patterns

进阶模式

Conditional:

if (cond()) yield* a(); else yield* b();

Reactive:

<Circle fill={() => val() > 150 ? 'red' : 'blue'} />

State machines:

while/switch

pattern with enum states

条件动画：

if (cond()) yield* a(); else yield* b();

响应式渲染：

<Circle fill={() => val() > 150 ? 'red' : 'blue'} />

状态机： 使用

while/switch

结合枚举状态的模式

References

参考文档

Setup — Project creation, installation, troubleshooting
Flow Control — all, any, chain, delay, sequence, loop
Tweening — Property tweens, easing, interpolation
Springs — Physics-based spring animations
Transforms — Coordinates, positioning, matrix operations
Presentation Mode — Slide-based playback
Txt — Text rendering, dynamic text, multi-line
Layout — Flexbox, cardinal directions, offset
LaTeX — Mathematical equations
Media — Images, icons, video
SVG — Animatable SVG component
Icons — Iconify icon usage and catalog
Camera — Pan, zoom, follow
Filters — blur, brightness, contrast, grayscale, sepia, hue, saturate, invert
Gradients — Linear, radial, conic gradient fills
Effects — createEffect, createDeferredEffect
Rendering — Rendering settings and output configuration
Sounds — Programmable sound playback (@alpha)

Setup — 项目创建、安装、故障排查
Flow Control — all、any、chain、delay、sequence、loop等流程控制
Tweening — 属性缓动、缓动函数、插值
Springs — 基于物理的弹簧动画
Transforms — 坐标、定位、矩阵运算
Presentation Mode — 基于幻灯片的播放模式
Txt — 文本渲染、动态文本、多行文本
Layout — Flexbox、方位布局、偏移
LaTeX — 数学公式渲染
Media — 图片、图标、视频
SVG — 可动画的SVG组件
Icons — Iconify图标使用与目录
Camera — 平移、缩放、跟随
Filters — 模糊、亮度、对比度、灰度、棕褐色、色相、饱和度、反色
Gradients — 线性、径向、锥形渐变填充
Effects — createEffect、createDeferredEffect
Rendering — 渲染设置与输出配置
Sounds — 可编程声音播放（@alpha版本）