欢迎使用 VoxelKit

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

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

它能帮你做什么

• 展示 .json 或 .vfp 格式的体素模型。
• 支持用户从系统文件选择器导入模型。
• 提供拖动旋转、双指缩放和双指平移。
• 自带背景、光照、阴影、模型载入动画和地面参考网格。
• 可以替换背景、加载提示和视觉参数，使它融入你的产品风格。
• 可以读取 VFP 文件的基本信息，或提取文件里已经附带的 GLB 预览。

一个典型场景

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

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

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

它暂时不做什么

VoxelKit 当前是预览组件，不是完整编辑器。

• 不支持点击某个方块后修改颜色、添加或删除方块。
• 不保存编辑结果，也不写回 VFP 文件。
• 不会把任意 VFP 重新转换成一个新的 GLB。
• 不处理登录、网络下载、云盘或作品库业务。

如果你只需要“把模型好看、稳定地展示出来”，可以直接使用它。需要编辑能力时，应接入独立编辑模块，而不是修改预览组件内部代码。

适合谁阅读

角色	推荐阅读顺序
产品或设计同学	本页 → 快速开始 → 接入与生命周期 的背景和加载提示部分。
HarmonyOS 页面开发者	本页 → 快速开始 → Preview API。
处理 VFP 文件的开发者	本页 → VFP Reader API → VFP 可信边界。
维护渲染/发布的工程师	介绍与兼容性 → 渲染架构与性能 → 构建验证与发布。

下一步

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