企业官网建设流程全解析

【ArkUI进阶练中学】第17课 完整精讲版

HarmonyOS 7.0 空间计算与3D渲染实战

主要目标：系统掌握 HarmonyOS 7.0 空间计算的技术栈全景，深入理解 ArkGraphics 3D 渲染管线、Spatial Recon Kit 3DGS 端侧重建、空间音频与沉浸光感组件的核心机制与最佳实践，并能够构建功能完整的空间计算应用。

第一部分 深度精讲

一、建立心智模型：HarmonyOS 空间计算技术栈全景

1.1 五层技术架构

HarmonyOS 7.0 的空间计算不是单一技术点，而是一套完整的技术栈，覆盖从应用层到硬件层的五个层次：

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场景并完成渲染。

关键信息：

@ohos.graphics.scene将3D开发相关模块的API组织在一起，方便开发者使用。本模块首批接口从 API 12 开始支持，后续版本新增接口采用上角标单独标记起始版本。

2.2 ECS 架构

ArkGraphics 3D 的引擎层采用 ECS（Entity-Component-System）架构设计，进行模块化封装（如材质定义、后处理特效等），为开发者提供了灵活易用的开发套件。

接口层基于引擎的 ECS Framework，通过 NAPI 层对数据进行组织处理，向开发者暴露简单易用的3D渲染接口，支持开发者使用少量代码完成3D场景的开发。

2.3 Scene 场景管理

Scene 是 ArkGraphics 3D 的基础模块，提供SceneResourceParameters、SceneNodeParameters等通用数据类型，同时提供 glTF 模型加载、场景元素、资源创建等基础方法。3D场景是以树状结构进行组织的，通过操作节点属性以及节点树结构可以改变3D场景。

import{Scene}from'@kit.ArkGraphics3D';// 异步加载 glTF 模型asyncfunctionloadModel():Promise<Scene|null>{try{// 加载场景资源，支持.gltf和.glb格式constscene=awaitScene.load($rawfile('models/scene.glb'));returnscene;}catch(error){console.error('模型加载失败:',error);returnnull;}}

关键细节：Scene.load()异步返回 Scene 对象，场景里的网格、材质、纹理、动画、相机和光源随后都挂在这个对象下面。.gltf文件可能还引用外部.bin和纹理文件，目录关系必须跟资源声明一致。

2.4 Component3D 组件

ArkUI 提供Component3D组件用于将 ArkGraphics 3D 场景或 glTF 模型渲染到 ArkUI 界面中，支持自定义场景模式与自动场景模式。

@Componentstruct Scene3DPage{privatescene: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;});}}

两种模式的差异：

关键细节：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 应用需要管理完整的加载状态：

typeLoadState='idle'|'loading'|'ready'|'failed'|'released';classSceneRuntime{scene:Scene|null=null;state:LoadState='idle';privategeneration:number=0;nextGeneration():number{this.generation+=1;returnthis.generation;}isCurrent(value:number):boolean{returnvalue===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）作为一种新兴的场景表示方法，通过大量带属性的三维高斯椭球来描述场景，能够在保持高渲染质量的同时实现实时性能。

3.3 加载 3DGS 模型

import{spatialRender}from'@kit.SpatialReconKit';import{Scene,RenderContext}from'@kit.ArkGraphics3D';asyncfunctionloadGSModel(){letrenderContext:RenderContext|null=Scene.getDefaultRenderContext();if(renderContext!=null){renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);letscene=awaitScene.load();leturi="OhosRawFile://assets/gltf/model.glb";// 3DGS模型的uriletoffset=0;letgsNode:spatialRender.GSNode=awaitspatialRender.GSPlugin.loadGSNode(scene,{uri,offset},scene.root);}}

GSNode继承 ArkGraphics 3D 通用Node，支持位置、缩放、旋转、显隐等常规节点属性，同时支持普通 3DGS 与分块 TiledGS 大场景模型加载。

3.4 内置风格化滤镜

套件内置 4 套后处理滤镜，直接作用于 3DGS 渲染画面，无需修改原始模型数据：

3.5 端侧三维重建（C/C++ NDK）

Native 层提供完整重建流水线：检测能力 → 建会话 → 喂数据帧 → 启动重建 → 查进度 → 暂停/继续 → 保存结果 → 销毁会话。

• 支持传入普通 RGB 图像帧，也支持接入 AR Engine 输出的 AR 帧，借助 SLAM 位姿提升重建精度
• 重建结果可输出 PLY 点云、MP4 运镜视频
• 空间编辑（spatialEdit，26.0.0 起始）：提供显式高斯点的编辑能力，支持主体提取（框选/反选/删除）、刚体变换、缩放及 3D 包围盒估计

3.6 设备与地域限制

由于空间重建能力会消耗大量系统资源，并非所有设备都支持重建。建议开发者先通过芯片判断，再调用接口查询当前设备是否支持该特性。

四、空间音频

HarmonyOS 7.0 空间音频新增基于 HRTF 的双耳效应渲染及头动追踪能力，解决传统音频缺乏空间方位感的问题，为游戏、影音及沉浸式内容等场景提供更丰富的音频体验。

HRTF（Head-Related Transfer Function，头部相关传输函数）是空间音频的核心。它描述了声音从声源到人耳的传输特性。人耳通过三种方式定位声音：

空间渲染节点根据坐标对音频做 HRTF 卷积，把单声道/立体声 PCM 变成带方位感的双声道。它不依赖系统级的空间音频开关，是应用内的 DSP 渲染，运算发生在手机端。支持六轴 IMU（陀螺仪+加速度计）的设备可实现 1kHz 采样率的头部追踪。

五、沉浸光感组件

沉浸光感是 HarmonyOS 空间化（Spatial UI）的材质体系，通过模拟真实物理光照模型，在组件内产生光晕、反射和折射效果。沉浸光感将材质视作独立界面物质，统一整合其光学行为、空间属性与交互响应能力。

支持的动效能力：

• 光随指动：光照跟随手指移动，模拟真实光源对材质表面的影响
• 光线勾勒：组件边缘生成动态轮廓光，强化空间层级的边界感
• 非线性形变：触控按压时组件产生符合物理规律的形变反馈

开启方式：沉浸光感提供应用级开启和组件级开启两种方式。应用级开启通过配置文件统一设置应用的沉浸光感开关（在 module.json5 中配置）；组件级开启通过systemMaterial(new ImmersiveMaterial())为指定组件启用沉浸光感材质。

关键约束：

六、综合实战：3D 商品展示应用

6.1 架构设计

@Entry@Componentstruct Product3DPage{@Statescene:Scene|null=null;@StateloadState:string='idle';@StateselectedMaterial:number=0;privateresourceFactory: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%')}asyncaboutToAppear(){this.loadState='loading';try{this.scene=awaitScene.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 模型。

asyncfunctionloadModel():Promise<Scene|null>{try{constscene=awaitScene.load(__________);returnscene;}catch(error){console.error('模型加载失败:',error);returnnull;}}

答案：

constscene=awaitScene.load($rawfile('models/scene.glb'));

解读：Scene.load()接受$rawfile()返回的资源路径，异步返回 Scene 对象。支持 .gltf 和 .glb 格式。

习题8【简答】Spatial Recon Kit 的设备与地域限制有哪些？

答案：

此外，由于空间重建能力会消耗大量系统资源，并非所有设备都支持重建，建议通过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';asyncfunctionloadGSModel(){letrenderContext:RenderContext|null=Scene.getDefaultRenderContext();if(renderContext!=null){renderContext.loadPlugin(spatialRender.GSPlugin.__________);letscene=awaitScene.load();leturi="OhosRawFile://__________";letoffset=0;letgsNode:spatialRender.GSNode=awaitspatialRender.GSPlugin.__________;}}

答案：

renderContext.loadPlugin(spatialRender.GSPlugin.PLUGIN_ID);// ...leturi="OhosRawFile://assets/gltf/model.glb";// ...letgsNode:spatialRender.GSNode=awaitspatialRender.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. 技术栈全景

2. ArkGraphics 3D 关键信息

3. Spatial Recon Kit 关键信息

4. 沉浸光感约束

5. 常见陷阱

• 将 Spatial Recon Kit 描述为独立套件（它是 ArkGraphics 3D 的扩展）
• 将 3DGS 重建能力描述为 HarmonyOS 7.0 首次引入（实际从 6.1.0(23) 开始）
• 忽略模拟器不支持的限制
• 忽略中国境内地域限制
• 忽略芯片门槛（Kirin 9020 及以上）
• 忘记在丢弃旧 Scene 前调用destroy()释放资源
• 不管理 generation 序号导致异步竞态

6. 行动清单

1. 使用Scene.load($rawfile('...'))异步加载 glTF 模型
2. 使用Component3D显示 3D 场景
3. 使用SceneResourceFactory管理材质和相机
4. 使用 Spatial Recon Kit 加载 3DGS 模型（PLY/GLB/MP4）
5. 使用内置滤镜实现风格化渲染
6. 管理 idle/loading/ready/failed/released 五种状态
7. 在丢弃旧 Scene 前调用destroy()释放资源
8. 注意模拟器不支持、中国境内地域限制和芯片门槛
9. 使用 HRTF 空间音频增强沉浸感
10. 使用沉浸光感组件提升界面空间感