欢迎使用 VoxelKit

VoxelKit 是一个让 HarmonyOS 应用能够直接展示体素模型的小型组件包。

如果你的产品里有像素风建筑、角色、玩具、地图、用户创作作品，或者任何由许多小方块组成的 3D 模型，VoxelKit 可以把它们放进一个可旋转、可缩放、可平移的 3D 预览区域。你不需要自己搭建 3D 场景、处理模型光照，也不需要自己解析 VFP 文件。

它能帮你做什么

• 展示 .json 或 .vfp 格式的体素模型。
• 支持用户从系统文件选择器导入模型。
• 提供拖动旋转、双指缩放和双指平移。
• 自带背景、光照、阴影、模型载入动画和地面参考网格。
• 可以替换背景、加载提示和视觉参数，使它融入你的产品风格。
• 可以读取 VFP 文件的基本信息，或提取文件里已经附带的 GLB 预览。
• 可按需开启体素编辑：点击选取、自由颜色放置/替换、删除、多选/框选、选区变换、撤销/重做与 JSON/VFP 保存。
• 可从 JSON 或当前编辑结果离屏导出一圈旋转的透明背景 GIF，用于作品分享；不会录入页面 UI 或用户当前手势。

一个典型场景

例如，你正在做一个“我的作品”页面：

1. 用户点“导入模型”。
2. 你的页面拉起系统文件选择器。
3. 用户选择一份 JSON 或 VFP。
4. 你把 Picker 返回的 URI 交给 VoxelKit。
5. VoxelKit 显示模型，用户可以旋转查看细节。

你的页面只需要负责按钮、文件选择、业务状态和页面样式；模型的解析、渲染与手势由 VoxelKit 处理。

它暂时不做什么

VoxelKit 已包含按需开启的体素编辑器，但它不是完整的业务创作工作台。

• 编辑器不提供固定工具栏、调色板、图层树、账号、云同步或作品库；这些由宿主页面实现。
• 编辑目标必须是 JSON 或 VFP 的权威体素数据，不能直接编辑任意 GLB 的顶点/贴图。
• 不会把任意 VFP 转换为通用 GLB；只有在保存 VFP 时按需生成派生 PRVW 预览。
• 不处理登录、网络下载、云盘或业务文件权限管理。

只需要“把模型好看、稳定地展示出来”时，可只接入 Viewer；需要编辑时，在同一 Viewer 上增加 VoxelEditorController，普通预览首帧不会因此预读编辑数据。

适合谁阅读

角色	推荐阅读顺序
产品或设计同学	本页 → 快速开始 → 接入与生命周期 的背景和加载提示部分。
HarmonyOS 页面开发者	本页 → 快速开始 → Preview API。
要加入编辑能力的开发者	本页 → 编辑器概览与接入 → 选取、批量编辑与变换。
要生成分享动图的开发者	本页 → VoxelTurntableExporter → 编辑器保存与性能。
处理 VFP 文件的开发者	本页 → VFP Reader API → VFP 可信边界。
维护渲染/发布的工程师	介绍与兼容性 → 渲染架构与性能 → 构建验证与发布。

下一步

第一次接入请直接继续阅读 快速开始。它会带你完成安装、创建预览区域、加载 JSON/VFP 和打开系统文件选择器。