【ArkUI进阶练中学】第17课:HarmonyOS 7.0空间计算与3D渲染实战
【ArkUI进阶练中学】第17课 完整精讲版
HarmonyOS 7.0 空间计算与3D渲染实战
主要目标: 系统掌握 HarmonyOS 7.0 空间计算的技术栈全景,深入理解 ArkGraphics 3D 渲染管线、Spatial Recon Kit 3DGS 端侧重建、空间音频与沉浸光感组件的核心机制与最佳实践,并能够构建功能完整的空间计算应用。
第一部分 深度精讲
一、建立心智模型:HarmonyOS 空间计算技术栈全景
1.1 五层技术架构
HarmonyOS 7.0 的空间计算不是单一技术点,而是一套完整的技术栈,覆盖从应用层到硬件层的五个层次:
| 层次 | 核心组件 | 职责 |
|---|---|---|
| 应用层 | 空间电商、虚拟展览、3D社交、沉浸式教育 | 业务场景 |
| 框架层 | ArkUI Space、ArkGraphics 3D、SpatialAudioKit、XR Interaction、Spatial Recon Kit | 开发接口 |
| 引擎层 | 3D渲染引擎、物理模拟引擎、空间音频引擎、动画引擎 | 底层能力 |
| 系统层 | 方舟图形引擎(AGP)、空间定位、传感器融合 | 系统支撑 |
| 硬件层 | GPU、NPU、摄像头、传感器 | 物理基础 |
1.2 三大能力板块
空间美学——让界面“活”起来。 ArkUI 提供声明式空间界面开发范式,沉浸光感组件将材质视作独立界面物质,统一整合其光学行为、空间属性与交互响应能力,系统化地模拟光线的传播与反射,构建兼具通透性与层次感的数字物质。
空间影像——2D 到 3D 的“一键跃迁”。 3DGS(3D Gaussian Splatting)快速重建技术与系统级渲染引擎结合,2D 照片可一键生成 2.5D 沉浸式效果。Spatial Recon Kit 是 HarmonyOS 生态中面向 3DGS 的图形扩展能力,不仅支持加载和渲染 3DGS 模型,还提供了端侧三维重建功能。
空间交互——从“触屏”到“空间”。 Spatial Recon Kit 提供空间重建与感知能力,Audio Kit 新增空间音频能力,用户从视觉、听觉到交互的整个数字空间体验被全面重塑。
1.3 本课知识地图
HarmonyOS 空间计算与3D渲染
├── ArkGraphics 3D
│ ├── ECS 架构(Entity-Component-System)
│ ├── Scene 场景管理
│ ├── Component3D 组件
│ ├── glTF 模型加载
│ └── 自定义着色器
├── Spatial Recon Kit
│ ├── 3DGS 模型加载与渲染
│ ├── 风格化滤镜
│ ├── 端侧三维重建
│ └── 设备与地域限制
├── 空间音频
│ ├── HRTF 双耳效应渲染
│ └── 头动追踪
├── 沉浸光感组件
│ ├── 光随指动
│ ├── 光线勾勒
│ └── 非线性形变
└── 综合实战
└── 3D 商品展示应用
二、ArkGraphics 3D:方舟3D图形引擎
2.1 核心定位与架构
ArkGraphics 3D 是 HarmonyOS 的方舟3D图形能力,基于轻量级的3D引擎以及渲染管线为开发者提供基础3D场景绘制能力,供开发者便捷、高效地构建3D场景并完成渲染。
关键信息:
| 属性 | 值 |
|---|---|
| Kit 名称 | ArkGraphics 3D |
| ArkTS 导入路径 | @kit.ArkGraphics3D |
| 底层模块 | @ohos.graphics.scene |
| 首批接口版本 | API 12 |
| 系统能力标识 | SystemCapability.ArkUi.Graphics3D |
| 支持设备 | Phone、PC/2in1、Tablet、TV、Wearable |
@ohos.graphics.scene 将3D开发相关模块的API组织在一起,方便开发者使用。本模块首批接口从 API 12 开始支持,后续版本新增接口采用上角标单独标记起始版本。
2.2 ECS 架构
ArkGraphics 3D 的引擎层采用 ECS(Entity-Component-System)架构设计,进行模块化封装(如材质定义、后处理特效等),为开发者提供了灵活易用的开发套件。
| 概念 | 职责 | 示例 |
|---|---|---|
| Entity(实体) | 场景中的对象容器 | SceneNode、GSNode |
| Component(组件) | 附加到实体的数据和行为 | 材质定义、后处理特效 |
| System(系统) | 每帧更新的逻辑 | 渲染管线、动画系统 |
接口层基于引擎的 ECS Framework,通过 NAPI 层对数据进行组织处理,向开发者暴露简单易用的3D渲染接口,支持开发者使用少量代码完成3D场景的开发。
2.3 Scene 场景管理
Scene 是 ArkGraphics 3D 的基础模块,提供 SceneResourceParameters、SceneNodeParameters 等通用数据类型,同时提供 glTF 模型加载、场景元素、资源创建等基础方法。3D场景是以树状结构进行组织的,通过操作节点属性以及节点树结构可以改变3D场景。
import { Scene } from '@kit.ArkGraphics3D';
// 异步加载 glTF 模型
async function loadModel(): Promise<Scene | null> {
try {
// 加载场景资源,支持.gltf和.glb格式
const scene = await Scene.load($rawfile('models/scene.glb'));
return scene;
} catch (error) {
console.error('模型加载失败:', error);
return null;
}
}
关键细节: Scene.load() 异步返回 Scene 对象,场景里的网格、材质、纹理、动画、相机和光源随后都挂在这个对象下面。.gltf 文件可能还引用外部 .bin 和纹理文件,目录关系必须跟资源声明一致。
2.4 Component3D 组件
ArkUI 提供 Component3D 组件用于将 ArkGraphics 3D 场景或 glTF 模型渲染到 ArkUI 界面中,支持自定义场景模式与自动场景模式。
@Component
struct Scene3DPage {
private scene: Scene | null = null;
build() {
Column() {
Component3D({ scene: this.scene })
.width('100%')
.height(400)
}
}
aboutToAppear() {
Scene.load($rawfile('models/scene.glb')).then((loadedScene) => {
this.scene = loadedScene;
});
}
}
两种模式的差异:
| 模式 | 传入参数 | 相机/光源 | 手势交互 |
|---|---|---|---|
| 自动场景模式 | glTF 模型(.gltf/.glb) | 框架自动创建 | 自动支持旋转、缩放 |
| 自定义场景模式 | Scene 对象 | 开发者通过 API 创建 | 需开发者接入手势 |
关键细节: 3D 引擎层的对象(scene、resourceFactory、camera、nodeRegistry)的增删改查都走 Scene API,不需要通知 ArkUI 框架。3D 引擎会在同一帧内感知到场景树的变化并重新渲染。
2.5 自定义着色器
ArkGraphics 3D 采用基于物理的渲染(PBR, Physically-Based Rendering)模型,其材质实现遵循通用的 PBR 原理。开发者既可以使用标准材质快速实现真实感效果,也可以创建自定义着色器,通过自定义着色器完全控制渲染计算过程,比如控制某物体不受某光源的影响、自定义边缘描边、高亮效果等个性化视觉呈现。
.shader 文件基于 JSON 格式,包含 compatibility_info、rasterizationState、depthStencilState、colorBlendState 等渲染管线配置。
2.6 资源加载的完整状态管理
生产级 3D 应用需要管理完整的加载状态:
type LoadState = 'idle' | 'loading' | 'ready' | 'failed' | 'released';
class SceneRuntime {
scene: Scene | null = null;
state: LoadState = 'idle';
private generation: number = 0;
nextGeneration(): number {
this.generation += 1;
return this.generation;
}
isCurrent(value: number): boolean {
return value === this.generation && this.state !== 'released';
}
}
关键细节: 用户快速切换模型时,较早发起的 Promise 可能较晚完成,旧结果不能覆盖新页面。丢弃旧结果前还需要调用 destroy() 释放图形资源。SceneResource 提供了 destroy() 方法用于销毁场景资源,释放所有关联的资源或引用。
三、Spatial Recon Kit:3DGS 端侧空间建模
3.1 核心定位
Spatial Recon Kit(空间建模套件)是 HarmonyOS 生态中面向 3DGS 的图形扩展能力,属于 ArkGraphics 3D 模块的扩展,需与 ArkGraphics 3D 模块联合使用。在 ArkTS 开发中,需要同时导入 @kit.ArkGraphics3D 和 @kit.SpatialReconKit;在 C/C++ 开发中,重建能力通过独立的 NDK 库提供。
核心能力:
- 3DGS 模型加载与渲染(spatialRender,6.0.1(21) 起始):支持 MP4、PLY、GLB 三种格式
- 3DGS 模型编辑(spatialEdit,26.0.0 起始):选择、上色、删除、导出
- 端侧三维重建(从 6.1.0(23) 开始):支持通过视觉输入(一系列图像及相机内参、位姿)对三维场景进行重建
3.2 3DGS 技术原理
3D Gaussian Splatting(3DGS)作为一种新兴的场景表示方法,通过大量带属性的三维高斯椭球来描述场景,能够在保持高渲染质量的同时实现实时性能。
| 维度 | 传统 Mesh | 3DGS |
|---|---|---|
| 表示方式 | 三角形网格 | 高斯点云 |
| 反光物体还原 | 差 | 优秀 |
| 端侧重建速度 | 慢 | 快 |
| 输出格式 | GLB、OBJ | PLY、GLB、MP4 |
3.3 加载 3DGS 模型
import { spatialRender } from '@kit.SpatialReconKit';
import { Scene, RenderContext } from '@kit.ArkGraphics3D';
async function loadGSModel() {
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();
if (renderContext != null) {
renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
let scene = await Scene.load();
let uri = "OhosRawFile://assets/gltf/model.glb"; // 3DGS模型的uri
let offset = 0;
let gsNode: spatialRender.GSNode =
await spatialRender.GSPlugin.loadGSNode(scene, { uri, offset }, scene.root);
}
}
GSNode 继承 ArkGraphics 3D 通用 Node,支持位置、缩放、旋转、显隐等常规节点属性,同时支持普通 3DGS 与分块 TiledGS 大场景模型加载。
3.4 内置风格化滤镜
套件内置 4 套后处理滤镜,直接作用于 3DGS 渲染画面,无需修改原始模型数据:
| 滤镜类型 | 常量 ID | 效果说明 |
|---|---|---|
| 复古效果 | RETRO_EFFECT_ID | 复古老照片质感 |
| 漫画风格 | COMIC_EFFECT_ID | 二次元漫画描边风格 |
| 黑白 Bit 效果 | OBRA_DINN_EFFECT_ID | 高对比度黑白版画效果 |
| 颜色编辑 | COLOR_EDITING_EFFECT_ID | 自定义调色、亮度饱和度调整 |
3.5 端侧三维重建(C/C++ NDK)
Native 层提供完整重建流水线:检测能力 → 建会话 → 喂数据帧 → 启动重建 → 查进度 → 暂停/继续 → 保存结果 → 销毁会话。
- 支持传入普通 RGB 图像帧,也支持接入 AR Engine 输出的 AR 帧,借助 SLAM 位姿提升重建精度
- 重建结果可输出 PLY 点云、MP4 运镜视频
- 空间编辑(spatialEdit,26.0.0 起始):提供显式高斯点的编辑能力,支持主体提取(框选/反选/删除)、刚体变换、缩放及 3D 包围盒估计
3.6 设备与地域限制
| 限制项 | 说明 |
|---|---|
| 支持设备 | Phone、Tablet、PC/2in1、TV |
| 模拟器 | 暂不支持模拟器,全部能力需要真机调试 |
| 地域限制 | 仅支持中国境内(香港特别行政区、澳门特别行政区、中国台湾除外) |
| 芯片门槛 | 仅保证 Kirin 9020、Kirin 9030S、Kirin 9030、Kirin 9030 Pro 及以后芯片 |
| 能力查询 | 运行时调用 HMS_SpatialRecon_IsSupport 判断 |
由于空间重建能力会消耗大量系统资源,并非所有设备都支持重建。建议开发者先通过芯片判断,再调用接口查询当前设备是否支持该特性。
四、空间音频
HarmonyOS 7.0 空间音频新增基于 HRTF 的双耳效应渲染及头动追踪能力,解决传统音频缺乏空间方位感的问题,为游戏、影音及沉浸式内容等场景提供更丰富的音频体验。
HRTF(Head-Related Transfer Function,头部相关传输函数) 是空间音频的核心。它描述了声音从声源到人耳的传输特性。人耳通过三种方式定位声音:
| 定位方式 | 描述 | 有效频率 | 定位精度 |
|---|---|---|---|
| ITD(时间差) | 声音到达两耳的时间差 | 低频(<1.5kHz) | 水平方向 |
| ILD(强度差) | 声音到达两耳的强度差 | 高频(>1.5kHz) | 水平方向 |
| HRTF(滤波) | 头部、耳廓对声音的滤波 | 全频段 | 三维空间 |
空间渲染节点根据坐标对音频做 HRTF 卷积,把单声道/立体声 PCM 变成带方位感的双声道。它不依赖系统级的空间音频开关,是应用内的 DSP 渲染,运算发生在手机端。支持六轴 IMU(陀螺仪+加速度计)的设备可实现 1kHz 采样率的头部追踪。
五、沉浸光感组件
沉浸光感是 HarmonyOS 空间化(Spatial UI)的材质体系,通过模拟真实物理光照模型,在组件内产生光晕、反射和折射效果。沉浸光感将材质视作独立界面物质,统一整合其光学行为、空间属性与交互响应能力。
支持的动效能力:
- 光随指动: 光照跟随手指移动,模拟真实光源对材质表面的影响
- 光线勾勒: 组件边缘生成动态轮廓光,强化空间层级的边界感
- 非线性形变: 触控按压时组件产生符合物理规律的形变反馈
开启方式: 沉浸光感提供应用级开启和组件级开启两种方式。应用级开启通过配置文件统一设置应用的沉浸光感开关(在 module.json5 中配置);组件级开启通过 systemMaterial(new ImmersiveMaterial()) 为指定组件启用沉浸光感材质。
关键约束:
| 约束项 | 说明 |
|---|---|
| targetSDKVersion | 不低于 26.0.0 |
| 生效范围 | 弹窗类组件(AlertDialog、ActionSheet、CustomDialog 等)可在全页面生效 |
| Release 版本规格调整 | 仅在 Navigation/NavDestination 标题栏或 Tabs 底部 TabBar 中生效 |
| 功耗 | 开启后需要大量 GPU 资源,需参考功耗优化指导 |
六、综合实战:3D 商品展示应用
6.1 架构设计
@Entry
@Component
struct Product3DPage {
@State scene: Scene | null = null;
@State loadState: string = 'idle';
@State selectedMaterial: number = 0;
private resourceFactory: SceneResourceFactory | null = null;
build() {
Stack() {
if (this.scene) {
Component3D({ scene: this.scene })
.width('100%')
.height('100%')
}
if (this.loadState === 'loading') {
LoadingProgress()
.width(48)
.height(48)
}
Row() {
ForEach(['极夜蓝', '雾银灰', '珊瑚橙'], (material: string) => {
Button(material)
.onClick(() => this.switchMaterial(material))
})
}
.position({ x: 16, y: 600 })
}
.width('100%')
.height('100%')
}
async aboutToAppear() {
this.loadState = 'loading';
try {
this.scene = await Scene.load($rawfile('models/product.glb'));
this.loadState = 'ready';
} catch (error) {
this.loadState = 'failed';
}
}
switchMaterial(material: string) {
// 通过 SceneResourceFactory 修改材质
}
}
6.2 关键设计原则
状态管理: 使用 idle、loading、ready、failed、released 五种状态管理 3D 场景生命周期,配合 generation 序号防止异步竞态。
资源释放: 页面退出时调用 scene.destroy() 释放图形资源,避免内存泄漏。
相机管理: 使用自定义场景模式时,通过 SceneResourceFactory 创建页面自己的相机,确保观察入口确定。
第二部分 习题与答案解读
每题后紧跟答案和解读,共15题。
习题1【单选】ArkGraphics 3D 的系统能力标识
ArkGraphics 3D 的系统能力标识是什么?
A. SystemCapability.ArkUi.Graphics3D
B. SystemCapability.Graphics.SpatialRender
C. SystemCapability.ArkGraphics.3D
D. SystemCapability.Spatial.Computing
答案:A
解读: ArkGraphics 3D 的系统能力标识为 SystemCapability.ArkUi.Graphics3D,首批接口从 API 12 开始支持。SystemCapability.Graphics.SpatialRender 是 Spatial Recon Kit 的 3DGS 模型渲染能力标识。
习题2【判断】Spatial Recon Kit 是独立于 ArkGraphics 3D 的套件
答案:错误
解读: Spatial Recon Kit 是 ArkGraphics 3D 模块的扩展,需与 ArkGraphics 3D 模块联合使用。在 ArkTS 开发中,需要同时导入 @kit.ArkGraphics3D 和 @kit.SpatialReconKit。
习题3【多选】Spatial Recon Kit 支持哪些 3DGS 模型格式?
A. MP4
B. PLY
C. GLB
D. OBJ
E. FBX
答案:A、B、C
解读: Spatial Recon Kit 支持加载 MP4(运镜视频)、PLY(点云格式)和 GLB(二进制 glTF)三种格式。OBJ 和 FBX 不是 3DGS 的输出格式。
习题4【单选】3DGS 重建能力的起始版本
3DGS 端侧重建能力从哪个版本开始支持?
A. HarmonyOS 5.0
B. HarmonyOS 6.0
C. HarmonyOS 6.1.0(23)
D. HarmonyOS 7.0
答案:C
解读: 3DGS 端侧重建能力从 6.1.0(23) 版本开始支持。HarmonyOS 7.0(26) 在此基础上进行了升级和增强,并非首次引入。
习题5【简答】ArkGraphics 3D 的 ECS 架构是什么?
答案: ArkGraphics 3D 的引擎层采用 ECS(Entity-Component-System)架构设计,进行模块化封装(如材质定义、后处理特效等)。
- Entity(实体): 场景中的对象容器,如 SceneNode、GSNode
- Component(组件): 附加到实体的数据和行为,如材质定义、后处理特效
- System(系统): 每帧更新的逻辑,如渲染管线、动画系统
习题6【多选】沉浸光感组件支持哪些动效能力?
A. 光随指动
B. 光线勾勒
C. 非线性形变
D. 粒子爆炸
E. 3D 旋转
答案:A、B、C
解读: 沉浸光感组件支持光随指动、光线勾勒、非线性形变等动效,可快速提升应用核心界面的空间感和沉浸感。
习题7【代码补全】加载 glTF 模型
补全代码,使用 Scene.load 异步加载 glTF 模型。
async function loadModel(): Promise<Scene | null> {
try {
const scene = await Scene.load(__________);
return scene;
} catch (error) {
console.error('模型加载失败:', error);
return null;
}
}
答案:
const scene = await Scene.load($rawfile('models/scene.glb'));
解读: Scene.load() 接受 $rawfile() 返回的资源路径,异步返回 Scene 对象。支持 .gltf 和 .glb 格式。
习题8【简答】Spatial Recon Kit 的设备与地域限制有哪些?
答案:
| 限制项 | 说明 |
|---|---|
| 支持设备 | Phone、Tablet、PC/2in1、TV |
| 模拟器 | 暂不支持模拟器,全部能力需要真机调试 |
| 地域限制 | 仅支持中国境内(港澳台除外) |
| 芯片门槛 | 仅保证 Kirin 9020、Kirin 9030S、Kirin 9030、Kirin 9030 Pro 及以后芯片 |
此外,由于空间重建能力会消耗大量系统资源,并非所有设备都支持重建,建议通过 HMS_SpatialRecon_IsSupport 接口查询。
习题9【判断】3DGS 只能用于空间重建
答案:错误
解读: 3DGS 不仅支持空间重建,还支持模型加载渲染(PLY、GLB、MP4 格式)和风格化滤镜处理(复古效果、漫画风格、黑白 Bit 效果、颜色编辑)。
习题10【代码补全】加载 3DGS 模型
补全代码,使用 Spatial Recon Kit 加载 3DGS 模型。
import { spatialRender } from '@kit.SpatialReconKit';
import { Scene, RenderContext } from '@kit.ArkGraphics3D';
async function loadGSModel() {
let renderContext: RenderContext | null = Scene.getDefaultRenderContext();
if (renderContext != null) {
renderContext.loadPlugin(spatialRender.GSPlugin.__________);
let scene = await Scene.load();
let uri = "OhosRawFile://__________";
let offset = 0;
let gsNode: spatialRender.GSNode =
await spatialRender.GSPlugin.__________;
}
}
答案:
renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);
// ...
let uri = "OhosRawFile://assets/gltf/model.glb";
// ...
let gsNode: spatialRender.GSNode =
await spatialRender.GSPlugin.loadGSNode(scene, { uri, offset }, scene.root);
解读: 需要先加载 GS 渲染插件(PLUGIN_ID),然后通过 loadGSNode 加载 3DGS 模型。
习题11【多选】以下哪些是 Spatial Recon Kit 的内置滤镜?
A. 复古效果
B. 漫画风格
C. 黑白 Bit 效果
D. 颜色编辑
E. 油画风格
答案:A、B、C、D
解读: 套件内置 4 套后处理滤镜:复古效果(RETRO_EFFECT_ID)、漫画风格(COMIC_EFFECT_ID)、黑白 Bit 效果(OBRA_DINN_EFFECT_ID)、颜色编辑(COLOR_EDITING_EFFECT_ID)。
习题12【简答】为什么 3D 场景加载需要管理 generation 序号?
答案: 用户快速切换模型时,较早发起的 Promise 可能较晚完成。如果不管理 generation 序号,旧结果可能覆盖新页面,导致 UI 串线。同时,旧加载成功后仍然得到一个真实 Scene,丢弃旧结果前还需要调用 destroy() 释放图形资源,否则会造成图形资源泄漏。
习题13【设计题】设计一个 3D 商品展示应用的核心功能
请设计一个 3D 商品展示应用的核心功能。
答案示例:
模型加载: 使用 Scene.load($rawfile('models/product.glb')) 异步加载商品 3D 模型,配合 Component3D 显示。
材质切换: 通过 SceneResourceFactory 获取材质资源,修改 PBR 材质的颜色参数。
相机控制: 通过 Scene API 控制相机位置和旋转,实现商品 360° 查看。
状态管理: 使用 idle/loading/ready/failed/released 五种状态管理场景生命周期。
习题14【简答】空间音频的 HRTF 原理是什么?
答案: HRTF(Head-Related Transfer Function,头部相关传输函数)描述了声音从声源到人耳的传输特性。人耳通过三种方式定位声音:
- ITD(时间差): 声音到达两耳的时间差,有效频率为低频(<1.5kHz)
- ILD(强度差): 声音到达两耳的强度差,有效频率为高频(>1.5kHz)
- HRTF(滤波): 头部、耳廓对声音的滤波,全频段有效
HarmonyOS 7.0 空间音频新增基于 HRTF 的双耳效应渲染及头动追踪能力。
习题15【综合论述】如何构建一个完整的空间计算应用?
答案: 构建完整的空间计算应用需要整合以下核心技术:
1. 3D 渲染(ArkGraphics 3D)。 使用 Scene.load() 加载 glTF 模型,使用 Component3D 显示场景。采用 ECS 架构管理场景中的实体和组件。
2. 空间重建(Spatial Recon Kit)。 使用 3DGS 技术进行端侧三维重建,支持 PLY、GLB、MP4 格式输出。注意设备(不支持模拟器)和地域(仅中国境内)限制。
3. 空间音频(SpatialAudioKit)。 使用 HRTF 双耳效应渲染和头动追踪,为游戏、影音场景提供方位感。
4. 沉浸光感(ArkUI)。 使用沉浸光感组件实现光随指动、光线勾勒、非线性形变等动效,提升界面的空间感和沉浸感。
5. 状态管理。 使用 idle/loading/ready/failed/released 五种状态管理 3D 场景生命周期,配合 generation 序号防止异步竞态。
第三部分 知识点总结
1. 技术栈全景
| 组件 | 职责 | 系统能力标识 |
|---|---|---|
| ArkGraphics 3D | 3D 场景渲染 | SystemCapability.ArkUi.Graphics3D |
| Spatial Recon Kit | 3DGS 空间建模 | SystemCapability.Graphics.SpatialRender |
| SpatialAudioKit | 空间音频 | — |
| 沉浸光感组件 | 空间界面动效 | — |
2. ArkGraphics 3D 关键信息
| 属性 | 值 |
|---|---|
| Kit 名称 | ArkGraphics 3D |
| 导入路径 | @kit.ArkGraphics3D |
| 底层模块 | @ohos.graphics.scene |
| 首批接口 | API 12 |
| 架构 | ECS(Entity-Component-System) |
| 支持设备 | Phone、PC/2in1、Tablet、TV、Wearable |
3. Spatial Recon Kit 关键信息
| 属性 | 值 |
|---|---|
| 定位 | ArkGraphics 3D 的扩展模块 |
| 支持格式 | PLY、GLB、MP4 |
| 滤镜 | 复古、漫画、黑白 Bit、颜色编辑 |
| 重建能力 | 从 6.1.0(23) 开始 |
| 设备限制 | 暂不支持模拟器 |
| 地域限制 | 仅中国境内 |
| 芯片门槛 | Kirin 9020 及以上 |
4. 沉浸光感约束
| 约束项 | 说明 |
|---|---|
| targetSDKVersion | 不低于 26.0.0 |
| 开启方式 | 应用级(module.json5)/ 组件级(systemMaterial) |
| Release 生效范围 | Navigation/NavDestination 标题栏、Tabs 底部 TabBar |
5. 常见陷阱
- 将 Spatial Recon Kit 描述为独立套件(它是 ArkGraphics 3D 的扩展)
- 将 3DGS 重建能力描述为 HarmonyOS 7.0 首次引入(实际从 6.1.0(23) 开始)
- 忽略模拟器不支持的限制
- 忽略中国境内地域限制
- 忽略芯片门槛(Kirin 9020 及以上)
- 忘记在丢弃旧 Scene 前调用
destroy()释放资源 - 不管理 generation 序号导致异步竞态
6. 行动清单
- 使用
Scene.load($rawfile('...'))异步加载 glTF 模型 - 使用
Component3D显示 3D 场景 - 使用
SceneResourceFactory管理材质和相机 - 使用 Spatial Recon Kit 加载 3DGS 模型(PLY/GLB/MP4)
- 使用内置滤镜实现风格化渲染
- 管理 idle/loading/ready/failed/released 五种状态
- 在丢弃旧 Scene 前调用
destroy()释放资源 - 注意模拟器不支持、中国境内地域限制和芯片门槛
- 使用 HRTF 空间音频增强沉浸感
- 使用沉浸光感组件提升界面空间感
更多推荐



所有评论(0)