API 参考概览

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

从哪个入口开始

目标	首选 API	说明
页面内显示、导入、手势查看	VoxelViewer + VoxelViewerController	UI 与命令控制分离，适合 ArkUI 页面。
调整背景、动画、手势边界	VoxelViewerOptions	在创建 Controller 前配置；也可运行时更新。
调整光照、曝光、阴影、描边	VoxelRenderTuning	通过 Controller 应用到已存在的场景。
读取 VFP 目录或提取缩略图	VoxelKit.createVfpReader()	不创建 ArkGraphics 对象。
校验、导出 JSON / VOX	VfpPackageReader	用权威校验确认 VOXO，不要仅依赖缓存。
JSON 编译为 VFP	VoxelKit.createVfpCompiler()	异步调用随 HAR 分发的 Native 编译器。

模块导入

import {
  VoxelKit,
  VoxelViewer,
  VoxelViewerController,
  VoxelViewerOptions,
  VoxelRenderTuning
} from 'voxel-kit';

公开层与内部层

只有入口文件导出的类型属于兼容承诺。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() 可获得面向用户的错误文本。