OverviewMap OpenLayers 鹰眼图

viewerOverviewMapMixin 把 Cesium 当前相机可见范围投影到调用方提供的 OpenLayers Map，以红色半透明矩形显示主视图所在区域。默认是 Cesium → OpenLayers 的单向同步；mixin 不会接管 OpenLayers 的交互，也不会反向修改 Cesium 相机。

需要 2D → 3D 反向联动（拖动 OpenLayers 地图驱动 Cesium 相机）时，使用 reverse: true 增强，见「二三维联动」指南。

安装

OpenLayers 是 @nexa/gis-cesium 的 peer dependency，应用需自行安装并创建 Map：

bash

pnpm add ol

import Map from 'ol/Map.js'
import View from 'ol/View.js'
import Feature from 'ol/Feature.js'
import Polygon from 'ol/geom/Polygon.js'
import VectorSource from 'ol/source/Vector.js'
import VectorLayer from 'ol/layer/Vector.js'
import { Fill, Stroke, Style } from 'ol/style.js'
import 'ol/ol.css'
import { viewerOverviewMapMixin } from '@nexa/gis-cesium'

const map = new Map({
  target: 'overview',
  view: new View({ projection: 'EPSG:4326', center: [105, 34], zoom: 3 }),
})

nexaGis.extend(viewerOverviewMapMixin, {
  map,
  ol: {
    Feature,
    Polygon,
    VectorSource,
    VectorLayer,
    Fill,
    Stroke,
    Style,
  },
})

ESM 项目应显式传入 ol 构造器适配器。为兼容历史 UMD 页面，省略 ol 时仍会尝试读取 window.ol；若两者都不存在，插件会安全降级并给出警告。

配置

interface ViewerOverviewMapOptions {
  map: OverviewMapLike
  ol?: OverviewMapOlAdapter
  padding?: [number, number, number, number]
  initialExtent?: [number, number, number, number]
}

参数	默认值	说明
`map`	必填	调用方创建并拥有的 OpenLayers Map
`ol`	`window.ol`	ESM OpenLayers 最小构造器适配器
`padding`	`[24, 24, 24, 24]`	`View.fit` 的上、右、下、左留白
`initialExtent`	`[73, 3, 135, 54]`	相机视域尚不可计算时的初始矩形

运行时 API

安装后通过 viewer.overviewMap 控制：

viewer.overviewMap.deactivate() // 暂停自动联动
viewer.overviewMap.sync()       // 手动同步一次，返回是否成功
viewer.overviewMap.activate()   // 恢复 camera.changed 监听，并立即同步

console.log(viewer.overviewMap.isActive)
console.log(viewer.overviewMap.isDestroyed)

activate、deactivate、destroy 都是幂等操作。自动同步监听 Cesium 公共 camera.changed 事件，避免源案例在每个 postRender 帧中重复创建 Polygon 和调用 fit。跨国际日期变更线时，插件会把 east 展开到大于 west 的连续范围，避免 OpenLayers 收到倒序 extent。

所有权与清理

mixin 只拥有自己创建的视域 VectorLayer、VectorSource 和 Cesium 相机监听；
destroy() 只移除上述资源，不清空 Map 的其他图层，也不调用 map.dispose()；
OpenLayers Map、底图、容器始终由调用方拥有，页面卸载时应由调用方释放；
通过 CesiumViewer.extend() 安装时，CesiumViewer.destroy() 会自动执行 mixin 的卸载钩子。

nexaGis.destroy()       // 先卸载 mixin 并销毁 Cesium Viewer
map.setTarget(undefined)
map.dispose()          // 调用方释放自己创建的 OL Map

迁移说明

源案例同时请求天地图、高德在线瓦片和第三方 3D Tiles；这些都不是鹰眼同步能力的必要组成，且存在令牌、HTTP 混合内容和服务可用性风险，因此没有迁移。示例使用 Canvas 生成的离线世界概览图，不复制来源不明的图片，也不依赖任何外部服务。

OverviewMap OpenLayers 鹰眼图 ​

安装 ​

配置 ​

运行时 API ​

所有权与清理 ​

迁移说明 ​

OverviewMap OpenLayers 鹰眼图

安装

配置

运行时 API

所有权与清理

迁移说明