跳到主要内容

VoxelViewer

VoxelViewer 是预览 UI 组件。它负责创建并承载 ArkGraphics Surface、绘制背景/加载层、处理单指旋转和双指平移/缩放；模型加载操作由 VoxelViewerController 发起。

组件参数​

VoxelViewer({
  controller: VoxelViewerController,
  backgroundBuilder?: (state: VoxelBackgroundState) => void,
  loadOverlayBuilder?: (state: VoxelLoadOverlayState) => void
})
参数类型必填说明
controllerVoxelViewerController是同一个页面内应稳定复用的控制器；不要在 build() 内反复创建。
backgroundBuilder(state: VoxelBackgroundState) => void否仅 backgroundMode = BUILDER 生效，替换完整背景层。
loadOverlayBuilder(state: VoxelLoadOverlayState) => void否仅 loadOverlayMode = BUILDER 生效，替换加载遮罩中的提示卡片。

基础使用​

@Entry
@Component
struct ModelPreviewPage {
  private previewController: VoxelViewerController = new VoxelViewerController();

  build() {
    Column() {
      VoxelViewer({ controller: this.previewController })
        .width('100%')
        .height(520)
        .borderRadius(20)
        .clip(true)
    }
    .padding(16)
  }
}

仅渲染组件不会自动加载模型。用户选中文件后调用 previewController.loadUri(uri)；从网络或数据库取得字节后调用 loadBytes(bytes)；内嵌 JSON 使用 loadText(text)。

组件生命周期​

  1. 在字段初始化阶段创建 Controller；此时只保存选项，不创建模型。
  2. VoxelViewer 首次挂载后绑定控制器，开始接收加载状态和渲染更新。
  3. 加载成功后组件将场景显示在 Surface 中；重复加载会替换旧场景。
  4. 页面即将离开且控制器不会复用时调用 dispose()，停止延迟描边与加载动画。
aboutToDisappear(): void {
  this.previewController.dispose();
}

手势契约​

手势默认行为可配置项
单指拖动围绕模型旋转orbitSensitivity
双指拖动平移视图panSensitivity
双指捏合缩放minZoomFactor、maxZoomFactor

宿主不应在同一 Surface 上再叠加会抢占单指/双指的手势容器；如必须有页面级滚动，请让预览区域获得明确高度并在交互测试机上验证竞争关系。Builder 无法取得 Scene、Camera 或 Mesh；它只负责视觉层，加载时机和场景生命周期仍由 Viewer/Controller 管理。

常见问题​

  • 空白区域通常表示尚未调用加载方法，不是组件故障。
  • 组件尺寸为 0 时 Surface 不会有可见输出；应明确设置 width 与 height。
  • VoxelViewer 不是文件选择器。Picker 由宿主实现，获得 URI 后传给 Controller。