VoxelViewerController

VoxelViewerController 是 VoxelViewer 的命令入口。一个 Controller 对应一个可替换的预览场景；可以连续导入多个文件，但不应跨多个同时可见的 Viewer 共享。

构造函数

new VoxelViewerController(options?: VoxelViewerOptions)

参数	类型	默认值	说明
`options`	`VoxelViewerOptions	undefined`	新建默认配置

导入方法

`loadText()`

async loadText(text: string, sourceName: string = 'model.json'): Promise<VoxelLoadResult>

参数	说明
`text`	PixForge 体素 JSON 文本。UTF-8 编码后的字节数不得超过 `options.maxJsonBytes`。
`sourceName`	结果和状态文字中展示的名称，不参与解析。

`loadBytes()`

async loadBytes(bytes: ArrayBuffer, sourceName: string = 'model'): Promise<VoxelLoadResult>

自动识别 JSON、VFP 1.2、VFP 1.3。JSON 走 maxJsonBytes 限制；URI 以外的 VFP 由调用方负责控制内存来源。

`loadUri()`

async loadUri(uri: string, sourceName: string = ''): Promise<VoxelLoadResult>

参数	说明
`uri`	由系统文档选择器返回、且当前应用有读取权限的 URI。
`sourceName`	为空时从 URI 最后一段推导文件名。

Reader 最多读取 64 MiB。大于此限制、空文件、权限失效、短读、非法 JSON/VFP 均会拒绝 Promise。

一次完整导入

async function showFile(controller: VoxelViewerController, uri: string): Promise<void> {
  try {
    const result = await controller.loadUri(uri);
    console.info('loaded ' + result.sourceFormat + ': ' + result.voxelCount);
  } catch (error) {
    console.error(controller.getLastError());
  }
}

状态与结果

方法	返回值	说明
`isLoading()`	`boolean`	导入或准备场景期间为 `true`。
`getStatus()`	`string`	可直接展示的当前状态。
`getLastError()`	`string`	最近一次导入错误；下一次开始加载时清空。
`getSourceName()`	`string`	最近一次成功导入的名称。
`getOptions()`	`VoxelViewerOptions`	当前选项对象。
`getRenderTuning()`	`VoxelRenderTuning`	当前渲染调参对象。

VoxelLoadResult 包含 sourceName、sourceFormat、gridSize、voxelCount、surfaceCount、vfpCacheHit。其中 vfpCacheHit=true 仅说明预览缓存命中，不能证明 VOXO 权威数据已校验。

运行时设置

controller.setGroundGridVisible(false);
controller.setOptions(options);
controller.setRenderTuning(tuning);

setOptions() 会立即同步地面网格和加载动画时长；背景/加载层将在组件下一次状态更新时采用新配置。setRenderTuning() 会立即重新应用光照、阴影与描边设置。详见 VoxelViewerOptions 和 VoxelRenderTuning。

`dispose()`

dispose(): void

取消已排队的延迟描边、完成当前加载动画、释放当前场景引用，并把状态置为“预览器已释放”。释放后若要再次显示模型，仍可调用 loadText、loadBytes 或 loadUri 重建场景。

不要依赖 bindStateListener() 或 getSceneResult()：它们服务于 HAR 内部组件协作，不属于稳定公开 API。

构造函数​

导入方法​

loadText()​

loadBytes()​

loadUri()​

一次完整导入​

状态与结果​

运行时设置​

dispose()​