openharmony 鸿蒙 js-apis-inner-scene-nodes

2025-06-12 浏览 (1)

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

参数：

参数名类型必填说明
indexnumber是要使能图层的下标，值域为大于等于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

参数：

参数名类型必填说明
indexnumber是要使能图层的下标，值域为大于等于0的整数。
enabledboolean是要设置的使能状态。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

名称值说明
NODE1结点是空结点。
GEOMETRY2几何类型结点。
CAMERA3相机类型结点。
LIGHT4灯光类型结点。

Container<T>

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

append

append(item: T): void

追加一个对象到容器。

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
itemT是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

参数：

参数名类型必填说明
itemT是要插入结点。
siblingT |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

参数：

参数名类型必填说明
itemT是要移除的对象。

示例：

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

参数：

参数名类型必填说明
indexnumber是要获取对象的下标，取值范围是大于等于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

名称类型只读可选说明
positionPosition3否否结点位置。
rotationQuaternion否否结点旋转角度。
scaleScale3否否结点缩放。
visibleboolean否否结点是否可见。true表示该节点可见，false表示不可见。
nodeTypeNodeType是否结点类型。
layerMaskLayerMask是否结点的图层掩码。
pathstring是否结点路径。
parentNode |null是否结点的父结点，不存在则为空值。
childrenContainer<Node>是否结点的结点，不存在则为空值。

getNodeByPath

getNodeByPath(path: string): Node|null

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

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

参数名类型必填说明
pathstring是场景结点层次中的路径。每层之间使用'/'符号进行分割。

返回值：

类型说明
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

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

LightType

光源类型枚举。

系统能力： SystemCapability.ArkUi.Graphics3D

名称值说明
DIRECTIONAL1平行光类型。
SPOT2点光源类型。

Light

光源，继承自Node。

属性

系统能力： SystemCapability.ArkUi.Graphics3D

名称类型只读可选说明
lightTypeLightType是否光源类型。
colorColor否否颜色。
intensitynumber否否光照密度，取值范围是大于0的实数。
shadowEnabledboolean否否是否使能阴影。true表示添加阴影，false表示没有阴影效果。
enabledboolean否否是否使能光源。true表示使用光源，false表示不使用。

SpotLight

点光源类型，继承自Light。

系统能力： SystemCapability.ArkUi.Graphics3D

DirectionalLight

平行光类型，继承自Light。

系统能力： SystemCapability.ArkUi.Graphics3D

Camera

相机类型，Camera继承自Node。

属性

系统能力： SystemCapability.ArkUi.Graphics3D

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

raycast20+

raycast(viewPosition: Vec2, params: RaycastParameters): Promise<RaycastResult[]>

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

系统能力： SystemCapability.ArkUi.Graphics3D

参数：

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

返回值：

类型说明
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模块)

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/eDKiIP