VoxelViewer 概览

VoxelViewer 是 Voxel Kit 的可视化组件。把它理解为一个放进 ArkUI 页面中的“体素 3D 画布”：宿主给它一份 JSON、VFP 字节或 DocumentPicker URI，它负责把内容变成可旋转、可平移、可缩放的模型预览。

它没有暴露 ArkGraphics 的 Scene、Camera、Mesh 或 Geometry。这是一项刻意的边界：模型切换、载入动画、描边、光照与资源释放都在组件内部协同，宿主通过稳定的 Controller 和 Options 表达需要的结果。

你将获得什么

能力	默认行为	你可以控制的部分
输入	JSON、VFP 1.2/1.3、Picker URI	三个 load*() 入口与显示文件名
交互	单指旋转、双指平移和缩放	旋转/平移灵敏度、缩放范围
视觉	工作室背景、PBR 光照、阴影、体素边缘、地面网格	背景、图片、渲染参数、网格开关
载入体验	逐层堆砌动画与内置遮罩	动画风格/时长，或四种 Loading 责任模式
状态	加载、场景准备、动画、错误	Promise、查询方法、外置 Overlay 状态回调

不负责的事

• 不拉起系统 Picker、不做网络下载或鉴权；宿主完成这些后只需传入 URI/数据。
• 不提供选中、放置、删除、撤销、重做或 VFP 写回。
• 不接受宿主直接操控内部相机、场景或材质。
• 不将预览成功宣称为 VFP 权威体素数据已经验证。

如果你的需求是读取目录、显示文件信息或提取 VFP 已包含的 GLB，而不需要显示 3D 场景，请使用 Reader API 概览。

最小结构

ArkUI 页面
├─ Options：预览配置，首次加载前设定资源和视觉
├─ Controller：一次页面生命周期内稳定复用
└─ VoxelViewer：只负责实际的可视区域
       ↑
  loadText / loadBytes / loadUri

一个 Controller 对应一个 Viewer。页面状态变化可以重组 build()，但不要随之重新创建 Controller；页面永久退出时销毁它，然后下次进入重新创建一对新的 Options/Controller/Viewer。

推荐阅读顺序

1. 接入与生命周期：先理解 Controller、手势和四种背景/Loading 策略。
2. Preview API 参考：按字段查完整接口、默认值和生效时机。
3. 渲染架构与性能：大模型、首帧描边、动画和性能取舍。
4. 测试与排障：在真机上完成最终验证。

第一次接入

若你的目标只是尽快看到模型，直接从快速开始复制最小页面。完成后再回到本目录按需配置背景、遮罩与渲染参数。