自定义空间背景

当 Cesium canvas 需要与页面的图片、渐变或其他 HTML 内容合成时，关键不是替换天空盒，而是为 WebGL 上下文开启 alpha 通道，再把场景未绘制区域设为透明。

创建透明 Viewer

import { CesiumViewer } from '@nexa/gis-cesium'
import { Color } from 'cesium'

const nexaGis = new CesiumViewer('container', {
  contextOptions: {
    webgl: {
      alpha: true,
    },
  },
})

const { scene } = nexaGis.viewer
if (scene.skyBox) scene.skyBox.show = false
scene.backgroundColor = new Color(0, 0, 0, 0)

容器背景由普通 CSS 管理：

#container {
  background-image:
    radial-gradient(circle at 20% 20%, #fff 0 1px, transparent 1.5px),
    linear-gradient(180deg, #010713, #0b5790 82%, #a7e7ff);
  background-size: 190px 190px, 100% 100%;
}

alpha 属于 WebGL 创建期属性。Viewer 创建后，即使把 scene.backgroundColor 改成透明色，也无法为一个以 alpha: false 创建的 canvas 补开透明通道。

contextOptions 合并规则

CesiumViewer 默认设置 webgl.preserveDrawingBuffer: true，以维持 canvas 截图能力。调用方传入的值最后合并，因此可以显式关闭：

const nexaGis = new CesiumViewer('container', {
  contextOptions: {
    requestWebgl1: false,
    allowTextureFilterAnisotropic: true,
    webgl: {
      alpha: true,
      antialias: false,
      preserveDrawingBuffer: false,
    },
  },
})

关闭 preserveDrawingBuffer 可减少额外缓冲开销，但截图、书签缩略图等读取 canvas 的能力可能失败。传入的 contextOptions 及其 webgl 子对象不会被 SDK 修改。

为兼容旧版类型声明，扁平写法 { contextOptions: { alpha: true } } 仍受支持，但推荐统一使用 Cesium 原生的 { contextOptions: { webgl: { ... } } }。

生命周期与所有权

创建 CesiumViewer 的组件或服务拥有该 Viewer，并应在离开页面时调用 nexaGis.destroy()。销毁前需要移除自行注册的 DOM 事件、定时器和场景监听；不要直接操作 Cesium 私有 _cesiumWidget 或 _context 字段。

示例中心由 CodeRunner 统一登记并销毁 Viewer，案例只恢复自己接管的 skyBox.show、backgroundColor 和容器主题状态。CSS 背景随 Vue 组件卸载自动释放，不会额外占用 WebGL 上下文。

与天空盒的区别

• 自定义 HTML/CSS 背景位于 canvas 后方，需要 contextOptions.webgl.alpha: true。
• SkyBox 位于 Cesium 场景内部，不需要透明 canvas，且会参与场景渲染。
• 若只想更换星空六面贴图，应使用 SkyBoxEffect；若要把页面设计、视频或 DOM 内容透过 canvas 展示，则使用本方案。