Two.js Element 深度指南:场景图基类 Two.Element 的渲染、序列化与资源释放
Two.js Element 深度指南:场景图基类 Two.Element 的渲染、序列化与资源释放
Two.js 是一个与渲染器无关(renderer-agnostic)的二维绘图 API,其所有图形对象(路径、图形、文字、渐变等)都继承自同一个基类 —— Two.Element。本文围绕 wiki/docs/element/README.md 文档,系统讲解该基类的定位、核心属性、序列化与资源释放机制,并结合 src/element.js 源码与测试用例,帮助你彻底理解 Two.js 场景图(scenegraph)的底层工作方式,掌握对象反序列化、SVG 渲染联动以及 renderer 资源安全释放的实战技巧。
Two.Element:Two.js 场景图的基础
从源码文档注释可以看出,src/element.js 中 Two.Element 被明确定义为 "The foundational object for the Two.js scenegraph"(Two.js 场景图的基类),它继承自 Two.Events:
export class Element extends Events {
constructor() {
super();
for (let prop in proto) {
Object.defineProperty(this, prop, proto[prop]);
}
}
static Properties = ['renderer', 'id', 'className'];
}
这里有两个值得关注的设计:
- 继承
Two.Events:这意味着每个 Element 天生具备事件能力(on/off/trigger等),详见 src/events.js。dispose()方法正是借助继承自 Events 的unbind()来解绑事件。 - 属性通过原型访问器(proto accessor)定义:
renderer、id、className三个属性并不是普通实例字段,而是在proto对象上通过get/set定义的(见 src/element.js),配合_flagId、_flagClassName等内部标志位实现"变更追踪",这是 Two.js 脏标记(dirty flag)渲染机制的基础。
Two.Element 位于类继承链的最底层,从源码结构看,Two.Shape(src/shape.js)直接继承 Element,而 Two.Path、Two.Group、Two.Text 等所有可渲染对象都经由 Shape 间接继承它;同样地,Two.Gradient、Two.Texture 等效果对象也直接或间接继承自 Element。
核心实例属性
文档中给出了三个实例成员,下面结合源码逐一展开。
renderer:渲染器专属变量的存储空间
Object access to store relevant renderer specific variables. Warning: manipulating this object can create unintended consequences.
renderer 属性(src/element.js)是一个普通对象,用于存放与具体渲染器相关的变量,默认值为 {}。文档特别警告:直接操作该对象可能引发不可预期的后果,因此日常开发中应当把它当作内部结构,而不是公共 API。
最常见的读取场景是配合 SVG 渲染器:
With the
Two.SVGRendereryou can access the underlying SVG element created viashape.renderer.elem.
即通过 shape.renderer.elem 拿到 Two.js 在 DOM 中创建的底层 SVG 元素,可以进一步做 DOM 层面的定制。从 src/renderers/svg.js 可以看到该元素是在渲染时惰性创建的:
if (!this._renderer.elem) {
this._renderer.elem = svg.createElement('g', {
id: this.id,
});
domElement.appendChild(this._renderer.elem);
}
从类型声明 src/element.d.ts 可以推断 renderer 对象包含 type(渲染器类型标识)、elem(对应的 SVG 元素,可为 <g>、<path>、<text>、<pattern>、渐变元素等)、以及可选的 onBeforeRender/onAfterRender 回调钩子。
id:会话内唯一的标识符
Session specific unique identifier.
每个 Element 在创建时都会自动获得一个会话内唯一的 id,初始值由 Constants.Identifier + Constants.uniqueId() 生成(src/element.js)。从 src/constants.js 可知前缀为 'two-',而 uniqueId() 是一个单调递增计数器:
Identifier: 'two-',
uniqueId: function () {
return count++;
}
即第一个对象 id 形如 two-0,第二个为 two-1,以此类推。id 的 setter 有额外行为(src/element.js):
set: function (v) {
const id = this._id;
if (v === this._id) return;
this._id = v;
this._flagId = true;
if (this.parent) {
delete this.parent.children.ids[id];
this.parent.children.ids[this._id] = this;
}
}
当元素已被加入某个 Group 时修改 id,会自动同步更新父级 children 的 ids 索引映射(src/children.js),保证 children.ids<a href="https://link.gitcode.com/i/17778bbc05e3d42c2edc9293cfe5bba7" target="_blank">id] 始终能正确检索到对象。文档的 nota-bene 还指出:在 SVG 渲染器下,修改 id 会同步改变底层 SVG 元素的 id,对应 [src/renderers/svg.js 中 if (this._flagId) 时的 setAttribute('id', ...) 逻辑。
className 与 classList:CSS 样式兼容
A class to be applied to the element to be compatible with CSS styling.
className(src/element.js)用于为元素指定一个类名,以兼容 CSS 样式;文档注明该属性仅在 SVG 渲染器中写入 DOM。其 setter 在值变化时会同步拆分出 classList 数组(src/element.js):
set: function (v) {
if (this._className !== v) {
this._flagClassName = true;
this.classList = v.split(/\s+?/);
this._className = v;
}
}
classList(src/element.js)是 String[] 类型,文档说明它是 "A list of class strings stored if imported / interpreted from an SVG element",即当使用 Two.interpret() 或 Two.load() 导入/解析 SVG 时,源 SVG 的 class 字符串会以数组形式保存在这里。SVG 渲染器在渲染时会把这些类名重新拼装回 DOM:
if (this._flagClassName) {
this._renderer.elem.setAttribute('class', this.classList.join(' '));
}
对应 src/renderers/svg.js。因此,导入 SVG 后你可以通过 element.className = 'my-css-class' 或直接操作 classList 来为对应图形应用 CSS 样式。
静态工厂方法 Two.Element.fromObject
Create a new
Two.Elementfrom an object notation of aTwo.Element.
fromObject(obj) 是 Two.Element 的静态方法(src/element.js),它接收一个描述 Element 的对象字面量,返回一个新的 Two.Element 实例:
static fromObject(obj) {
const elem = new Element().copy(obj);
if ('id' in obj) {
elem.id = obj.id;
}
return elem;
}
从 src/element.d.ts 的类型定义可以看出,可接受的 obj 结构为:
{
renderer?: { type: string };
id?: string;
className?: string;
}
文档明确指出,该方法与 Two.Element#toObject 协同工作("Works in conjunction with Two.Element.toObject"):toObject() 生成对象描述,fromObject() 依据描述重建实例。toObject() 的实现(src/element.js)返回:
toObject() {
return {
renderer: { type: this.renderer.type },
id: this.id,
className: this.className,
};
}
一个典型的序列化-反序列化用法如下:
const elem = new Two.Element();
elem.id = 'my-element';
elem.className = 'accent';
// 序列化为纯对象(可用于 JSON.stringify 保存到本地)
const snapshot = elem.toObject();
// 依据对象描述重建新实例
const clone = Two.Element.fromObject(snapshot);
clone.id === 'my-element'; // true
clone.className === 'accent'; // true
需要注意 copy() 方法(src/element.js)明确不复制原对象的 id("Explicitly do not copy the id of an object to keep uniqueness"),因此 fromObject 只有在传入对象显式包含 id 字段时才会恢复该 id,否则新实例会使用自己新生成的唯一 id。这一点保证了反序列化不会产生 id 冲突。由于 Element 是场景图基类,子类(如 Path、Group)也都继承了 toObject/fromObject 模式,各子类在序列化时会附加自身的专属属性。
flagReset:脏标记机制的开关
Called internally by Two.js's renderer to reset all flags. Ensures that only properties that change are updated before being sent to the renderer.
Two.js 的渲染器采用**脏标记(dirty flag)**优化策略:只有当属性发生变化(标志位被置为 true)时,才会把对应变更同步到渲染器,从而避免每帧全量重绘。flagReset()(src/element.js)的作用是在渲染流程完成后重置这些标志:
flagReset() {
this._flagId = this._flagClassName = false;
return this;
}
基类只负责重置 id 与 className 两个标志位;子类会通过 super.flagReset.call(this) 扩展自己的标志位重置逻辑。从源码检索可以看到,这个模式贯穿整个类体系:
Two.Group#flagReset(src/group.js)Two.Path#flagReset(src/path.d.ts)Two.Gradient#flagReset(src/effects/gradient.js)Two.LinearGradient、Two.RadialGradient、Two.Stop、Two.Texture、Two.Sprite、Two.ImageSequence等效果类均有同名方法,且统一调用super.flagReset.call(this)。
渲染器在完成一次渲染后会调用它。以 src/renderers/canvas.js 为例,Canvas 渲染器在每个 render 流程的末尾执行 return this.flagReset();SVG 渲染器的 render(src/renderers/svg.js)则利用这些标志位决定是否调用 setAttribute 更新 DOM 属性(如 _flagId、_flagClassName、_flagOpacity、_flagVisible、_flagMatrix 等)。
还有一个值得注意的细节:在 src/renderers/svg.js 中,隐藏对象(!this._visible 或透明度为 0)会直接短路返回而不重置标志位,因此对这些对象的状态修改会一直累积,直到对象重新可见时一次性应用。这保证了不可见对象上发生的多次变更不会丢失。
对普通使用者而言,flagReset 由渲染器在内部调用,一般不需要手动触发;但了解它的存在,有助于理解 Two.js 的"按需更新"性能模型。
dispose:安全释放渲染资源与事件
Release the element's renderer object and detach any events. This cleans up renderer-specific resources and unbinds all event listeners.
dispose()(src/element.js)用于彻底释放一个 Element 所占用的资源,它做四件事:
- 解绑全部事件:调用继承自
Two.Events的unbind()清空所有监听器,避免内存泄漏; - 移除 SVG DOM 节点:若存在
_renderer.elem且已在 DOM 中,将其从父节点移除并删除引用; - 释放 WebGL 资源:当
type === 'WebGLRenderer'时,通过gl.deleteTexture()和gl.deleteBuffer()释放纹理与缓冲区,并清空 effect 引用; - 清理 Canvas 上下文:当
type === 'CanvasRenderer'时删除缓存的_renderer.context。
其中 WebGL 部分的核心逻辑如下:
if (this.type === 'WebGLRenderer' && this.renderer.ctx) {
const gl = this.renderer.ctx;
if (this._renderer.texture) {
gl.deleteTexture(this._renderer.texture);
delete this._renderer.texture;
}
if (this._renderer.positionBuffer) {
gl.deleteBuffer(this._renderer.positionBuffer);
delete this._renderer.positionBuffer;
}
if (this._renderer.effect) {
this._renderer.effect = null;
}
}
最后,dispose() 会保留渲染器类型(this._renderer = { type: rendererType }),为对象后续可能的重新挂载(re-attachment)保留上下文,并返回 this 以支持链式调用。
dispose() 的行为在测试套件中有系统性的验证,见 tests/suite/dispose.js:
- Element.dispose - Event Unbinding:验证 dispose 前事件正常触发、dispose 后事件不再触发,且
_bound标志复位为false(tests/suite/dispose.js); - Element.dispose - SVG DOM Cleanup:验证 dispose 前元素存在于 DOM(
two.renderer.domElement.querySelector('#' + rect.id)可查到_renderer.elem),dispose 后 DOM 中的对应节点被移除(tests/suite/dispose.js)。
实际使用中,当你在 WebGL 场景下移除不再需要的图形,或需要销毁 SVG 渲染下的元素时,调用 element.dispose() 即可安全地回收 DOM 节点、GPU 纹理/缓冲区与事件监听:
// 移除一个矩形并释放其资源
rect.parent.remove(rect);
rect.dispose();
实战小结
Two.Element 是理解 Two.js 整个对象模型的门户:
- 继承关系:
Element → Shape → Path / Group / Text / …,所有可渲染与可感知效果的对象都共享这套基类 API; - 三大属性:
renderer(渲染器内部状态,SVG 下可通过renderer.elem拿到底层 DOM)、id(会话唯一标识,修改会自动同步 children 索引与 SVG id)、className/classList(CSS 样式兼容,SVG 渲染器写入 DOM); - 序列化:
toObject()与静态fromObject(obj)成对使用,可实现场景快照的保存与重建,且反序列化不会产生 id 冲突; - 性能机制:
flagReset()配合各子类的脏标志位,实现"只更新变化的属性"的增量渲染; - 资源安全:
dispose()统一解绑事件、移除 DOM 节点并释放 WebGL/Canvas 资源,由 tests/suite/dispose.js 提供回归保障。
想深入阅读源码,建议从 src/element.js 入手,并对照 src/events.js、src/shape.js 与 src/renderers/svg.js 串联起"事件 → 属性变更 → 脏标记 → 渲染器同步"的完整链路。