DisplayObject

DisplayObject 是 Next2D Player 中所有显示对象的基类。

属性

只读属性

属性	类型	说明
instanceId	number	DisplayObject 的唯一实例 ID
isSprite	boolean	返回是否具有 Sprite 功能
isInteractive	boolean	返回是否具有 InteractiveObject 功能
isContainerEnabled	boolean	返回显示对象是否具有容器功能
isTimelineEnabled	boolean	返回显示对象是否具有 MovieClip 功能
isShape	boolean	返回显示对象是否具有 Shape 功能
isVideo	boolean	返回显示对象是否具有 Video 功能
isText	boolean	返回显示对象是否具有 Text 功能
concatenatedMatrix	Matrix	到根级别的组合变换矩阵
dropTarget	DisplayObject | null	精灵被拖动或放置到的显示对象
loaderInfo	LoaderInfo | null	此显示对象所属文件的加载信息
mouseX	number	鼠标相对于 DisplayObject 参考点的 X 坐标（像素）
mouseY	number	鼠标相对于 DisplayObject 参考点的 Y 坐标（像素）
root	MovieClip | Sprite | null	DisplayObject 的根 DisplayObjectContainer

可读写属性

属性	类型	说明
name	string	名称。用于 getChildByName()（默认：""）
startFrame	number	起始帧（默认：1）
endFrame	number	结束帧（默认：0）
isMask	boolean	表示 DisplayObject 是否被设置为遮罩（默认：false）
parent	Sprite | MovieClip | null	此 DisplayObject 的父 DisplayObjectContainer
alpha	number	Alpha 透明度值（0.0-1.0，默认：1.0）
blendMode	string	要使用的混合模式（默认：BlendMode.NORMAL）
filters	Array | null	与显示对象关联的滤镜对象数组
height	number	显示对象的高度（像素）
width	number	显示对象的宽度（像素）
colorTransform	ColorTransform	显示对象的 ColorTransform
matrix	Matrix	显示对象的 Matrix
rotation	number	DisplayObject 实例的旋转角度（度）
scale9Grid	Rectangle | null	当前活动的缩放网格
scaleX	number	从参考点应用的对象水平缩放值
scaleY	number	从参考点应用的对象垂直缩放值
visible	boolean	显示对象是否可见（默认：true）
cacheAsBitmap	Matrix | null	位图缓存用的 Matrix。仅可设置缩放值（a, d）（b, c, tx, ty 将被忽略）。以 1.0 为基准，应用于 displayObject 自身的 scaleX/scaleY。缓存质量 = 指定 Matrix × 自身缩放 × 舞台缩放。缓存时不受祖先 Matrix 影响，但绘制时应用祖先 Matrix。命中测试、宽度和高度基于矢量。适用对象：Shape、TextField、Sprite、MovieClip（Video 因图像尺寸固定而不适用）（默认：null）
x	number	相对于父 DisplayObjectContainer 本地坐标的 X 坐标
y	number	相对于父 DisplayObjectContainer 本地坐标的 Y 坐标

方法

方法	返回类型	说明
getBounds(targetDisplayObject)	Rectangle	返回定义显示对象相对于指定 DisplayObject 坐标系统区域的矩形
globalToLocal(point)	Point	将点对象从舞台（全局）坐标转换为显示对象（本地）坐标
localToGlobal(point)	Point	将点对象从显示对象（本地）坐标转换为舞台（全局）坐标
hitTestObject(targetDisplayObject)	boolean	评估 DisplayObject 的绘制范围是否重叠或相交
hitTestPoint(x, y, shapeFlag)	boolean	评估显示对象是否与 x 和 y 参数指定的点重叠或相交
getLocalVariable(key)	any	从类的本地变量空间获取值
setLocalVariable(key, value)	void	在类的本地变量空间中存储值
hasLocalVariable(key)	boolean	确定类的本地变量空间中是否有值
deleteLocalVariable(key)	void	从类的本地变量空间中删除值
getGlobalVariable(key)	any	从全局变量空间获取值
setGlobalVariable(key, value)	void	将值保存到全局变量空间
hasGlobalVariable(key)	boolean	确定全局变量空间中是否有值
deleteGlobalVariable(key)	void	从全局变量空间中删除值
clearGlobalVariable()	void	清除全局变量空间中的所有值
remove()	void	移除父子关系

混合模式

常量	说明
BlendMode.NORMAL	正常显示
BlendMode.ADD	叠加
BlendMode.MULTIPLY	正片叠底
BlendMode.SCREEN	滤色
BlendMode.DARKEN	变暗
BlendMode.LIGHTEN	变亮
BlendMode.DIFFERENCE	差值
BlendMode.OVERLAY	叠加
BlendMode.HARDLIGHT	强光
BlendMode.INVERT	反转
BlendMode.ALPHA	Alpha
BlendMode.ERASE	擦除

使用示例

const { Sprite } = next2d.display;
const { BlurFilter } = next2d.filters;

const sprite = new Sprite();

// 位置和大小
sprite.x = 100;
sprite.y = 200;
sprite.scaleX = 1.5;
sprite.scaleY = 1.5;
sprite.rotation = 30;

// 显示控制
sprite.alpha = 0.8;
sprite.visible = true;
sprite.blendMode = "add";

// 滤镜
sprite.filters = [
    new BlurFilter(4, 4)
];

// 添加到舞台
stage.addChild(sprite);

坐标变换示例

const { Point } = next2d.geom;

// 将全局坐标转换为本地坐标
const globalPoint = new Point(100, 100);
const localPoint = displayObject.globalToLocal(globalPoint);

// 将本地坐标转换为全局坐标
const localPos = new Point(0, 0);
const globalPos = displayObject.localToGlobal(localPos);

碰撞检测示例

// 使用边界框检测
const hit1 = displayObject.hitTestPoint(100, 100, false);

// 使用实际形状检测
const hit2 = displayObject.hitTestPoint(100, 100, true);

// 与另一个 DisplayObject 进行碰撞检测
if (obj1.hitTestObject(obj2)) {
    console.log("检测到碰撞");
}

变量操作示例

// 本地变量操作
displayObject.setLocalVariable("score", 100);
const score = displayObject.getLocalVariable("score");
if (displayObject.hasLocalVariable("score")) {
    displayObject.deleteLocalVariable("score");
}

// 全局变量操作
displayObject.setGlobalVariable("gameState", "playing");
const state = displayObject.getGlobalVariable("gameState");
displayObject.clearGlobalVariable(); // 清除全部

cacheAsBitmap 示例

cacheAsBitmap 将矢量绘制或容器缓存为位图，从第二帧开始重复使用缓存纹理，从而提高性能。

适用类：

• Shape — 缓存矢量绘制
• TextField — 缓存文本渲染
• Sprite — 将容器及其所有子元素一起缓存
• MovieClip — 将容器及其所有子元素一起缓存

⚠️ 不适用于 Video。由于 Video 具有固定的图像尺寸，缓存没有效果。

Matrix 限制： Matrix 中仅可设置缩放值（a, d）。旋转（b, c）和平移（tx, ty）将被忽略。

// ✅ 正确用法（仅设置缩放）
shape.cacheAsBitmap = new Matrix(1, 0, 0, 1, 0, 0);  // 1 倍
shape.cacheAsBitmap = new Matrix(2, 0, 0, 2, 0, 0);  // 2 倍质量

// ❌ 旋转/平移值将被忽略
shape.cacheAsBitmap = new Matrix(1, 0.5, 0.5, 1, 100, 200);  // b, c, tx, ty 被忽略

使用场景：

1. 高速动画 — 高速移动的对象视觉清晰度低，缓存导致的画质降低几乎不可察觉，同时能显著提高性能
2. 静态背景和 UI 元素 — 缓存不变的 UI 元素（面板、装饰、图标等）可消除每帧重绘成本
3. 复杂矢量绘制 — 缓存路径较多的复杂 Shape 可大幅降低绘制开销

const { Shape, Sprite } = next2d.display;
const { Matrix } = next2d.geom;

// 以 1 倍比例缓存（1.0 基准 = 相对于 displayObject 自身的 scaleX/scaleY）
const shape = new Shape();
shape.graphics.beginFill(0xFF0000).drawCircle(50, 50, 40).endFill();
shape.cacheAsBitmap = new Matrix(1, 0, 0, 1, 0, 0);

// 以 2 倍分辨率缓存（自身缩放的 2 倍质量）
const hqShape = new Shape();
hqShape.graphics.beginFill(0x00FF00).drawRect(0, 0, 100, 80).endFill();
hqShape.cacheAsBitmap = new Matrix(2, 0, 0, 2, 0, 0);

// scaleX/scaleY 会被反映（缓存质量 = Matrix × 自身缩放 × 舞台缩放）
shape.scaleX = 2; // 缓存质量: 1 × 2 × stageScale
shape.scaleY = 2;

// 父级缩放不影响缓存质量（但绘制时会应用）
const container = new Sprite();
container.scaleX = 3;
container.scaleY = 3;
container.addChild(shape);

// 命中测试、宽度和高度基于矢量
const bounds = shape.getBounds(shape); // 返回矢量边界

// 禁用缓存
shape.cacheAsBitmap = null;

在 DisplayObjectContainer 上使用 cacheAsBitmap

您也可以在 Sprite 和 MovieClip 等 DisplayObjectContainer 子类上设置 cacheAsBitmap。 容器的所有子元素将被渲染到单个纹理中并缓存，在后续帧中重复使用。

const { Shape, Sprite, MovieClip } = next2d.display;
const { Matrix } = next2d.geom;

// 包含多个子元素的 Sprite
const sprite = new Sprite();
const rect = new Shape();
rect.graphics.beginFill(0xFF0000).drawRect(0, 0, 100, 80).endFill();
sprite.addChild(rect);
const circle = new Shape();
circle.graphics.beginFill(0x00FF00).drawCircle(50, 40, 30).endFill();
sprite.addChild(circle);

// 将整个容器缓存为位图
sprite.cacheAsBitmap = new Matrix(1, 0, 0, 1, 0, 0);

// 同样适用于 MovieClip
const mc = new MovieClip();
mc.cacheAsBitmap = new Matrix(1, 0, 0, 1, 0, 0);

// 禁用缓存（下一帧恢复正常渲染）
sprite.cacheAsBitmap = null;

缓存行为：

• 当对象或其祖先的缩放发生变化时，缓存将失效并在下一帧重新生成
• 位置更改（x, y）会保留缓存 — 仅更新绘制位置
• 在缩放频繁变化的动画期间，缓存每帧都会重新生成，因此缓存在动画完成后的静态状态下最为有效

注意事项：

• Matrix 中仅可设置缩放值（旋转和平移将被忽略）
• 不适用于 Video（固定尺寸的图像数据）
• 缓存期间，子元素的更改（添加/删除/属性更改）不会反映在屏幕上
• 当 stage.rendererScale 更改时，缓存会自动失效
• 同时设置 filter 和 cacheAsBitmap 时，cacheAsBitmap 优先

相关

• MovieClip
• Sprite