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