UI 组件

OpenLayers 中的 UI 组件提供位于地图上或地图上的用户界面元素，用于启用用户交互和显示信息。该系统包含两个主要类别：Controls（控件）（固定位置的界面元素）和 Overlays（覆盖物）（定位在地理坐标处的 DOM 元素）。有关与地图内容（如绘制和编辑）的用户交互，请参阅要素编辑交互。

系统架构

UI 组件系统围绕两个主要抽象构建，它们处理不同的定位范式：

UI 组件类型层次结构

100%

UI 组件与地图系统的集成

100%

控件系统

控件是具有固定屏幕位置的 UI 元素，提供地图交互功能。基础 Control 类处理所有内置控件使用的 DOM 管理和地图集成模式。

控件基础实现

Control 类（src/ol/control/Control.js45-161）为所有 UI 控件提供基础：

• 元素管理：控件创建和管理自己的 DOM 元素
• 地图集成：自动附加到地图覆盖物容器
• 事件处理：内置事件侦听器清理和渲染集成
• 目标支持：在地图视口之外的可选渲染

控件类型	目的	关键方法
Attribution	显示数据源归属	setCollapsible()、setCollapsed()
FullScreen	切换全屏地图显示	handleFullScreen_()
MousePosition	显示光标坐标	setCoordinateFormat()、setProjection()
OverviewMap	带有当前视图指示器的迷你地图	getOverviewMap()、setRotateWithView()
Rotate	将地图旋转重置为北	resetNorth_()
ScaleLine	显示地图比例信息	setUnits()、setDpi()
Zoom	放大/缩小按钮	zoomByDelta_()
ZoomSlider	基于滑块的缩放控制	setThumbPosition_()
ZoomToExtent	将地图拟合到特定范围	handleZoomToExtent()

控件生命周期和 DOM 集成

100%

示例控件实现

归属控件模式

Attribution 控件演示了动态内容更新和可折叠 UI 模式：

// Attribution 控件的关键实现细节
collectSourceAttributions_(frameState) {
  const layers = this.getMap().getAllLayers();
  const visibleAttributions = new Set(
    layers.flatMap((layer) => layer.getAttributions(frameState))
  );
  // 处理归属并更新可折叠状态
}

比例尺控件模式

ScaleLine 控件显示动态测量计算和单位转换：

// 带单位转换的比例计算
updateElement_() {
  const pointResolution = getPointResolution(
    projection, viewState.resolution, center, pointResolutionUnits
  );
  // 在公制、英制、海里单位之间转换
  // 计算适当的比例尺宽度
}

覆盖物系统

覆盖物是定位在特定地理坐标处的 DOM 元素，它们随地图移动。与控件不同，覆盖物绑定到地图坐标而不是屏幕位置。

覆盖物定位系统

Overlay 类（src/ol/Overlay.js112-582）为 DOM 元素提供地理定位：

100%

覆盖物配置选项

选项	类型	目的
position	Coordinate	覆盖物的地理位置
positioning	Positioning	覆盖物相对于坐标的定位方式
offset	Array<number>	从计算位置的像素偏移
element	HTMLElement	要定位的 DOM 元素
stopEvent	boolean	是否停止事件传播
autoPan	PanIntoViewOptions	自动平移以保持覆盖物可见

自动平移功能

覆盖物可以自动平移地图以确保它们保持可见：

100%

集合管理

UI 组件通常使用 Collection 类在集合中管理，该类为控件和覆盖物等组件提供类似数组的可观察功能。

集合事件系统

100%

集成模式

默认控件设置

OpenLayers 通过 defaults 函数提供默认的控件集，通常包括：

• Zoom - 放大/缩小按钮
• Rotate - 旋转重置（当旋转不为 0 时）
• Attribution - 数据源归属

自定义控件开发

创建自定义控件遵循基础 Control 模式：

1. 扩展 Control 类：继承自 ol/control/Control
2. 创建 DOM 元素：构建控件的 HTML 结构
3. 实现事件处理程序：处理用户交互
4. 覆盖 render()：根据地图更改更新控件状态
5. 管理生命周期：在 setMap() 中清理资源

覆盖物用例

常见的覆盖物应用程序包括：

• 弹出窗口：特定坐标处的信息显示
• 标记：基于 HTML 的点表示
• 工具提示：动态信息显示
• 自定义小部件：与地理位置绑定的交互元素