纹渊 HarmonyOS 7 工程实战（03）：GLTF/GLB 模型库的数据目录设计

一、问题与目标纹渊的 3D 预览需要面对多个载体模型头盔、动物、杯体或其他商品形态。模型如果只是散落在资源目录里页面很快会变成一堆硬编码路径后续新增载体、替换模型或做降级提示时维护成本会越来越高。更稳的做法是把模型当成目录数据来管理。每个模型都应该有名称、资源路径、默认缩略图、适用纹样区域和失败提示。页面只消费目录项不直接关心底层资源怎么组织。这样模型库扩展时页面状态不会跟着重写。二、实现思路模型目录可以先从最小字段开始id、displayName、resource、previewImage、materialSlot 和 fallbackText。id 用来保存选择状态resource 指向 GLTF/GLB 资源materialSlot 标记纹样最终要进入哪个材质节点fallbackText 用于模型加载失败时的界面提示。加载流程也要分层目录读取负责提供候选项模型加载负责创建 Scene材质绑定负责把纹样结果放进节点页面只处理选中态和错误态。这样做的好处是模型数量增加时业务链路仍然保持稳定。模型字段处理方式id保存用户选择避免显示名变更影响状态恢复resource指向 GLTF/GLB 资源统一交给模型加载服务处理materialSlot标记纹样需要替换的材质节点或贴图槽位fallbackText加载失败时给出可理解的降级说明三、关键实现模型加载服务只暴露一个入口接收资源路径返回可绑定材质的场景对象。页面不直接创建底层资源也不把节点查找逻辑写进组件。async function loadModel(path: ResourceStr): PromiseScene { const scene await Scene.load(path) const factory scene.getResourceFactory() if (scene.root ! undefined) { scene.root.position { x: 0, y: 0, z: 0 } } if (factory ! null) { const camera await factory.createCamera({ name: main-camera }) scene.root?.addChild(camera) } return scene }这种写法把 3D 资源的不确定性包在服务层里。模型文件缺失、节点名称变化、材质槽位不匹配都可以在服务层返回明确错误页面只需要显示降级状态或切换到二维预览。目录化还有一个实际好处不同载体可以共享同一套页面组件。新增一个 GLB 模型时优先改目录数据和材质槽位不需要改创作页的交互结构。四、失败场景与取舍模型库最容易踩的坑是把资源路径和页面选择写死。短期看能跑长期看每新增一个载体都要改页面。另一个问题是材质节点没有稳定标识模型换版后贴图失效但页面仍然显示“生成成功”。降级策略要提前准备。模型加载失败时不应该让页面停在空白 3D 容器可以保留 Canvas 预览、显示模型资源不可用提示并允许用户继续导出平面纹样。这样 3D 能力异常不会拖垮整个创作流程。五、验证步骤打开创作入口确认标题、主要卡片、底部操作区和预览区域显示正常。走一遍主流程观察加载态、成功态和下一步按钮是否同步变化。人为制造空输入、重复点击或不可用条件确认页面给出可理解的提示。返回上一页再进入确认选中态、预览结果和关键状态没有漂移。在较窄窗口和较宽窗口各看一遍确认文字、卡片和按钮没有重叠。六、总结GLTF/GLB 模型库的数据目录设计核心是把资源、材质槽位和失败提示从页面里拿出来。页面只处理选中态模型服务处理资源细节后续扩展载体时会更稳。