跳到主要内容

VoxelViewerOptions

创建后直接为字段赋值，再传入 VoxelViewerController。这是一个可变配置对象；已经加载场景时建议修改后调用 controller.setOptions(options)，不要只修改字段而不通知 Controller。

动画与模型显示​

字段类型默认值作用
animationModeVoxelLoadAnimationModeSTACK导入后的揭示方式。
playLoadAnimationbooleantrue是否播放揭示动画。
loadAnimationDurationMsnumber1500动画时长，毫秒。
cornerRadiusnumber0Viewer 内容区域圆角，单位 vp。默认直角且不启用组件内部裁剪；正数时模型、背景和 HAR 内置遮罩以相同半径裁剪。
showGroundGridbooleantrue是否显示地面网格。
unitGridTexture`Resourceundefined`undefined

animationMode 可取 STACK、SOFT、RADIAL、WAVE、SPIRAL、CONVERGE。动画仅影响可视揭示，不改变 VOXO 体素数据。

模型圆角与加载卡片圆角是两件事

cornerRadius 管理的是整个 Viewer 内容区域：ArkGraphics 模型、ArkUI 背景与 HAR 内置遮罩的共同边界。它默认是 0，因此外层页面不需要再通过 .borderRadius(0).clip(false) 覆盖组件内部裁剪。

loadOverlayStyle.borderRadius 只管理加载提示卡片本身。即使卡片有圆角，也不会使模型显示区域变成圆角；loadOverlayMode = EXTERNAL 时 HAR 不绘制加载遮罩。

unitGridTexture：PBR 单位描边资源​

当前静态 HAR 的可靠接入方式是：下载 voxel_grid.png（PBR 单位网格纹理），将其命名为 voxel_grid.png 后放进宿主 HAP 的 resources/rawfile/voxel/，并在首个 load*() 前赋值：

options.unitGridTexture = $rawfile('voxel/voxel_grid.png');

该纹理写入 PBR 材质的 AO 平铺通道：不改写原始体素颜色，近处保持锐利，远处降低闪烁，并随主体光照变化。你可以传入同规格的自定义 Resource 覆盖视觉；若资源无法创建，运行时会记录警告并走旧式独立描边 Geometry 回退。该运行时降级不是 VFP 的 BORD 区段。

静态 HAR 不能可靠地让 ArkGraphics 读取自身 $rawfile()，也不能用 Data URI 或运行时缓存 file:// 作为稳定替代。不要把 unitGridTexture 设为文件路径、URI 或字符串；公开类型只接受 ArkUI Resource。真正不需要宿主资源的方案需要迁移到具备独立资源命名空间的 HSP/应用模块。

背景​

字段类型默认值作用
darkBackgroundbooleanfalse使用暗色三段背景。
backgroundModeVoxelBackgroundModeBUILTIN_CUSTOM背景责任方。
lightBackgroundTopColor/MiddleColor/BottomColorstring三段浅色浅色渐变。
darkBackgroundTopColor/MiddleColor/BottomColorstring三段深色深色渐变。
backgroundImage`Resourceundefined`undefined
backgroundImageFitImageFitImageFit.Cover图片适配方式。
backgroundImageOpacitynumber1图片不透明度。
backgroundImageOverlayColorstring#00000000图片上方色罩。

BUILTIN 使用 HAR 固定工作室背景；BUILTIN_CUSTOM 使用以上颜色；BUILDER 由宿主 Builder 替换整层；EXTERNAL 不绘制背景，由外部页面提供。

手势与导入上限​

字段类型默认值说明
orbitSensitivitynumber1单指旋转灵敏度。
panSensitivitynumber1双指平移灵敏度。
minZoomFactornumber0.08可缩放的最近边界。
maxZoomFactornumber5可缩放的最远边界。
gestureLocksVoxelGestureLockOptions全部为 false六类用户输入的初始锁定策略：单指/桥接双指旋转、单独双指旋转、平移、缩放、点击编辑、框选。运行时更推荐 controller.setGestureLocks()。
autoRotatebooleanfalse是否在场景就绪后自动绕体素 Z 轴旋转。
autoRotateDurationMsnumber5000自动旋转一整圈的时长，运行时限制为 300..60000 毫秒。
maxJsonBytesnumber15 * 1024 * 1024JSON 导入最大 UTF-8 字节数。

加载层​

字段类型默认值说明
loadOverlayModeVoxelLoadOverlayModeBUILTIN内置、定制、Builder 或外部加载层。
loadOverlayStyleVoxelLoadOverlayStyle新建默认样式文案、颜色、圆角、指示器。
onLoadOverlayStateChanged(state) => void空函数读取阶段状态，常用于 EXTERNAL。

完整配置示例​

const options = new VoxelViewerOptions();
options.animationMode = VoxelLoadAnimationMode.RADIAL;
options.loadAnimationDurationMs = 900;
options.cornerRadius = 0; // 默认：模型显示区域直角且不裁剪。
options.showGroundGrid = false;
options.backgroundMode = VoxelBackgroundMode.BUILTIN_CUSTOM;
options.lightBackgroundTopColor = '#F5F8FF';
options.lightBackgroundBottomColor = '#D7E1F0';
options.orbitSensitivity = 0.85;
options.panSensitivity = 0.9;
options.minZoomFactor = 0.04;
options.autoRotate = true;
options.autoRotateDurationMs = 5000;
options.gestureLocks.rotation = true;
options.maxJsonBytes = 15 * 1024 * 1024;
options.onLoadOverlayStateChanged = (state: VoxelLoadOverlayState): void => {
  console.info(state.phase + ': ' + state.message);
};
const controller = new VoxelViewerController(options);

颜色使用 ArkUI 可接受的字符串。对 backgroundImageOpacity、灵敏度、缩放边界等数值，请在产品侧施加合理范围，避免传入负数或最小值大于最大值。