〖共创稿事节〗HarmonyOS 7 新特性实战（10）：普通 GLB 模型的加载、视角控制与注释入口

先验证普通网格路径API 26 模拟器与 HBN-AL80 真机已经运行普通 GLB 教学样本模型共 8 个节点、64 个三角形文件只有数 KB。它由项目脚本生成是抽象的带角、带翼几何造型不是古代神兽的考据复原也不是 3DGS 重建结果。这种小样本可以先排除素材下载、授权和复杂模型性能等变量专门核对加载路径。加载器直接使用 ArkGraphics 3D 的 Scene.load未调用 Spatial Recon Kit 插件。随包 GLB 经场景加载后交给 Component3D 显示模型浏览与空间重建分别使用各自的资源和接口。constsceneawaitScene.load(uri);constcameraawaitscene.getResourceFactory().createCamera({name:MeshCamera});camera.nearPlane0.01;camera.farPlane100;camera.fovMath.PI/3;camera.enabledtrue;模型使用随包资源不请求网络。页面在加载完成后才把 Scene 绑定到 Component3D发生错误则显示具体错误信息。示例中的节点数量来自固定教学资源不是对任意导入 GLB 的自动统计。让相机围绕模型转动页面使用两个 Slider 分别控制水平角和距离距离限制在 28。相机位置绕 Y 轴变化同时更新相机朝向避免只移动位置却继续看向原来的方向。当前环绕中心高度是 0.25适配本样本的坐标范围更换模型后应按包围盒重新计算。constdMath.max(2,Math.min(8,distance));this.camera.position{x:Math.sin(yaw)*d,y:0.25,z:Math.cos(yaw)*d};this.camera.rotation{x:0,y:Math.sin(yaw/2),z:0,w:Math.cos(yaw/2)};模拟器已检查正面、78° 侧面和复位侧面显示出模型厚度变化。角部、翼部按钮保留为教学注释入口模型表面另外接入射线查询命中后可打开关联条目。屏幕标签投影、标签遮挡剔除与双指手势仍属后续范围。点击模型时如何确定阅读目标Camera.raycast 从 API 20 起可用属于本系列空间化改造的基础能力。传入坐标为组件内的 01 归一化位置原点在左上角。用 ClickEvent 的局部坐标除以 Component3D 的实际宽高不要用整个屏幕尺寸也不要再乘设备像素比。接口坐标说明服务层保留相机引用和版本号。视角改变或场景销毁会使旧查询失效空数组表示有效查询没有命中undefined 则表示本次结果不应再应用到页面。asyncpick(x:number,y:number,width:number,height:number):Promisestring|undefined{constcamerathis.camera;constgenerationthis.generation;if(!camera||width0||height0||!Number.isFinite(x)||!Number.isFinite(y)||x0||y0||xwidth||yheight){returnundefined;}consthitsawaitcamera.raycast({x:x/width,y:y/height},{});if(generation!this.generation||camera!this.camera){returnundefined;}returnhits.length0?hits[0].node.name:;}页面再用请求序号保护连续点击只有最后一次查询能更新提示。射线结果按距离排序当前选择第一项这不是自行实现的三角形求交算法。模型节点名称必须与内容配置匹配本教学模型只允许八个已知节点启用阅读按钮未知节点不会自动被当作内容 ID。组件尺寸与点击事件需要来自同一坐标空间。下面是页面实际使用的绑定布局变化时更新宽高点击时传入局部坐标。这里没有另放透明按钮覆盖模型点击对象就是 Component3D。Component3D({scene:this.scene}).width(100%).layoutWeight(1).id(meshViewport).onAreaChange((_old:Area,area:Area){this.viewportWidthNumber(area.width);this.viewportHeightNumber(area.height);}).onClick((event:ClickEvent){this.pick(event);})查询开始时先清空 hit阅读按钮由 readingEntryId 控制在查询结果应用时更新。等待过程中发生第二次点击旧请求即使稍后成功也会因为版本不匹配而退出。active 用于保护离页后的回调控制器另有相机代次检查覆盖查询期间改变观察角度的情况。页面处理如下字段与前面的控制器配套使用privateasyncpick(event:ClickEvent):Promisevoid{constversionthis.pickVersion;this.hit;try{constnameawaitthis.controller.pick(event.x,event.y,this.viewportWidth,this.viewportHeight);if(!this.active||version!this.pickVersion||nameundefined){return;}consthotspotfindMeshHotspot(name||);this.hithotspot?.nodeName||;this.readingEntryIdhotspot?.entryId||;this.readingLabelhotspot?阅读关联条目${hotspot.title}:阅读关联条目;this.notehotspot?${hotspot.note}此映射来自教学配置不表示模型具有史料依据。:(name?未配置网格${name}阅读入口保持禁用。:未命中模型请点击可见网格。);}catch(error){if(this.activeversionthis.pickVersion){this.note命中失败${(errorasError).message};}}}控制器的 generation 与页面的 pickVersion 分别处理相机状态和点击先后不能只保留其中一个。只检查页面版本会把同一次点击在转动相机后返回的结果当成有效只检查相机版本又无法区分同一视角下两次点击的完成顺序。当前相机失效分支有宿主机测试连续点击的页面版本保护已接入但尚无乱序 UI 回调的自动回归测试。八个节点通过 MeshHotspotMapping 显式关联阅读样本躯干、头部和双足对应旋龟双角和双翼对应鹿蜀。抽象教学模型并不是神兽复原模型部位也不能作为原典解释的依据。应用通过 entryId 传递目标阅读页在本地数据中查找找不到目标时保留可操作列表并提示不会打开错误条目。图中展示躯干命中后的说明与阅读入口。模型节点到条目的路由由下表配置按钮使用 readingEntryId 是否为空决定可点击状态。节点阅读条目 ID标题body、head、leftFoot、rightFootxuangui旋龟leftHorn、rightHorn、leftWing、rightWinglushu鹿蜀模拟器中已经完成躯干命中、打开详情、回到模型页再点击左上空白区域。空白查询提示未命中同时禁用关联阅读避免沿用先前选中的 body。当前阅读页的底部返回按钮沿路由栈回到模型页虽然文案仍为“返回目录”后续应随来源改为更准确的返回说明。constparamsthis.getUIContext().getRouter().getParams()asReadingRouteParams|undefined;if(params?.entryId){constentrythis.entries.find((item:ReadingEntry)item.idparams.entryId);if(entry){this.select(entry);}else{this.feedback关联条目不存在可从列表选择;}}输入情况处理规则验证方式点击可见模型读取最近命中节点已配置节点启用阅读真机八个节点的映射提示与按钮点击空白清除上次选择禁用阅读模拟器与真机空白点击查询期间转动相机或离页丢弃过期结果相机替身异步测试越界坐标或零尺寸不调用射线查询服务边界测试传入不存在的阅读 ID提示并回到可选列表已实现异常路由尚未实机验收离开页面后处理晚到资源加载器维护 generation。每次加载前先清理前一场景保存本次 generationScene 或相机异步返回时若 generation 已变化立即销毁该场景并返回不把它重新挂到离开的页面。相机创建抛错时同样销毁 Scene页面显示失败原因。加载不是单个 awaitScene.load 与 createCamera 都可能在页面离开后才完成所以两处等待后都要检查。实际加载方法标明了各分支负责销毁的资源asyncload(uri:ResourceStr):PromiseScene|undefined{this.dispose();constgenerationthis.generation;constsceneawaitScene.load(uri);try{if(generation!this.generation){scene.destroy();returnundefined;}constcameraawaitscene.getResourceFactory().createCamera({name:MeshCamera});camera.nearPlane0.01;camera.farPlane100;camera.fovMath.PI/3;camera.clearColor{r:0.04,g:0.08,b:0.13,a:1};camera.enabledtrue;if(generation!this.generation){scene.destroy();returnundefined;}this.scenescene;this.cameracamera;this.setView(0,4);returnscene;}catch(error){scene.destroy();throwerrorasError;}}示例设置了 clearColor但截图的背景来自场景环境不能用这项赋值推断最终像素颜色。初始化 setView 会更新相机代次使后续射线查询基于已设定的视角。销毁时先清空持有的相机再释放 Scene避免下一次查询继续使用旧引用。dispose():void{this.generation;this.cameraundefined;if(this.scene){this.scene.destroy();this.sceneundefined;}}这部分有实际服务代码的替身测试离页后模型才返回、相机分配失败、观察距离边界、重复清理均有检查。替身测试说明应用如何处理生命周期不代替真实 GPU 内存分析。当前程序样本的显示则另有模拟器截图。真机上的节点映射与阅读路径2026-09-20在 HBN-AL80API 26上依次点击八个模型节点均回读配置中的关联条目。躯干、头部、左右足显示旋龟左右角、左右翼显示鹿蜀。点击位置应落在可见网格上足部与躯干在画面中距离较近点击躯干投影范围会得到 body需要按模型实际位置选择足部。八个节点均检查到映射提示与按钮其中躯干入口实际打开旋龟正文左翼入口实际打开鹿蜀正文其余六个节点的记录止于映射结果。回到模型页点击空白区域页面提示未命中并禁用阅读按钮拖动视角 Slider 后回读 57°模型显示随之改变。调整视角时清除旧入口下一次阅读目标由新视角下的点击确定。从命中入口扩展为屏幕标签当前实现的业务链是“模型命中 → 已知节点 → 阅读条目”。屏幕上跟随部位移动的标签需要另一条“节点局部点 → 世界变换 → 相机投影 → 裁剪”的坐标链。射线返回一个节点名称并不会自动生成标签位置。因此当前版本保留已验证的点击入口投影标签作为明确的后续功能。模型换版时节点名称、原点、朝向和单位应一起确认。现有八个名称只适用于当前随包样本若导出工具改变节点命名命中仍可能成功但阅读白名单会拒绝新名称。这个行为比把未知节点误关联到原典更容易排查。相机转动、缩放和复位时立即清除旧阅读入口。八个节点名称均有宿主机回归检查未知名称返回 undefined替换正式模型时需要连同模型版本、节点表和资料来源一并复核。交互能力当前范围后续验收条件模型加载与相机控制固定样本、Slider、复位已实现角度切换已实测更换模型后重新计算初始视角和观察距离点击命中与阅读真机八个节点映射正确躯干→旋龟、左翼→鹿蜀已进入详情空白处禁用入口换版模型后核对全部节点名称与目标条目跟随模型的文字标签未实现正面、侧面、背面分别核对位置与裁剪标签遮挡未实现明确遮挡算法并检查凹陷、背面和相机后方单指旋转与双指缩放未实现当前使用 Slider检查点击与拖动冲突、缩放边界及阅读滚动标签的世界位置与屏幕位置应分开管理。投影后先排除相机后方和屏幕外的点再考虑遮挡。只有点坐标没有法线时不能直接判断表面是否背向相机深度或射线遮挡检查也需要单独测量查询频率与成本。隐藏空间标签时仍应保留普通列表入口让读者能到达同一个原典条目。当前样本很小适合发现坐标、路由和状态问题不能据此推断复杂模型的帧率、显存占用或功耗。正式模型需要再验证贴图预算、反复进入退出以及较慢加载时的资源释放。已有的相机替身测试覆盖应用分支模拟器截图证明本样本的实际路径两类结果各自承担不同证据。参考ArkGraphics 3D 场景构建与管理。