VoxelViewer 概览
VoxelViewer 是 Voxel Kit 的可视化组件。把它理解为一个放进 ArkUI 页面中的“体素 3D 画布”：宿主给它一份 JSON、VFP 字节或 DocumentPicker URI，它负责把内容变成可旋转、可平移、可缩放的模型预览。
模型显示区默认是直角，不会在组件内部裁剪 ArkGraphics Surface。需要卡片式圆角时，显式设置 VoxelViewerOptions.cornerRadius；它与加载提示卡片的 VoxelLoadOverlayStyle.borderRadius 独立。
它没有暴露 ArkGraphics 的 Scene、Camera、Mesh 或 Geometry。这是一项刻意的边界：模型切换、载入动画、描边、光照与资源释放都在组件内部协同，宿主通过稳定的 Controller 和 Options 表达需要的结果。
你将获得什么
| 能力 | 默认行为 | 你可以控制的部分 |
|---|---|---|
| 输入 | JSON、VFP 1.2/1.3、Picker URI | 三个 load*() 入口与显示文件名 |
| 交互 | 单指旋转、双指平移和缩放 | 灵敏度、缩放范围，以及分别锁定旋转、平移、缩放、编辑和框选 |
| 相机 | 自动适配模型的初始取景；有效 VFP SCNE 优先 | 通过 Controller 设置 X/Y/Z 旋转、XYZ 平移或恢复初始机位 |
| 视觉 | 工作室背景、PBR 光照、阴影、体素边缘、地面网格 | 背景、图片、渲染参数、网格开关 |
| 载入体验 | 逐层堆砌动画与内置遮罩 | 动画风格/时长，或四种 Loading 责任模式 |
| 状态 | 加载、场景准备、动画、错误 | Promise、查询方法、外置 Overlay 状态回调 |
不负责的事
- 不拉起系统 Picker、不做网络下载或鉴权；宿主完成这些后只需传入 URI/数据。
VoxelViewer本身不提供固定编辑工具栏；需要编辑时传入同一页面长期复用的VoxelEditorController，由宿主绘制按钮、调色板和保存入口。- 不接受宿主直接操控内部 ArkGraphics 相机、场景或材质；需要机位控制时使用版本化的 Controller 相机 API。
- 不将预览成功宣称为 VFP 权威体素数据已经验证。
如果你的需求是读取目录、显示文件信息或提取 VFP 已包含的 GLB，而不需要显示 3D 场景，请使用 Reader API 概览。
对于 VFP 1.3，coordinateSystem='Z_UP' 只说明上轴；Viewer 同时遵循 Orientation Profile v1：源空间 +Y 为模型正前方、+X 为右、右手系。于是 SCNE.camera.yaw=0 是从 +Y 正面观察 Pivot，正 yaw 向 +X 转动，正 pitch 向 +Z 抬升。旧文件没有 axisConvention 时仍使用这套固定默认值；显式不完整的轴约定不会被静默猜测。
最小结构
ArkUI 页面
├─ Options：预览配置，首次加载前设定资源和视觉
├─ Controller：一次页面生命周期内稳定复用
└─ VoxelViewer：只负责实际的可视区域
↑
loadText / loadBytes / loadUri
一个 Controller 对应一个 Viewer。页面状态变化可以重组 build()，但不要随之重新创建 Controller；页面永久退出时销毁它，然后下次进入重新创建一对新的 Options/Controller/Viewer。
推荐阅读顺序
- 接入与生命周期：先理解 Controller、手势和四种背景/Loading 策略。
- Preview API 参考：按字段查完整接口、默认值和生效时机。
- 渲染架构与性能：大模型、首帧描边、动画和性能取舍。
- 测试与排障：在真机上完成最终验证。
若你的目标只是尽快看到模型，直接从快速开始复制最小页面。完成后再回到本目录按需配置背景、遮罩与渲染参数。