加载状态与样式

加载层独立于模型导入。无论采用内置卡片、定制卡片或外部 UI，状态都来自同一份 VoxelLoadOverlayState。

模式：VoxelLoadOverlayMode

枚举值	含义	宿主责任
BUILTIN	使用标准遮罩与状态卡。	无。
BUILTIN_CUSTOM	使用 HAR 卡片，但采用 VoxelLoadOverlayStyle。	配置样式。
BUILDER	HAR 管可见性与遮罩，宿主替换卡片内容。	提供 Builder。
EXTERNAL	HAR 完全不绘制加载 UI。	监听回调并绘制全部 UI。

阶段：VoxelLoadOverlayPhase

阶段	visible	典型含义
IDLE	通常否	等待导入。
IMPORTING	是	读取或解析输入。
PREPARING	是	准备预览资源。
ANIMATING	是	正在播放加载揭示。
ERROR	是	导入失败，errorMessage 有值。
HIDDEN	否	成功后隐藏。

VoxelLoadOverlayState 包含 phase、visible、message、errorMessage。不要通过比较中文 message 判断阶段；应比较 phase。

VoxelLoadOverlayStyle 全字段

字段	默认值	用途
maskColor	#00000000	整层遮罩颜色。
cardColor	#F8FBFFDD	状态卡背景。
titleColor	#425572	普通状态文字。
errorColor	#C2413B	错误文字。
loadingIndicatorColor	#4A7DF3	加载指示器颜色。
fontSize / errorFontSize	14 / 12	文本尺寸。
borderRadius	16	卡片圆角。
horizontalPadding / verticalPadding	18 / 16	内边距。
animationTopMargin	14	指示器与文字间距。
showLoadingIndicator	true	是否显示指示器。
useControllerStatus	true	是否取 Controller 当前状态文案。
idleText	导入提示	空闲文案。
loadingText	准备渲染资源	导入文案。
preparingText	创建预览	准备文案。
animationText	构建模型	动画文案。
errorPrefix	导入失败：	错误前缀。

外部 UI 示例

@State private overlayText: string = '';
@State private overlayVisible: boolean = false;

private makeOptions(): VoxelViewerOptions {
  const options = new VoxelViewerOptions();
  options.loadOverlayMode = VoxelLoadOverlayMode.EXTERNAL;
  options.onLoadOverlayStateChanged = (state: VoxelLoadOverlayState): void => {
    this.overlayVisible = state.visible;
    this.overlayText = state.errorMessage.length > 0 ? state.errorMessage : state.message;
  };
  return options;
}

回调可能在一次导入中多次触发，因此只做轻量状态赋值；不要在回调中再次调用 loadUri() 或同步读取大文件。