代码
import ...
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
fontFamily={'JetBrains Mono, monospace'}
offsetX={-1}
x={-400}
code={'const number = 7;'}
/>,
);
yield* waitFor(0.6);
yield* all(
code().code.replace(code().findFirstRange('number'), 'variable', 0.6),
code().code.prepend(0.6)`function example() {\n `,
code().code.append(0.6)`\n}`,
);
yield* waitFor(0.6);
yield* code().selection(code().findFirstRange('variable'), 0.6);
yield* waitFor(0.6);
yield* all(
code().code('const number = 7;', 0.6),
code().selection(DEFAULT, 0.6),
);
});
Code 节点用于显示代码片段。它支持语法高亮,并提供多种不同的方法为代码添加动画。
解析与高亮
首先,如果你直接复制本教程中的任何代码片段,会发现所显示的代码颜色单一。默认高亮器使用 Lezer 来解析和高亮代码,但要做到这一点,它需要你所使用语言的语法(grammar)。你可以在项目配置文件中进行设置。
首先,安装你所使用语言的语法。你可以查看这份并不详尽的可用语法列表。对于本教程,你应安装 javascript 语法:
npm i @lezer/javascript
然后,在项目配置中,使用导入的语法实例化一个新的 LezerHighlighter,并将其设为默认高亮器:
src/project.tsimport {makeProject} from '@motion-canvas/core';
import example from './scenes/example?scene';
import {Code, LezerHighlighter} from '@motion-canvas/2d';
import {parser} from '@lezer/javascript';
Code.defaultHighlighter = new LezerHighlighter(parser);
export default makeProject({
scenes: [example],
});
现在,你项目中的所有 Code 节点都将使用 @lezer/javascript 来解析和高亮代码片段。如果你想使用多种语言,请参阅多语言一节。
请注意,默认情况下,JavaScript 解析器不支持 JSX 或 TypeScript。你可以通过 dialects 启用对这些语言的支持。某个解析器可用的方言(dialect)通常列在该语法包的文档中。
Code.defaultHighlighter = new LezerHighlighter(
parser.configure({
// Provide a space-separated list of dialects to enable:
dialect: 'jsx ts',
}),
);
定义代码
要显示的代码通过 code 属性设置。最简单的情况下,你可以直接使用字符串:
import ...
export default makeScene2D(function* (view) {
view.add(
<Code
fontSize={28}
code={'const number = 7;'}
/>,
);
});
不过,代码片段通常包含多行代码。此时使用模板字符串要方便得多(用反引号字符 ` 表示):
view.add(
<Code
fontSize={28}
code={`\
function example() {
const number = 7;
}
`}
/>,
);
请注意以下两点:
-
代码片段会忽略模板字符串本身的缩进。模板字符串会保留所有空白字符,因此每行开头的任何额外空格或制表符都会包含在代码片段中。
-
开头的反斜杠字符 (
\) 用于转义第一个换行符。这使代码片段可以从新行开始,而不会在开头实际包含一个空行。如果没有该反斜杠,等效代码必须写成:view.add(<CodefontSize={28}code={`function example() {const number = 7;}`}/>,);
借助 ${} 语法,模板字符串可让你轻松地在代码片段中包含变量。在下面的示例中,${name} 会被 name 变量的值(此处为 number)所替换:
const name = 'number';
view.add(
<Code
fontSize={28}
code={`\
function example() {
const ${name} = 7;
}
`}
/>,
);
${} 语法中的任何有效 JavaScript 表达式都会包含在代码片段中:
const isRed = true;
view.add(
<Code
fontSize={28}
code={`\
function example() {
const color = '${isRed ? 'red' : 'blue'}';
}
`}
/>,
);
使用信号
如果你尝试在 ${} 语法中使用信号,会发现它们无法按预期工作。在模板字符串中调用信号会使用其当前值,此后即使信号发生变化,也不会再更新代码片段:
import {makeScene2D, Code} from '@motion-canvas/2d';
import {waitFor} from '@motion-canvas/core';
export default makeScene2D(function* (view) {
const nameSignal = Code.createSignal('number');
view.add(
<Code
fontSize={28}
code={`const ${nameSignal()} = 7;`}
/>,
);
yield* waitFor(1);
nameSignal('newValue');
// The code snippet still displays "number" instead of "newValue".
yield* waitFor(1);
});
尝试不调用信号而直接传递它,情况会更糟。由于每个信号都是一个函数,它会被字符串化并包含在代码片段中:
import ...
export default makeScene2D(function* (view) {
const nameSignal = Code.createSignal('number');
view.add(
<Code
fontSize={28}
code={`const ${nameSignal} = 7;`}
/>,
);
yield* waitFor(1);
nameSignal('newValue');
yield* waitFor(1);
});
之所以会发生这种情况,是因为模板字符串在我们的代码执行时会被立即解析。要解决此问题,你可以使用一个名为 CODE 的自定义标签函数。它允许 Code 节点以自定义方式解析模板字符串,从而正确支持信号。它使用起来非常简单,只需将 CODE 标签函数放在模板字符串之前:
import ...
export default makeScene2D(function* (view) {
const nameSignal = Code.createSignal('number');
view.add(
<Code
fontSize={28}
// Note the CODE tag function here:
code={CODE`const ${nameSignal} = 7;`}
/>,
);
yield* waitFor(1);
nameSignal('newValue');
// Now the code snippet is updated accordingly.
yield* waitFor(1);
});
CODE 返回的值本身也可以嵌套在其他模板字符串中:
const implementation = CODE`\
console.log('Hello!');
return 7;`;
const method = CODE`\
greet() {
${implementation}
}`;
const klass = CODE`\
class Example {
${method}
}
`;
view.add(<Code code={klass} />);
// class Example {
// greet() {
// console.log('Hello!');
// return 7;
// }
// }
你可能已经注意到,这些示例使用了一种通过 Code.createSignal() 创建的特殊类型信号。虽然通用的 createSignal() 在这些简单示例中也能正常工作,但当你开始为代码片段添加动画时,专用信号才会大放异彩。
为代码添加动画
Code 节点提供了几种不同的代码动画技术,具体取决于你所需的控制程度。
差异比对
为代码添加动画的默认方法是差异比对(diffing)。每当你对 code 属性进行补间时,都会使用该方法:
import ...
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
offsetX={-1}
x={-400}
code={`\
function example() {
const number = 9;
}`}
/>,
);
yield* code().code('const nine = 9;', 0.6).wait(0.6).back(0.6).wait(0.6);
});
该方法使用耐心差异算法(patience diff algorithm)来确定新旧代码片段之间的差异,然后相应地为这些变化添加动画。
append 与 prepend
如果你想在代码片段的开头或末尾添加代码,可以使用 append 和 prepend 方法。它们既可以立即修改代码,也可以随着时间推移为 变化添加动画:
import ...
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
offsetX={-1}
x={-400}
/>,
);
// append immediately
code().code.append(`const one = 1;`);
// animate using the signal signature
yield* code().code.append('\nconst two = 2;', 0.6);
// animate using the template tag signature
yield* code().code.append(0.6)`
const three = 3;`;
// prepend works analogically
yield* code().code.prepend('// example\n', 0.6);
yield* waitFor(0.6);
});
insert、replace 与 remove
若要对更改进行更细粒度的控制,你可以使用 insert、replace 和 remove 在特定位置修改代码。有关如何在代码片段中指定位置的更多信息,请参阅代码范围:
import ...
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
offsetX={-1}
x={-400}
code={`\
function example() {
console.log('Hello!');
}`}
/>,
);
// insert code at line 2, column 0
yield* code().code.insert([2, 0], ' return 7;\n', 0.6);
// replace the word "Hello!" with "Goodbye!"
yield* code().code.replace(word(1, 15, 6), 'Goodbye!', 0.6);
// remove line 2
yield* code().code.remove(lines(2), 0.6);
// animate multiple changes at the same time
yield* all(
code().code.replace(word(0, 9, 7), 'greet', 0.6),
code().code.replace(word(1, 15, 8), 'Hello!', 0.6),
);
yield* waitFor(0.6);
});
edit
edit 方法提供了一种定义代码过渡的不同方式。它与插入到模板字符串中的 replace、insert 和 remove 辅助函数配合使用。它们让你可以用更直观的方式指定更改,而无需知道代码中的确切位置:
import ...
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
offsetX={-1}
x={-400}
/>,
);
yield* code().code.edit(0.6)`\
function example() {
${insert(`// This is a comment
`)}console.log("${replace('Hello!', 'Goodbye!')}");
${remove(` return 7;
`)}}`;
yield* waitFor(0.6);
});
信号
请注意,上面使用的所有方法都不是在 Code 节点上调用,而是在其 code 属性上调用。这看似有些多余,但有充分的原因:code 属性是一种专用的代码信号,就像通过 Code.createSignal() 创建的信号一样。这意味着你自己的信号也可以使用所有这些动画方法:
import ...
export default makeScene2D(function* (view) {
const message = Code.createSignal(`Hello, world!`);
const body = Code.createSignal(CODE`console.log('${message}');`);
view.add(
<Code
fontSize={28}
offsetX={-1}
x={-400}
code={CODE`\
function hello() {
${body}
}`}
/>,
);
yield* waitFor(0.3);
yield* all(
message('Goodbye, world!', 0.6),
body.append(0.6)`\n return 7;`,
);
yield* waitFor(0.3);
});
代码信号也可以嵌套在传递给动画方法的模板字符串中:
import {makeScene2D, Code, CODE} from '@motion-canvas/2d';
import {createRef, waitFor} from '@motion-canvas/core';
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
offsetX={-1}
x={-400}
code={'// example'}
/>,
);
const body = Code.createSignal(CODE`console.log('Hello!');`);
yield* waitFor(0.3);
// Notice how the CODE tag is not used here because
// "append" already supports nested signals:
yield* code().code.append(0.6)`
function hello() {
${body}
}`;
// The "body" signal remains reactive after the append animation:
yield* body(`console.log('Goodbye!');`, 0.6);
yield* waitFor(0.3);
});
代码范围
CodeRange 用于通过行号和列号指定一段连续的字符范围。它可用于编辑代码、在视觉上选中代码的一部分,或查询字符的位置和尺寸。
代码范围的结构如下:
[[startLine, startColumn], [endLine, endColumn]];
例如,要选中第二行的前三个字符,可以使用以下范围:
[[1, 0], [1, 3]];
请记住,行和列都是从零开始计数的。此外,你应将列视为位于字符左侧的位置,这意味着如果你想包含第 n 列的字符,应将 n + 1 用作结束列。
为方便起见,我们提供了 word 和 lines 辅助函数,用于创建一些常见的范围类型:
// a range starting at line 1, column 3,
// spanning 3 characters:
word(1, 3, 3);
// a range starting at line 1, column 3,
// spanning until the end of the line:
word(1, 3);
// a range containing lines from 1 to 3 (inclusive):
lines(1, 3);
// a range containing line 2
lines(2);
创建 Code 节点后,你可以使用其 findFirstRange、findAllRanges 和 findLastRange 方法,查找包含特定字符串或匹配给定正则表达式的范围:
import {makeScene2D, Code} from '@motion-canvas/2d';
import {createRef, waitFor} from '@motion-canvas/core';
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
offsetX={-1}
x={-400}
code={`\
function example() {
console.log('Hello!');
}`}
/>,
);
yield* code().code.replace(
// find the range of "example" and replace it with "greet"
code().findFirstRange('example'),
'greet',
0.6,
);
yield* waitFor(0.6);
});
代码选中
selection 属性可用于在视觉上区分代码片段的某一部分。选中范围可以使用单个 代码范围 或一个范围数组来指定:
import ...
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
offsetX={-1}
x={-400}
code={`\
function hello() {
console.log('Hello');
}`}
/>,
);
// select all instances of "hello" (case-insensitive)
yield* code().selection(code().findAllRanges(/hello/gi), 0.6);
yield* waitFor(0.3);
// select line 1
yield* code().selection(lines(1), 0.6);
yield* waitFor(0.3);
// reset the selection
yield* code().selection(DEFAULT, 0.6);
yield* waitFor(0.3);
});
查询位置与尺寸
getPointBBox 和 getSelectionBBox 分别可用于检索特定字符或字符范围的位置和尺寸。返回值是 Code 节点局部空间中的一个边界框。
以下示例使用 getSelectionBBox 在单词 log 周围绘制一个矩形:
import ...
export default makeScene2D(function* (view) {
const code = createRef<Code>();
view.add(
<Code
ref={code}
fontSize={28}
offsetX={-1}
x={-400}
code={`\
function hello() {
console.log('Hello');
}`}
/>,
);
const range = createSignal(() => {
const range = code().findFirstRange('log');
const bboxes = code().getSelectionBBox(range);
// "getSelectionBBox" returns an array of bboxes,
// one for each line in the range. You can just
// use the first one for this example.
const first = bboxes[0];
return first.expand([4, 8]);
});
code().add(
<Rect
offset={-1}
position={range().position}
size={range().size}
lineWidth={4}
stroke={'white'}
radius={8}
/>,
);
});
自定义主题
LezerHighlighter 使用 CodeMirror 的 HighlightStyle 为特定的代码词元分配颜色。默认情况下使用 DefaultHighlightStyle。你可以将自己的样式作为第二个参数传递给 LezerHighlighter 构造函数,以指定自定义样式:
import {Code, LezerHighlighter} from '@motion-canvas/2d';
import {HighlightStyle} from '@codemirror/language';
import {tags} from '@lezer/highlight';
import {parser} from '@lezer/javascript';
const MyStyle = HighlightStyle.define([
{tag: tags.keyword, color: 'red'},
{tag: tags.function(tags.variableName), color: 'yellow'},
{tag: tags.number, color: 'blue'},
{tag: tags.string, color: 'green'},
// ...
]);
Code.defaultHighlighter = new LezerHighlighter(parser, MyStyle);
多语言
你可以使用 highlighter 属性为每个节点单独配置高亮器。这将覆盖项目配置文件中设置的默认高亮器:
import {Code, LezerHighlighter} from '@motion-canvas/2d';
import {parser} from '@lezer/rust';
const RustHighlighter = new LezerHighlighter(parser);
// ...
view.add(
<Code
// this node uses the default parser
offsetX={-1}
x={-400}
code={`
function hello() {
console.log('Hello!');
}
`}
/>,
);
view.add(
<Code
// this node uses the Rust parser
highlighter={RustHighlighter}
offsetX={1}
x={400}
code={`
fn hello() {
println!("Hello!");
}
`}
/>,
);
为你经常使用的语言创建自定义组件会很有用。你可以使用 withDefaults 辅助函数,快速用自己的默认配置扩展任意节点:
src/nodes/RustCode.tsimport {Code, LezerHighlighter, withDefaults} from '@motion-canvas/2d';
import {parser} from '@lezer/rust';
const RustHighlighter = new LezerHighlighter(parser);
export const RustCode = withDefaults(Code, {
highlighter: RustHighlighter,
});
src/scenes/example.tsximport {RustCode} from '../nodes/RustCode';
// ...
view.add(
<RustCode
code={`
fn hello() {
println!("Hello!");
}
`}
/>,
);
渲染
如果你使用的是基于 Chromium 的浏览器,可能会注意到代码动画有些抖动。这是因为画布会将渲染后的文本对齐到最近的像素,从而无法平滑移动。在我们找到解决办法之前,建议你使用 Firefox 进行渲染。