示例工程：GSAssetGate｜页面 GSImportPage｜资产 GS-052 > 说明：本文提供可静态审查的导入前置逻辑和官方接口调用边界。演示清单与状态属于示例数据，不代表模型已在设备上成功渲染或完成3D重建。一个 3DGS 模型进来，文件名看着像 .glb，并不能说明它已经准备好交给渲染引擎。真实项目里，模型可能刚从临时目录复制出来，用户又点了一次导入；前一次 Promise 还没结束，下一次选择已经替换了页面上的当前资产。即使 SDK 后来正确加载了模型，业务层也可能把旧任务的结果贴在新页面上。因此这篇文章不把“几分钟完成端侧重建”当成已验证结果，也不假设每台手机都支持 Spatial Recon Kit。我们只解决一个更靠前的工程问题：在调用 GSPlugin.loadGSNode 前，让资源清单、设备限制、异步任务身份三者能够相互核对。用于示例的资产是 GS-052，文件 studio_052.glb，记录大小 42.6 MiB；它是演示夹具，不附带真实 3D 模型。## 一、先把“能选文件”与“能加载模型”拆开Spatial Recon Kit 用来扩展 ArkGraphics 3D 的 3DGS 能力，官方介绍提到 MP4、PLY、GLB 等模型资源格式。这里的“支持”不是说所有同扩展名文件都有效，更不是给任意 MP4 视频承诺 3DGS 可渲染。模型的容器、内部数据、读取权限与硬件条件都需要具体核查。官方说明该 Kit 暂不支持模拟器，并给出适用设备与地区限制。开发时可以在模拟器里检查 ArkUI 列表、状态栏和输入门禁，但不能靠模拟器界面宣称 GSPlugin 已完成端侧加载。真实设备上的能力支持情况仍应结合对应系统能力、设备列表与实际 SDK 文档确认。我给 GSAssetGate 设置四个前置门槛：资产 ID 是否存在、扩展名是否在本工程允许清单内、文件字节数是否处于本应用的体验预算、资源 URI 是否已经指向工程可访问的本地位置。它们只负责拦截明显无效输入，不负责证明模型内容正确。### 1. 业务格式白名单应写成可读的规则下面的纯 ArkTS 函数既不需要启动渲染引擎，也不依赖模型 SDK 的运行环境。80 MiB 是这个示例自己设置的缓存体验上限，不是华为公布的 Spatial Recon Kit 最大文件大小。这样做是为了把产品约束与平台约束区别开。arktsinterface GSManifest { assetId: string; filename: string; uri: string; bytes: number;}interface GateResult { allowed: boolean; reason: string;}const DEMO_BYTE_LIMIT: number = 80 * 1024 * 1024;function inspectManifest(item: GSManifest): GateResult { if (item.assetId.trim().length === 0 || item.uri.trim().length === 0) { return { allowed: false, reason: 'MISSING_ID_OR_URI' }; } const name: string = item.filename.toLowerCase(); const ext: string = name.substring(name.lastIndexOf('.') + 1); if (['glb', 'ply', 'mp4'].indexOf(ext) < 0) { return { allowed: false, reason: 'UNSUPPORTED_EXTENSION' }; } if (!Number.isFinite(item.bytes) || item.bytes <= 0 || item.bytes > DEMO_BYTE_LIMIT) { return { allowed: false, reason: 'APP_SIZE_BUDGET' }; } return { allowed: true, reason: 'PRECHECK_PASS' };}````filename`、`uri`、`bytes` 都来自业务清单，不应从用户可改的文件名猜测真实字节长度。实现时要用实际文件统计结果替换 bytes，再考虑文件变更时间或摘要校验。一个后缀符合要求的文件仍可能截断、加密或与真正容器格式不匹配，所以 `PRECHECK_PASS` 只能解释为“允许进入下一阶段”，不能显示“模型验证通过”。与其在页面里堆满复杂的错误弹窗，不如把原因码稳定下来。例如格式不符提示“此文件类型暂未开放”，预算超限提示“文件超过本应用当前导入预算”，模型内容损坏则留给真正的加载失败回调。这样一条客服日志就能区分业务拒绝与平台解析失败。## 二、异步加载最怕旧结果污染新选择### 1. 一个资产加载动作只认一个操作序号官方 API 变更记录中可核对 `spatialRender.GSPlugin.loadGSNode(scene, params, parent?)`，第二个参数 `GSImportSettings` 至少包含 `uri`，并可提供 `offset`。它在已准备好的 ArkGraphics 3D `Scene` 中加载 GS 节点。这里不自行发明初始化、压缩或重建进度接口，而把创建 Scene 视为宿主渲染页面独立完成的步骤。arktsimport { Scene } from ‘@kit.ArkGraphics3D’;import { spatialRender } from ‘@kit.SpatialReconKit’;class GSLoadCoordinator { private generation: number = 0; private loading: boolean = false; async load(scene: Scene, asset: GSManifest): Promise { const gate: GateResult = inspectManifest(asset); if (!gate.allowed) return gate.reason; if (this.loading) return ‘ALREADY_LOADING’; const myGeneration: number = ++this.generation; this.loading = true; try { const settings: spatialRender.GSImportSettings = { uri: asset.uri, offset: 0 }; await spatialRender.GSPlugin.loadGSNode(scene, settings); if (myGeneration !== this.generation) return ‘STALE_RESULT’; return ‘LOAD_RESOLVED’; } catch (err) { console.error(GSAssetGate/${asset.assetId} load error ${JSON.stringify(err)}); return ‘LOAD_FAILED’; } finally { this.loading = false; } } invalidatePending(): void { this.generation += 1; }}````generation是业务侧用来拒绝旧响应的数字，不是 SDK 的任务 ID；调用invalidatePending()也**不能取消已经启动的底层加载或释放场景节点**。因此上面的实现明确把STALE_RESULT 当作提示状态，真实工程仍要依据 ArkGraphics 3D 的节点生命周期规则处理已创建对象。loading阻止同一控制器上的重复操作，却不能跨进程、跨页面自动同步。这里用LOAD_RESOLVED而不是RENDER_READY也有原因：Promise 解析只表示对应加载 API 的这一阶段结束，是否已经进入可见场景，仍与渲染循环、相机、材质和宿主 Scene 状态有关。文章不替设备制造“加载耗时 1.2 秒”一类未经测试的数字。![](https://i-blog.csdnimg.cn/direct/88a5e5eb7bc34abb8960f8e6919b8b8d.png)### 2. 临时文件 URI 与资源 URI 不能混为一谈官方示例会出现OhosRawFile://…形式的资源路径，自己的文件 URI 则可能来自应用沙箱、用户选择器或其他系统受控位置。不能把content://、相册 URI 和 rawfile 路径统一当作文件系统绝对路径直接交给底层 SDK。页面层至少要记录来源、访问期限及是否做过受控复制。导入动作应该拥有自己的“资产快照”。假设用户先选 GS-052，随后选择 GS-053，前一份 URI 可能还被后台加载逻辑持有。此时清掉页面的文件名并不代表底层对象被自动释放。更稳妥的是在提交加载前冻结 assetId/uri/bytes，变更当前选择时让旧序号失效，并在真正可释放资源时再进行清理。## 三、把预检结果与设备能力放在同一个页面模拟界面把 GS-052作为当前资产，显示文件名studio_052.glb、记录大小 42.6 MiB、应用预算 80 MiB、状态 PRECHECK_PASS，下一行写 WAIT_DEVICE。最后一项是产品自己的等待阶段，不是 SDK 的状态码。这样展示有意拒绝把“文件清单合法”装成“模型已经重建完成”。![](https://i-blog.csdnimg.cn/direct/be9bf35d50b042abaed8461ec41907b1.png)为了让界面不依赖渲染服务也可以验证，我们单独构建一个预检按钮。下面这段 ArkUI 演示逻辑只调用前面定义的纯函数，不启动 Scene；因此即使在模拟器里显示绿色的 PRECHECK_PASS，也只能证明清单分支逻辑与 UI 更新通路按预期设计，不代表 GSPlugin 在模拟器可用。```arkts@Entry@Componentstruct GSImportPage { @State resultText: string = 'NOT_CHECKED'; @State nextStep: string = 'WAIT_INPUT'; private readonly item: GSManifest = { assetId: 'GS-052', filename: 'studio_052.glb', uri: 'OhosRawFile://assets/gltf/studio_052.glb', bytes: 44669338 // 演示清单约 42.6 MiB；不代表文件真实存在 }; build() { Column({ space: 16 }) { Text('GSAssetGate · GS-052').fontSize(22) Text(this.item.filename) Text(门禁：$this.resultText‘)Text(‘后续阶段：${this.nextStep}) Button('检查导入条件').onClick(() => { const gate: GateResult = inspectManifest(this.item); this.resultText = gate.reason; this.nextStep = gate.allowed ? 'WAIT_DEVICE' : 'FIX_INPUT'; console.info(GSAssetGate/GS-052 ${gate.reason} ${this.nextStep}); }) }.padding(24).width('100%') }}```这个页面示例有意不处理文件选择器和模型导入，因为两者依赖实际媒体权限、资源路径与渲染上下文。正式工程应把 item 改为受控业务状态，并只在开发调试中显示门禁原因码；对用户则展示可理解的提示。bytes数值来自演示输入，不能作为对实际.glb文件大小的测量证据。这套页面还有一条产品规则：门禁通过后也不要自动发起加载。模型导入可能引起明显的 CPU、GPU 与内存占用，用户需要知道接下来会消耗设备资源，并能取消还没有提交的请求。对于体积较大的资产，可以先提供名称、大小、来源和可用空间的概要，再把最终“尝试加载”留给明确的按钮行为。这样遇到不支持的机型时，页面仍能提供诊断信息，而不是静默卡住。## 四、调试顺序比“先看见模型”更重要建议按三层检查。先做纯函数夹具：空 ID、后缀不符、零字节、预算超限都要落到确定的原因码；再做 ArkUI 状态检查：重复点按钮不会产生多份日志，换资产以后旧回执不会覆盖新资产；最后才是支持设备上的GSPlugin.loadGSNode联调，记录应用版本、目标 SDK、系统版本、资产校验信息与是否完成资源释放。我不会把 3DGS 模型导入与“端侧重建算法已运行”混为一谈。模型加载是读取与显示已有资产；重建是由视频或空间采集数据生成资产，所需输入、资源和能力链不同。文章选择了加载入口前的工程控制点，不提供未经核实的重建耗时、重建质量或芯片兼容范围表。当PRECHECK_PASS与WAIT_DEVICE同时出现在演示图里，它恰好表达了这套方案的边界：业务输入可先受控，平台渲染仍需在支持的真实设备上验证。此后若增加模型缓存、切换场景、跨设备分享，应继续把资产身份、资源所有权和加载生命周期分开记录，而不是靠一个isLoading` 布尔值包办所有状态。官方核对资料： Spatial Recon Kit 简介、3DGS 端侧重建管线、Spatial Recon Kit API 变更。本文不替代 SDK 发布说明与设备支持清单；示例代码尚未通过目标 SDK 编译与真机渲染验证。