跳到主要内容

介绍、范围与兼容性

如果你只是第一次接入，请先读更易懂的 欢迎与介绍。本页开始说明开发边界和兼容性。

这个组件在项目中的位置​

可以把 VoxelKit 理解为页面里的“3D 模型展示区域”。它不是一个独立 App，也不替你做作品列表、文件管理、网络下载或登录。

你的应用负责：显示“导入”按钮、让用户选择文件、保存作品信息、决定 Loading 怎么展示；VoxelKit 负责：读取模型、把小方块组成 3D 画面、处理旋转缩放和释放渲染资源。

这样做的好处是：你可以把 VoxelKit 放进作品详情、创作预览、文件浏览器或社区帖子中，而不必把整个产品业务带进渲染组件。

开发边界​

由宿主完成由 VoxelKit 完成
文件选择、网络、登录、业务缓存、作品信息、页面布局。JSON/VFP 识别、模型预览、光照、手势、载入动画和 3D 资源生命周期。
品牌背景、外置 Loading/错误页（需要时）。内置背景/Loading，或在 Builder 模式下控制其正确显示时机。
保存、分享已提取的 GLB。读取 VFP 中已有的 GLB 预览字节。

宿主不直接操作 ArkGraphics Scene、Mesh 或 Camera；这些对象由组件内部管理，避免模型切换、动画和描边创建相互干扰。

运行环境​

项目要求
HarmonyOS APIAPI 23 / 6.1.0 或兼容版本。
图形能力SystemCapability.ArkUi.Graphics3D。
语言ArkTS / ArkUI。
最终验证真机或支持 ArkGraphics 的模拟器。DevEco 设计预览不能验证 Component3D。
HAR 名称npm/OHPM 包名 voxel-kit；构建模块名 voxelKit。
当前 HAR 版本2.1.0。新增 THMB PNG 缩略图读取，不破坏既有 Preview 或 Reader 调用。

版本兼容性​

层级兼容范围注意事项
Preview JSON当前 PixForge 风格 JSON，grid_size=1..128。数据按 data[z][y][x]、Z-up 解释。
Preview VFP1.2、1.3。1.3 以只读预览缓存为优先路径。
Container Reader1.2、1.3。只检查容器/目录/区段 CRC，不验证权威 VOX0。
VFP 规范1.3。详细 ABI 与缓存语义见 VFP 规范。
Python 工具独立发布的 voxelkit。不是 HarmonyOS HAR 的运行时依赖。

语义化版本规则​

  • PATCH：渲染、稳定性、性能或文档修复；不变更公开类型/默认行为。
  • MINOR：增加可选字段、独立能力或非破坏性回调。
  • MAJOR：改变包名、导出 API、输入约定、默认行为或最低系统要求。

应用只应从包根 Index.ets 的公开导出导入。导入 internal/、依赖 getSceneResult() 返回值或访问未文档化属性会失去升级兼容性。

不适用场景​

  • 需要编辑、拾取、放置、撤销/重做或保存 VFP 的产品。
  • 要把任意 VFP 的 VOX0 直接转换为 JSON、VOX 或新 GLB 的产品。
  • 要自行驱动相机坐标、强行替换材质或绑定内部 ArkGraphics Node 的产品。
  • 需要服务端下载、鉴权、云端同步的产品。

这些能力应在独立编辑器、格式转换或业务 SDK 中实现，不能通过复制 HAR 内部类“临时开放”。