harmony 鸿蒙SceneNode

  • 2025-06-12
  • 浏览 (6)

SceneNode

本模块提供3D图形中场景资源结点的类型及操作方法。

说明：

本模块首批接口从API version 12开始支持，后续版本的新增接口，采用上角标标记接口的起始版本。

导入模块

import { LayerMask, NodeType, Container, Node, Geometry, LightType, Light, SpotLight, DirectionalLight,
  Camera } from '@kit.ArkGraphics3D';

LayerMask

用于定义结点的图层掩码。

getEnabled

getEnabled(index: number): boolean

获取指定图层下标图层掩码的使能状态。

系统能力： SystemCapability.ArkUi.Graphics3D

参数： |参数名|类型|必填|说明| |—-|—-|—-|—-| |index|number|是|要使能图层的下标，值域为大于等于0的整数。|

返回值： |类型|说明| |—-|—-| |boolean|返回特定下标的图层是否使能。true表示使用图层掩码，false表示不使用。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function layerMask() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node|null = result.getNodeByPath("rootNode_");
      if (node) {
          // 获取掩码的使能状态
          let enabled: Boolean = node.layerMask.getEnabled(1);
      }
    }
  });
}

setEnabled

setEnabled(index: number, enabled: boolean): void

将特定下标的图层掩码使能。

系统能力： SystemCapability.ArkUi.Graphics3D

参数： |参数名|类型|必填|说明| |—-|—-|—-|—-| |index|number|是|要使能图层的下标，值域为大于等于0的整数。| |enabled|boolean|是|要设置的使能状态。true表示使用图层掩码，false表示不使用。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function layerMask() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node|null = result.getNodeByPath("rootNode/Scene/");
      if (node) {
          // 设置掩码状态
          node.layerMask.setEnabled(1, true);
      }
    }
  });
}

NodeType

结点类型枚举。

系统能力： SystemCapability.ArkUi.Graphics3D |名称|值|说明| |—-|—-|—-| |NODE|1|结点是空结点。| |GEOMETRY|2|几何类型结点。| |CAMERA|3|相机类型结点。| |LIGHT|4|灯光类型结点。|

Container<T>

定义场景对象的容器。容器提供了一种将场景对象分组到层次结构中的方法。

append

append(item: T): void

追加一个对象到容器。

系统能力： SystemCapability.ArkUi.Graphics3D

参数： |参数名|类型|必填|说明| |—-|—-|—-|—-| |item|T|是|T类型对象。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function append() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node|null = result.getNodeByPath("rootNode/Scene/");
      // append 节点
      result.root?.children.get(0)?.children.append(node);
    }
  });
}

insertAfter

insertAfter(item: T, sibling: T|null): void

在兄弟结点后面插入对象。

系统能力： SystemCapability.ArkUi.Graphics3D

参数： |参数名|类型|必填|说明| |—-|—-|—-|—-| |item|T|是|要插入结点。| |sibling|T |null|是|兄弟结点。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function insertAfter() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node|null = result.getNodeByPath("rootNode/Scene/");
      // insertAfter 节点
      result.root?.children.get(0)?.children.insertAfter(node, null);
    }
  });
}

remove

remove(item: T): void

移除指定对象。

系统能力： SystemCapability.ArkUi.Graphics3D

参数： |参数名|类型|必填|说明| |—-|—-|—-|—-| |item|T|是|要移除的对象。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function remove() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node|null = result.getNodeByPath("rootNode/Scene/");
      // remove 节点
      result.root?.children.remove(node);
    }
  });
}

get

get(index: number): T|null

获取特定下标对象，获取不到则返回空。

系统能力： SystemCapability.ArkUi.Graphics3D

参数： |参数名|类型|必填|说明| |—-|—-|—-|—-| |index|number|是|要获取对象的下标，取值范围是大于等于0的整数。|

返回值： |类型|说明| |—-|—-| |T |null|返回获取到的对象，获取不到则返回空值。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function get() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node|null = result.getNodeByPath("rootNode/Scene/");
      // 从children中get 0号节点
      result.root?.children.get(0)?.children.insertAfter(node, null);
    }
  });
}

clear

clear(): void

清空容器内的所有对象。

系统能力： SystemCapability.ArkUi.Graphics3D

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function clear() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node|null = result.getNodeByPath("rootNode/Scene/");
      // 清空children节点
      result.root?.children.clear();
    }
  });
}

count

count(): number

获取容器中对象的数量。

系统能力： SystemCapability.ArkUi.Graphics3D

返回值： |类型|说明| |—-|—-| |number|返回容器中对象个数，取值范围是非负整数。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function count() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let node : Node|null = result.getNodeByPath("rootNode_");
      if (node) {
        let container: Container<Node> = node.children;
        // 获取children中的节点数
        let count: number = container.count();
      }
    }
  });
}

Node

3D场景由树状层次结构的结点组成，其中每个结点都实现了Node接口。继承自SceneResource。

属性

系统能力： SystemCapability.ArkUi.Graphics3D

名称 类型 只读 可选 说明
position Position3 否 否 结点位置。
rotation Quaternion 否 否 结点旋转角度。
scale Scale3 否 否 结点缩放。
visible boolean 否 否 结点是否可见。true表示该节点可见，false表示不可见。
nodeType NodeType 是 否 结点类型。
layerMask LayerMask 是 否 结点的图层掩码。
path string 是 否 结点路径。
parent Node |null 是 否 结点的父结点，不存在则为空值。
children Container<Node> 是 否 结点的结点，不存在则为空值。

getNodeByPath

getNodeByPath(path: string): Node|null

根据路径获取结点，如果获取不到则返回空。

系统能力： SystemCapability.ArkUi.Graphics3D

参数： |参数名|类型|必填|说明| |—-|—-|—-|—-| |path|string|是|场景结点层次中的路径。每层之间使用’/‘符号进行分割。|

返回值： |类型|说明| |—-|—-| |Node |null|返回结点对象。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node } from '@kit.ArkGraphics3D';

function getNode() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result && result.root) {
      // 查找节点
      let geo : Node|null = result.root.getNodeByPath("scene/node");
    }
  });
}

Geometry

几何节点类型，用于承载可渲染的网格数据，并支持可选的形变功能，继承自Node。

属性

系统能力： SystemCapability.ArkUi.Graphics3D

名称 类型 只读 可选 说明
mesh Mesh 是 否 网格属性。
morpher20+ Morpher 是 是 可选的形变器，用于为几何体添加基于顶点的形变或动画效果。若未设置，则该几何体不支持形变功能。

LightType

光源类型枚举。

系统能力： SystemCapability.ArkUi.Graphics3D

名称 值 说明
DIRECTIONAL 1 平行光类型。
SPOT 2 点光源类型。

Light

光源，继承自Node。

属性

系统能力： SystemCapability.ArkUi.Graphics3D

名称 类型 只读 可选 说明
lightType LightType 是 否 光源类型。
color Color 否 否 颜色。
intensity number 否 否 光照密度，取值范围是大于0的实数。
shadowEnabled boolean 否 否 是否使能阴影。true表示添加阴影，false表示没有阴影效果。
enabled boolean 否 否 是否使能光源。true表示使用光源，false表示不使用。

SpotLight

点光源类型，继承自Light。

系统能力： SystemCapability.ArkUi.Graphics3D

DirectionalLight

平行光类型，继承自Light。

系统能力： SystemCapability.ArkUi.Graphics3D

Camera

相机类型，Camera继承自Node。

属性

系统能力： SystemCapability.ArkUi.Graphics3D

名称 类型 只读 可选 说明
fov number 否 否 视场，取值在0到π弧度之间。
nearPlane number 否 否 近平面，取值大于0。
farPlane number 否 否 远平面，取值大于nearPlane。
enabled boolean 否 否 是否使能相机。true表示使用相机，false表示不使用相机。
postProcess PostProcessSettings |null 否 否 后处理设置。
clearColor Color |null 否 否 将渲染目标（render target）清空后的特定颜色。

raycast20+

raycast(viewPosition: Vec2, params: RaycastParameters): Promise

从屏幕指定位置发射射线，检测并返回所有命中的3D物体信息。使用Promise异步回调。

系统能力： SystemCapability.ArkUi.Graphics3D

参数： |参数名|类型|必填|说明| |—-|—-|—-|—-| |viewPosition|Vec2|是|标准化设备坐标(NDC)，范围[-1, 1]。(-1, -1)为屏幕左下角，(1, 1)为屏幕右上角。| |params|RaycastParameters|是|射线检测的配置参数（如检测范围、过滤节点等）。|

返回值： |类型|说明| |—-|—-| |Promise<RaycastResult[]>|返回命中的结果数组（按距离从近到远排序），若无命中则返回空数组。|

示例：

import { Image, Shader, MaterialType, Material, ShaderMaterial, Animation, Environment, Container, SceneNodeParameters,
  LightType, Light, Camera, SceneResourceParameters, SceneResourceFactory, Scene, Node, Vec2, Vec3, RaycastParameters,
  RaycastResult } from '@kit.ArkGraphics3D';

function Raycast() : void {
  let scene: Promise<Scene> = Scene.load($rawfile("gltf/CubeWithFloor/glTF/AnimatedCube.gltf"));
  scene.then(async (result: Scene) => {
    if (result) {
      let sceneFactory: SceneResourceFactory = result.getResourceFactory();
      let sceneCameraParameter: SceneNodeParameters = { name: "camera1" };
      // 创建相机
      let camera: Promise<Camera> = sceneFactory.createCamera(sceneCameraParameter);
      camera.enabled = true;
      lookAt(this.cam, { x: 15, y: 10, z: 20 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 1, z: 0 });
      let viewPos: scene3d.Vec2 = { x: 0.5, y: 0.5 };
      return camera?.raycast(viewPos, result.root);
    }
  });
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkGraphics 3D（方舟3D图形）

harmony 鸿蒙ScenePostProcessSettings

harmony 鸿蒙SceneResource

harmony 鸿蒙SceneType

harmony 鸿蒙Scene

harmony 鸿蒙@ohos.graphics.scene (ArkGraphics 3D模块)

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://www.seaxiang.com/blog/eDKiIP
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录