引用
通常,在创建节点时,我们希望存储对它的引用,以便之后为它制作动画。一种做法是先将它赋值给一个变量,然后再将其添加到场景中:
const circle = <Circle />;
view.add(circle);
// we can now animate our circle:
yield * circle.scale(2, 0.3);
如果你习惯了 React 之类的库,上面的例子可能看起来有些奇怪。在 Motion Canvas 中,JSX 组件会立即创建并返回给定类的实例。将它作为引用存储并在整个动画中使用是完全有效的。
但这种方式的扩展性不佳。我们添加的节点越多,就越难看清场景的整体结构。请看下面的例子:
const rectA = <Rect />;
const rectB = <Rect />;
const circle = <Circle>{rectA}</Circle>;
view.add(
<Layout>
{circle}
{rectB}
</Layout>,
);
现在将其与一个不存储任何引用的版本对比:
view.add(
<Layout>
<Circle>
<Rect />
</Circle>
<Rect />
</Layout>,
);
如果你觉得后一个例子更易读,那么本指南正适合你。
ref 属性
Motion Canvas 中的每个节点都有一个名为 ref 的属性,可让你创建对该节点的引用。它接受一个回调函数,该函数会在节点创建后立即调用,第一个参数即为新创建的实例。
有了这些认识,我们可以将最初的例子改写为:
let circle: Circle;
view.add(
<Circle
ref={instance => {
circle = instance;
}}
/>,
);
yield * circle.scale(2, 0.3);
以这种方式使用 ref 属性并不实用,我们也不推荐这样做。但理解它的工作原理至关重要,因为接下来介绍的所有方法都以此属性为基础。
createRef() 函数
使用 ref 属性的推荐方式是配合 createRef() 函数。继续我们的例子,可以将其改写为:
import {createRef} from '@motion-canvas/core';
// ...
const circle = createRef<Circle>();
view.add(<Circle ref={circle} />);
yield * circle().scale(2, 0.3);
注意,circle 不再只是一个指向圆圈的变量。相反,它是一个类似信号的函数,可用于访问圆圈。不带任何参数调用它(circle())会返回我们的实例。
回到那个较复杂场景的例子,我们现在可以将其改写为:
const rectA = createRef<Rect>();
const rectB = createRef<Rect>();
const circle = createRef<Circle>();
view.add(
<Layout>
<Circle ref={circle}>
<Rect ref={rectA} />
</Circle>
<Rect ref={rectB} />
</Layout>,
);
makeRef() 函数
ref 属性的另一个常见用例是将新创建的实例赋值给某个对象的属性。在下面的例子中,我们将圆圈赋值给 circle.instance(稍后会讨论这样做为何有用):
const circle = {instance: null as Circle};
view.add(
<Circle
ref={instance => {
circle.instance = instance;
}}
/>,
);
我们可以使用 makeRef() 函数来简化这一过程:
import {makeRef} from '@motion-canvas/core';
// ...
const circle = {instance: null as Circle};
view.add(
<Circle ref={makeRef(circle, 'instance')} />,
);
引用数组
当我们创建一个节点数组并希望获取其中所有节点的引用时,makeRef() 尤其有用:
const circles: Circle[] = [];
view.add(
<Layout>
{range(10).map(index => (
<Circle ref={makeRef(circles, index)} />
))}
</Layout>,
);
在 JavaScript 中,数组是以索引作为属性的对象。因此 makeRef(circles, index) 会将新创建的圆圈设置为数组的第 n 个元素。最终,我们得到一个大小为 10、填满圆圈的数组,可用它来为所有圆圈制作动画。
你也可以使用 createRefArray() 辅助函数来实现相同的效果:
import {createRefArray, range} from '@motion-canvas/core';
// ...
const circles = createRefArray<Circle>();
view.add(
<Layout>
{range(10).map(() => (
<Circle ref={circles} />
))}
</Layout>,
);
这次我们不指定索引。每当将 circles 数组传给 ref 属性时,新创建的圆圈都会被追加到我们的数组中。
请查看流程控制指南中的循环小节,了解如何利用引用数组来编排动画。
自定义函数
makeRef() 还可用于从自定义函数组件中返回多个引用:
function Label({
refs,
children,
}: {
refs: {rect: Rect; text: Txt};
children: string;
}) {
return (
<Rect ref={makeRef(refs, 'rect')}>
<Txt ref={makeRef(refs, 'text')}>{children}</Txt>
</Rect>
);
}
const label = {rect: null as Rect, text: null as Txt};
view.add(<Label refs={label}>HELLO</Label>);
// we can now animate both the Rect and the Text of our label:
yield * label.rect.opacity(2, 0.3);
yield * label.text.fontSize(24, 0.3);
在本例中,我们定义了一个名为 Label 的函数组件,由一个矩形及其内部的文字组成。使用该组件时,我们通过 refs 属性传入我们自己创建的 label 对象。随后 makeRef() 会用所有必需的引用填充该对象。
createRefMap() 函数
随着场景变得越来越复杂,为每个节点声明引用会变得繁琐。createRefMap() 辅助函数让我们可以按节点类型将引用分组:
import {createRefMap} from '@motion-canvas/core';
// ...
const labels = createRefMap<Txt>();
view.add(
<>
<Txt ref={labels.a}>A</Txt>
<Txt ref={labels.b}>B</Txt>
<Txt ref={labels.c}>C</Txt>
</>,
);
返回的对象是一个映射(map),可以存储任意数量的引用。在上面的例子中,我们在键 a、b、c 下分别赋了三个 Txt 引用。只需访问映射的某个属性(如 labels.a)就会为我们创建一个引用。属性名称是任意的,可以是任何我们想要的名字。
之后,我们可以使用相同的键来检索这些引用:
yield * labels.a().text('A changes', 0.3);
yield * labels.b().text('B changes', 0.3);
yield * labels.c().text('C changes', 0.3);
要检查某个引用是否存在,可以使用 in 运算符。这样可以避免创建引用:
if ('d' in labels) {
yield * labels.d().text('D changes', 0.3);
}
返回的对象带有一个 mapRefs 方法,让我们可以遍历映射中的所有引用。它类似于 Array.prototype.map 函数:
yield * all(...labels.mapRefs(label => label.fill('white', 0.3)));
makeRefs() 函数
回看前面的例子,你可能会注意到我们不得不两次定义 refs 类型。一次是在 Label 声明中,另一次是在创建 label 对象时:
function Label({
refs,
children,
}: {
refs: {rect: Rect; text: Txt};
children: string;
}) {
return (
<Rect ref={makeRef(refs, 'rect')}>
<Txt ref={makeRef(refs, 'text')}>{children}</Txt>
</Rect>
);
}
const label = {rect: null as Rect, text: null as Txt};
view.add(<Label refs={label}>HELLO</Label>);
我们可以使用 makeRefs() 来消除这种冗余。它可以从 Label 声明中提取类型,并创建一个与之匹配的空对象:
import {makeRef, makeRefs} from '@motion-canvas/core';
// ...
function Label({
refs,
children,
}: {
refs: {rect: Rect; text: Txt};
children: string;
}) {
return (
<Rect ref={makeRef(refs, 'rect')}>
<Txt ref={makeRef(refs, 'text')}>{children}</Txt>
</Rect>
);
}
const label = makeRefs<typeof Label>();
view.add(<Label refs={label}>HELLO</Label>);