7.4 KiB
自绘元素与自定义容器
<custom> 与 <container-custom> 用来处理现成元素无法直接表达的绘制与子元素控制:前者在元素内部直接用 Canvas 2D 画内容,后者接管子元素的绘制与事件传递。普通布局仍然优先用 <container> 与现成元素;只有确实需要直接操作画布或控制子元素时才用这两个标签。
前置知识
阅读本篇前,建议先读完:
custom
<custom> 是叶子元素,没有子元素。它的尺寸与位置由 loc 决定,loc 之外不参与布局。
render 接收 MotaOffscreenCanvas2D,在元素局部坐标里直接用 canvas.ctx 绘制。局部坐标的原点在元素左上角,宽高就是 loc 的宽高。
系统在调用 render 前后已经保存并恢复了画布状态,函数里不需要在开头和结尾习惯性地写 save / restore。只有在函数内部临时改变状态、之后还要恢复并继续绘制时,才需要自己保存和恢复。
bindings 接收依赖值数组。把 render 读取的响应式值放进数组,例如 bindings={[angle.value]},不需要传 ref 对象。读取 .value 发生在父组件 render 中,和 loc={[x.value, ...]} 一样会被 Vue 追踪;值变化后父组件重渲染,bindings prop 更新,<custom> 重绘。render 函数本身不需要认识 Vue、Ref 或 watch,它只读取普通值。Ref 等响应式基础见《响应式》。
::: warning
不要在 render 里修改用于 bindings 的响应式值(例如渲染时递增 angle.value),这会让渲染与状态更新互相触发。一般不会遇到这种情况,确实需要时会在高级 III 中进一步讲解。
:::
<custom> 默认开启缓存。内容频繁变化、缓存没有收益时,可以加 nocache。
需要直接使用 Canvas 2D 的路径、渐变、裁剪等能力,而现成元素组合不出来时,用 <custom> 自绘。能用 g-* 图形、image 与 text 拼出来的内容,继续用现成元素。
import { ref } from 'vue';
// 把 angle.value 放进 bindings;角度变化时 <custom> 会重绘
const angle = ref(0);
const ringColors = ['#2f6fed', '#7aa7ff', '#f2b84b'];
// render 在元素局部坐标里绘制内容
const render = canvas => {
const ctx = canvas.ctx;
const cx = 100;
const cy = 100;
// 径向渐变与同心圆环直接走 Canvas 2D
const gradient = ctx.createRadialGradient(cx, cy, 12, cx, cy, 88);
gradient.addColorStop(0, '#2f6fed');
gradient.addColorStop(1, '#141a22');
ctx.beginPath();
ctx.arc(cx, cy, 88, 0, Math.PI * 2);
ctx.fillStyle = gradient;
ctx.fill();
ringColors.forEach((color, index) => {
ctx.beginPath();
ctx.arc(cx, cy, 70 - index * 16, 0, Math.PI * 2);
ctx.strokeStyle = color;
ctx.lineWidth = 3;
ctx.stroke();
});
// 指针从圆心出发,按 angle 旋转;坐标都相对元素左上角
ctx.translate(cx, cy);
ctx.rotate(angle.value);
ctx.beginPath();
ctx.moveTo(0, 0);
ctx.lineTo(0, -64);
ctx.strokeStyle = '#e8f0ff';
ctx.lineWidth = 4;
ctx.stroke();
};
<custom loc={[40, 40, 200, 200]} bindings={[angle.value]} render={render} />;
下面的 live 用 <custom> 绘制同心圆环、径向渐变与旋转指针,角度值通过 bindings 触发重绘。
container-custom
<container-custom> 是带子元素的容器,区别只在绘制方式:render 接管子元素的绘制。
render(canvas, children, transform) 拿到画布、排好序的子元素列表与当前变换。子元素不会自动出现,必须自己遍历 children,对每个子元素调用 renderContent;不调用就不会绘制。children 已经按 zIndex 排好序,遍历顺序就是绘制顺序;hidden 的子元素应当跳过。
因为绘制的是子元素本身,render 里可以先逐个修改子元素的属性,再调用 renderContent。下面的例子给每个子元素设置依次递增的模糊:
// render 接管子元素绘制:按顺序给每个子元素设置递增的模糊,再逐个绘制
const render = (canvas, children, transform) => {
children.forEach((child, index) => {
if (child.hidden) return;
child.setFilter(`blur(${index * 2}px)`);
child.renderContent(canvas, transform);
});
};
<container-custom loc={[40, 40, 240, 160]} render={render}>
<g-rect loc={[16, 16, 208, 40]} fillStyle="#2f6fed" />
<g-rect loc={[16, 64, 208, 40]} fillStyle="#2f6fed" />
<g-rect loc={[16, 112, 208, 40]} fillStyle="#2f6fed" />
</container-custom>;
和 custom 一样,系统在调用 render 前后已经保存并恢复了画布状态,这个例子不需要写 save / restore。
propagate 接管事件传递,参数依次是事件类型、当前进度、事件对象、当前容器和「按默认规则继续传递」的回调。不写 propagate 就沿用默认。只有需要修改事件坐标或改变传递路径时才写,日常自定义绘制不需要它。
<container-custom> 常用于内置组件内部;需要自己控制子元素绘制或事件传递时也可以使用。普通布局继续用 <container>。
它默认开启缓存。内容频繁变化、缓存没有收益时,可以加 nocache。
普通 <container> 默认也会开启缓存:子元素先画到容器的缓存画布上,超出缓存画布的内容会被裁掉。给容器加 nocache 后子元素直接画到上层画布,超出容器的内容才不再被裁。不过这是缓存实现带来的特性,后续可能变化,不要依赖它来做布局或裁剪。
下面的 live 用同一组子元素对比:左侧普通 <container> 原样绘制,右侧 <container-custom> 在 render 里给子元素依次设置递增的模糊。
选择方式
| 需求 | 用法 |
|---|---|
| 只画内容、没有子元素 | <custom> |
| 要控制子元素怎么画 | <container-custom> 的 render |
| 要控制事件怎么传递 | <container-custom> 的 propagate |
| 普通布局 | <container> 与现成元素 |
能用现成元素组合出来的内容,优先用现成元素;<custom> 与 <container-custom> 留给 Canvas 2D 直接绘制或子元素控制。
边界与注意
<custom>没有子元素,尺寸与位置由loc决定。<container-custom>的render必须遍历并调用子元素的renderContent,否则子元素不会绘制。propagate不写就沿用默认;不需要改变事件传递时不要写。<custom>与<container-custom>默认缓存;内容频繁变化时再加nocache。- 普通布局与能用现成元素表达的内容,继续用
<container>与现成元素。