首页 / three.js / API 文档

Object3D

先看结论

场景图节点基类。所有可加入场景的物体都继承它，提供位置、旋转、缩放、父子关系与坐标变换。

最后验证 2026-11-03 · three.js 0.160.0 · 更新 2026-10-29 · 引用本文

new THREE.Object3D()

变换属性

属性	默认	说明
`position`	(0, 0, 0)	相对父节点的位置
`rotation`	(0, 0, 0)	欧拉角，弧度
`quaternion`	单位四元数	与 `rotation` 自动同步
`scale`	(1, 1, 1)	三轴缩放
`up`	(0, 1, 0)	`lookAt` 使用的朝上方向
`matrix`	单位矩阵	本地变换矩阵
`matrixWorld`	单位矩阵	世界变换矩阵
`matrixAutoUpdate`	true	渲染前是否按位置旋转缩放自动重算矩阵
`matrixWorldAutoUpdate`	true	是否自动更新世界矩阵

场景图属性

属性	默认	说明
`id`	自增	进程内唯一编号
`uuid`	自动生成	全局唯一标识，序列化时使用
`name`	''	自定义名称，配合 `getObjectByName` 查找
`parent`	null	父节点
`children`	[]	子节点数组
`visible`	true	false 时连同子节点一起跳过渲染
`castShadow`	false	是否投射阴影
`receiveShadow`	false	是否接收阴影
`frustumCulled`	true	是否参与视锥剔除
`renderOrder`	0	渲染排序权重，透明物体常用
`layers`	第 0 层	图层掩码，相机可选择性渲染
`userData`	{}	自定义数据容器，序列化时保留

常用方法

方法	说明
`add(object)`	添加子节点，会自动从原父节点移除
`remove(object)`	移除子节点
`removeFromParent()`	从父节点移除自身
`clear()`	移除全部子节点
`attach(object)`	添加子节点但保持其世界变换不变
`traverse(callback)`	深度优先遍历自身与后代
`traverseVisible(callback)`	只遍历可见节点
`getObjectByName(name)`	按名称查找后代
`getObjectById(id)`	按编号查找后代
`localToWorld(vector)`	本地坐标转世界坐标
`worldToLocal(vector)`	世界坐标转本地坐标
`getWorldPosition(target)`	世界位置
`getWorldQuaternion(target)`	世界旋转
`getWorldScale(target)`	世界缩放
`getWorldDirection(target)`	世界坐标下的朝向向量
`lookAt(x, y, z)`	让对象的 +Z 轴朝向目标点
`rotateX(angle)` / `rotateY` / `rotateZ`	绕本地轴旋转
`translateX(d)` / `translateY` / `translateZ`	沿本地轴平移
`applyMatrix4(matrix)`	应用变换矩阵并分解到位置、旋转、缩放
`updateMatrix()`	按位置旋转缩放重算本地矩阵
`updateMatrixWorld(force)`	递归更新世界矩阵
`clone(recursive)`	克隆节点，材质与几何仍为引用

示例：层级与坐标

const building = new THREE.Group();
building.position.set(120, 0, -40);

const floor = new THREE.Mesh(floorGeometry, floorMaterial);
floor.position.y = 3;
building.add(floor);

const roof = new THREE.Mesh(roofGeometry, roofMaterial);
roof.position.y = 9;
floor.add(roof);          // 挂在地板下，跟随地板的变换

scene.add(building);

// roof 的世界位置 = building × floor × roof 的本地变换
const worldPos = roof.getWorldPosition(new THREE.Vector3());
console.log(worldPos);

// 查找并批量处理
building.traverse(function (obj) {
  if (obj.isMesh) {
    obj.castShadow = true;
  }
});

矩阵何时更新

默认 matrixAutoUpdate: true，每次渲染前 three.js 会按 position、quaternion、scale 重新计算本地矩阵，再更新世界矩阵。手动改 matrix 并把 matrixAutoUpdate 设为 false 时，必须自己调用 updateMatrix() 与 updateMatrixWorld(true)，否则物体停在旧位置。

remove 不会释放显存。从场景移除节点只是断开引用，几何与材质仍占用 GPU 资源。确实不再使用时要调用 geometry.dispose() 与 material.dispose()。

引用本文

经纬志（2026）。《Object3D》。https://www.jingweizhi.com/three/api/object3d.html（访问日期 2026-11-03）。