VoxelViewerOptions

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

动画与模型显示

字段	类型	默认值	作用
animationMode	VoxelLoadAnimationMode	STACK	导入后的揭示方式。
playLoadAnimation	boolean	true	是否播放揭示动画。
loadAnimationDurationMs	number	1500	动画时长，毫秒。
showGroundGrid	boolean	true	是否显示地面网格。
unitGridTexture	`Resource	undefined`	undefined

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

背景

字段	类型	默认值	作用
darkBackground	boolean	false	使用暗色三段背景。
backgroundMode	VoxelBackgroundMode	BUILTIN_CUSTOM	背景责任方。
lightBackgroundTopColor/MiddleColor/BottomColor	string	三段浅色	浅色渐变。
darkBackgroundTopColor/MiddleColor/BottomColor	string	三段深色	深色渐变。
backgroundImage	`Resource	undefined`	undefined
backgroundImageFit	ImageFit	ImageFit.Cover	图片适配方式。
backgroundImageOpacity	number	1	图片不透明度。
backgroundImageOverlayColor	string	#00000000	图片上方色罩。

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

手势与导入上限

字段	类型	默认值	说明
orbitSensitivity	number	1	单指旋转灵敏度。
panSensitivity	number	1	双指平移灵敏度。
minZoomFactor	number	0.08	可缩放的最近边界。
maxZoomFactor	number	5	可缩放的最远边界。
autoRotate	boolean	false	预留字段；当前版本不启动自动旋转。
maxJsonBytes	number	15 * 1024 * 1024	JSON 导入最大 UTF-8 字节数。

加载层

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

完整配置示例

const options = new VoxelViewerOptions();
options.animationMode = VoxelLoadAnimationMode.RADIAL;
options.loadAnimationDurationMs = 900;
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.maxJsonBytes = 15 * 1024 * 1024;
options.onLoadOverlayStateChanged = (state: VoxelLoadOverlayState): void => {
  console.info(state.phase + ': ' + state.message);
};
const controller = new VoxelViewerController(options);

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