API 参考概览

本参考按可直接从 voxel-kit 导入的公开对象拆分，而不是按内部渲染实现拆分。每一页都给出真实签名、参数、返回值、异常、生命周期和可复制的 ArkTS 示例。

从哪个入口开始

目标	首选 API	说明
页面内显示、导入、手势查看与相机命令	VoxelViewer + VoxelViewerController	UI 与命令控制分离，适合 ArkUI 页面。
调整背景、动画、手势边界	VoxelViewerOptions + VoxelGestureLockOptions	在创建 Controller 前配置；也可运行时选择性锁定输入。
调整光照、曝光、阴影、描边	VoxelRenderTuning	通过 Controller 应用到已存在的场景。
在预览后编辑体素	VoxelEditorController	按需恢复权威体素，支持选取、增删改、选区、变换、撤销/重做与保存。
自由 RGB、选区和 VFP 保存布局	编辑器类型与保存 API	颜色、坐标、对齐、状态和派生区段均有独立类型。
读取 VFP 目录或提取缩略图	VoxelKit.createVfpReader()	不创建 ArkGraphics 对象。
校验、导出 JSON / VOX	VfpPackageReader	用权威校验确认 VOXO，不要仅依赖缓存。
JSON 编译为 VFP	VoxelKit.createVfpCompiler()	异步调用随 HAR 分发的 Native 编译器。
导出可保存或分享的视频	VoxelKit.createGltiExporter()	将权威 VFP 导出为 GLTI MP4 字节。
从保留编辑源的视频包恢复 VFP	VoxelKit.createGltiReader()	校验 GLTI、GLB 扩展和 VFP 权威数据后返回原字节。

模块导入

import {
  VoxelKit,
  VoxelViewer,
  VoxelViewerController,
  VoxelEditorController,
  VoxelEditorOptions,
  VoxelCameraTransform,
  VoxelGestureLockOptions,
  VoxelViewerOptions,
  VoxelRenderTuning
} from 'voxel-kit';

如果应用同时需要视频交付或恢复编辑工程，再从相同包中导入 VoxelGltiExporter、VoxelGltiExportOptions 与 GltiPackageReader。这两项能力不依赖 VoxelViewer，也不会创建 3D 场景；请阅读 导出到相册与分享 了解用户任务流程， 再按需查阅 GLTI API 细节。

公开层与内部层

只有入口文件导出的类型属于兼容承诺。internal/ 下的 VoxelSceneResult、ArkGraphics Scene、Mesh、材质与缓存任务都可能随渲染器升级而改变，应用不得保存或操作它们。

VoxelViewerController.bindStateListener() 与 getSceneResult()目前用于组件内部协调，虽然可见于实现，但不是应用契约；请使用 isLoading()、getStatus()、getLastError()、VoxelLoadResult 和 VoxelViewerOptions.onLoadOverlayStateChanged 获取状态。

最小完整骨架

@Entry
@Component
struct VoxelPage {
  private controller: VoxelViewerController = new VoxelViewerController();

  build() {
    Column() {
      VoxelViewer({ controller: this.controller })
        .width('100%')
        .height('100%')
    }
  }
}

接下来按“显示模型”“编辑体素”“控制加载”“读取文件”四类任务进入对应页面。所有异步 API 都应在 try/catch 中调用；拒绝 Promise 后，读取 controller.getLastError() 或编辑器 getState().message 可获得面向用户的错误文本。