Voxel Kit for HarmonyOS
Voxel Kit for HarmonyOS 是面向 ArkUI 的体素 SDK。它把“拿到一份 JSON 或 VFP 文件，安全地显示成可交互的 3D 体素模型”拆成两个可以独立使用的能力：
- VoxelViewer：负责可见的模型预览，包括异步导入、ArkGraphics 场景、光照、载入动画、背景、单指旋转和双指平移/缩放。
- Reader API：负责不依赖 3D 引擎的 VFP 容器读取、目录检查、CRC 校验以及区段、内嵌 GLB 预览和 PNG 缩略图提取。
它适合在作品详情、资产浏览器、导入页和社区内容中展示 .json 或 .vfp 体素模型。宿主应用负责 Picker、网络、业务状态与页面布局；组件负责预览与资源生命周期。
获取 Kit
Voxel Kit for HarmonyOS 推荐通过字符科技 OHPM 仓安装：先执行 ohpm config set registry http://ohpm.charactech.cn/repos/ohpm/，再执行 ohpm install voxel-kit。可在 OHPM 获取 voxel-kit 查看包信息；完整安装步骤见安装与第一个预览。
先判断你需要哪一部分
| 你的目标 | 需要的能力 | 从哪里开始 |
|---|---|---|
| 页面上展示模型，让用户旋转、缩放、平移 | VoxelViewer | 快速开始 |
| 自己制作背景、加载状态或使用统一产品 Loading | VoxelViewer 的 Options/Builder | VoxelViewer 概览 |
| 选择 VFP 后先展示文件版本、区段与 META | VfpPackageReader | Reader API 概览 |
| 取出 VFP 中本来就带着的 GLB 预览 | extractPreviewGlb() | VFP Reader API |
| 取出 VFP 用于资产卡片的 PNG 缩略图 | extractThumbnail() | VFP Reader API |
| 编辑、保存、把 VOX0 转成新 GLB | 不属于当前 HAR | 范围与兼容性 |
五分钟内完成的事
- 在工程根目录执行
ohpm config set registry http://ohpm.charactech.cn/repos/ohpm/与ohpm install voxel-kit。 - 在页面字段中创建一个长期存在的
VoxelViewerController，不要在build()中创建。 - 首次加载前设置
unitGridTexture = $rawfile('voxel/voxel_grid.png')，让单位体素描边首帧可见。 - 在
build()中放入VoxelViewer({ controller })。 - 通过
loadText()、loadBytes()或loadUri()串行导入模型，并在页面永久离开时dispose()。
完整代码见 安装与第一个预览。
选择正确能力
| 你要做的事 | 推荐入口 |
|---|---|
| 首次接入并显示模型 | 安装与第一个预览 |
| 管理加载、背景、手势和页面释放 | 接入与生命周期 |
| 查询公开 ArkTS API | Preview API |
| 在 HarmonyOS 中读取 VFP、校验容器或提取内嵌预览 | VFP Reader API |
| 判断“可预览”是否等于“可信资产” | VFP 可信边界 |
| 构建、真机验证、准备 OHPM 发布 | 开发与发布概览 |
预览不等于编辑或权威验证
该 HAR 提供只读 VFP 文件读取与预览能力，但不提供体素编辑或 VFP 写回。预览路径的成功不自动等价于权威验证；涉及资产发布、编辑或可信导出时，仍应执行对应的完整验证流程。