Two.js Element 深度指南:场景图基类 Two.Element 的渲染、序列化与资源释放

原创2026-09-24 16:55:581,918 阅读
文章标签:图形学前端

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'];
}

这里有两个值得关注的设计:

  1. 继承 Two.Events:这意味着每个 Element 天生具备事件能力(on/off/trigger 等),详见 src/events.js。dispose() 方法正是借助继承自 Events 的 unbind() 来解绑事件。
  2. 属性通过原型访问器(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.SVGRenderer you can access the underlying SVG element created via shape.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.Element from an object notation of a Two.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 所占用的资源,它做四件事:

  1. 解绑全部事件:调用继承自 Two.Events 的 unbind() 清空所有监听器,避免内存泄漏;
  2. 移除 SVG DOM 节点:若存在 _renderer.elem 且已在 DOM 中,将其从父节点移除并删除引用;
  3. 释放 WebGL 资源:当 type === 'WebGLRenderer' 时,通过 gl.deleteTexture() 和 gl.deleteBuffer() 释放纹理与缓冲区,并清空 effect 引用;
  4. 清理 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 串联起"事件 → 属性变更 → 脏标记 → 渲染器同步"的完整链路。

登录后查看全文
two.js