viewer.background — BackgroundManager

设计意图

viewer.background 是画布背景域,背景有四种形态:纯色(setColor)、上下双色垂直渐变(setGradient)、图片(setImage)与透明(setTransparent),外加整体不透明度旋钮(setOpacity)。未设置时引擎默认显示浅灰垂直渐变;初始背景也可在构造期经 ViewerOptions.background 给定(纯色或 "transparent")。

图片背景的来源类型很宽(BackgroundImageSource):URL 字符串 / URL / HTMLImageElement / ImageBitmap / Blob 都收;适配方式经 BackgroundFit 控制("cover" 裁切铺满 / "contain" 完整显示 / "stretch" 拉伸变形,默认 "cover")。要注意画布背景与页面 CSS 是双轨:canvas 内容由引擎绘制,宿主页面的 CSS 背景管不到它——深浅主题切换时要同步调本域,见主题定制的画布背景说明。

何时用它:对齐宿主应用的主题底色、产品展示的品牌背景图、把 viewer 透明嵌入页面让宿主背景透出来。

典型用法

深浅主题切换时同步画布背景(与 CSS token --fmb-bg 对齐):

const BG = {
  light: { r: 0.957, g: 0.965, b: 0.976 }, // #f4f6f9
  dark: { r: 0.039, g: 0.055, b: 0.078 }, // #0a0e14
};
themeToggle.onchange = () => viewer.background.setColor(BG[theme]);

品牌背景图(异步加载,失败抛 ViewerError):

try {
  await viewer.background.setImage("/brand/studio-backdrop.jpg", { fit: "cover", opacity: 0.85 });
} catch {
  viewer.background.setGradient({ r: 0.9, g: 0.92, b: 0.95 }, { r: 0.75, g: 0.78, b: 0.82 });
}

透明嵌入(viewer 浮在宿主页面背景之上):

viewer.background.setTransparent();

注意事项

• setImage 是异步方法(等图片解码完成),加载失败抛 ViewerError(NetworkFailed);跨域 URL 按 crossOrigin="anonymous" 拉取,源站需允许 CORS。
• clear() 当前等价于 setTransparent()——是「清掉背景设置变透明」,不是「恢复默认浅灰渐变」;要回默认观感需自己重设渐变。
• setOpacity(alpha) 作用于背景整体(0–1),不是单独针对图片;setImage 的 opts.opacity(默认 1)只是设置图片时的初值。
• 构造期 ViewerOptions.background 只支持纯色或 "transparent";渐变与图片背景要在创建后经本域设置。
• 与 CSS 双轨:页面主题色改了 CSS 变量不会影响 canvas,两边都要改,做法见主题定制。

完整签名与延伸

• BackgroundManager — 全部方法的精确签名。
• BackgroundImageSource / BackgroundFit / Color — 图片来源、适配方式与颜色类型。
• viewer-ui:主题定制 — CSS token 与画布背景的双轨同步做法。