跳到主要内容

自定义组件

组件是像 Rect 和 Circle 这样的类,它们可以将渲染和数据功能抽象为可复用的模块化单元。要在场景中使用组件,请将其添加到视图中,并为组件提供参数。

<Switch initialState={false} />

要定义组件接受哪些参数,首先需要定义一个接口。接口的所有属性都必须用 SignalValue<> 包装,如下所示:

// You can extend an existing props interface
// such as LayoutProps, ShapeProps or NodeProps to
// include their properties alongside the ones you
// define

export interface SwitchProps extends NodeProps {
initialState?: SignalValue<boolean>;

// We don't use color here because we want
// to be able to pass hex strings and rgb
// values to accent rather than a `Color`
accent?: SignalValue<PossibleColor>;
}

接下来,为你的组件创建一个类。组件类必须继承 Node 或其子类之一。如果你不想从现有组件继承任何方法,就让类继承 Node。我们建议继承与你要构建的组件最相似的组件。例如,如果你要制作一个包含 Layout 的组件,就应该继承 Layout 和 LayoutProps。

export interface SwitchProps extends NodeProps {
// properties
}

export class Switch extends Node {
// implementation
}

要使用接口中定义的属性,你的类_必须_包含一个同名属性。Motion Canvas 提供了类型装饰器来简化这一操作,例如 @initial() 和 @signal()。点击此处了解有关信号的更多信息。

下面是定义此类属性的示例:

export class Switch extends Node {
// @initial - optional, sets the property to an
// initial value if it was not provided.
@initial(false)
// @signal - is required by motion canvas
// for every prop that was passed in.
@signal()
public declare readonly initialState: SimpleSignal<boolean, this>;

@initial('#68ABDF')
// @colorSignal - some complex types provide a dedicated decorator for
// signals that takes care of parsing.
// In this case, `accent` will automatically convert strings into `Color`s
@colorSignal()
public declare readonly accent: ColorSignal<this>;
// ...
}

注意,颜色用 ColorSignal<> 包装,而其他任何类型(即使是用户定义的类型)都用 SimpleSignal<> 包装。颜色信号不需要传入类型,因为 Motion Canvas 知道它必须是可解析为颜色的类型。在这两种情况下,都在包装器的末尾传入类,以将该信号注册到类上。属性必须使用 public、declare 和 readonly 关键字进行初始化。

普通属性可以按常规方式定义。例如:

export class Switch extends Node {
public constructor(props?: SwitchProps) {
super({
// If you wanted to ensure that layout was always
// true for this component, you could add it here
// as such:
// layout: true
...props,
});
// ...
}
}

props 参数在 super() 调用之外也很有用,可用于在别处访问你的数据。例如,如果你要构建一个显示数组的组件,就可以使用 props 为数组中的每个 Rect 设置颜色。

现在我们可以使用 this.add() 向视图中添加元素,就像向场景的视图添加元素一样:

export class Switch extends Node {
public constructor(props?: SwitchProps) {
// ...
this.add(
<Rect>
<Circle />
</Rect>,
);
}
}

由于这是一个类,你还可以添加方法。这在想要轻松地为组件制作动画时尤其有用。下面是一个用于切换开关状态的方法示例:

export class Switch extends Node {
// ...
public *toggle(duration: number) {
yield* all(
tween(duration, value => {
// ...
}),
tween(duration, value => {
// ...
}),
);
this.isOn = !this.isOn;
}
}

以下是我们在本指南中构建的组件的源代码:

import {
Circle,
Node,
NodeProps,
Rect,
colorSignal,
initial,
signal,
} from '@motion-canvas/2d';
import {
Color,
ColorSignal,
PossibleColor,
SignalValue,
SimpleSignal,
all,
createRef,
createSignal,
easeInOutCubic,
tween,
} from '@motion-canvas/core';

export interface SwitchProps extends NodeProps {
initialState?: SignalValue<boolean>;
accent?: SignalValue<PossibleColor>;
}

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

@initial('#68ABDF')
@colorSignal()
public declare readonly accent: ColorSignal<this>;

private isOn: boolean;
private readonly indicatorPosition = createSignal(0);
private readonly offColor = new Color('#242424');
private readonly indicator = createRef<Circle>();
private readonly container = createRef<Rect>();

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

this.isOn = this.initialState();
this.indicatorPosition(this.isOn ? 50 : -50);

this.add(
<Rect
ref={this.container}
fill={this.isOn ? this.accent() : this.offColor}
size={[200, 100]}
radius={100}
>
<Circle
x={() => this.indicatorPosition()}
ref={this.indicator}
size={[80, 80]}
fill="#ffffff"
/>
</Rect>,
);
}

public *toggle(duration: number) {
yield* all(
tween(duration, value => {
const oldColor = this.isOn ? this.accent() : this.offColor;
const newColor = this.isOn ? this.offColor : this.accent();

this.container().fill(
Color.lerp(oldColor, newColor, easeInOutCubic(value)),
);
}),

tween(duration, value => {
const currentPos = this.indicator().position();

this.indicatorPosition(
easeInOutCubic(value, currentPos.x, this.isOn ? -50 : 50),
);
}),
);
this.isOn = !this.isOn;
}
}