控件系统

目的和范围

控件系统提供定位在地图上的用户界面元素，以启用用户交互和显示信息。控件是屏幕上具有固定位置的可视小组件，可以涉及用户输入（按钮）或信息显示。该系统管理内置 UI 控件（如缩放按钮、归属显示、比例尺和概览地图）的创建、定位、渲染和生命周期。

有关与地图内容的用户交互（绘制、选择要素），请参阅要素编辑交互。有关定位在地理坐标处的覆盖物，请参阅覆盖物和定位。

控件系统架构

100%

基础控件类

Control 类作为 OpenLayers 中所有 UI 控件的基础。它扩展 BaseObject，并为 DOM 元素管理、地图集成和渲染生命周期提供公共功能。

核心属性和方法

属性/方法	目的
element	控件的 DOM 容器元素
map_	对关联 Map 实例的引用
target_	用于渲染的自定义目标元素
listenerKeys	用于清理的事件侦听器键数组
setMap(map)	将控件附加到地图或从地图分离
render(mapEvent)	在每个地图渲染周期调用

控件生命周期

100%

内置控件类型

信息显示控件

归属控件

显示带有可折叠功能的图层源归属。

关键功能：

• 通过 collapsible 选项控制的可折叠显示
• 从可见图层自动收集归属
• 通过 attributions 选项支持自定义归属
• 动态内容的 XSS 保护警告

100%

比例尺控件

显示当前缩放级别的地图比例尺或比例线。

配置选项：

• bar：渲染为比例尺而不是线
• steps：比例尺段数
• units：显示单位（公制、英制、海里、度、美制）
• dpi：输出设备 DPI，用于精确缩放

鼠标位置控件

以指定的投影和格式显示当前鼠标坐标。

关键功能：

• 通过 coordinateFormat 可配置的坐标格式
• 投影转换支持
• 当鼠标离开视口时的占位符文本
• 全局投影上的世界包裹

导航控件

缩放控件

提供具有可自定义标签和样式的放大/缩小按钮。

100%

缩放滑块控件

具有拖动交互的滑块样式缩放控件。

关键功能：

• 水平或垂直方向自动检测
• 用于连续缩放更改的拖动交互
• 点击缩放功能
• 支持可配置持续时间的动画

旋转控件

用于将地图旋转重置为北的按钮，带有可视旋转指示器。

功能：

• 当旋转为 0 时自动隐藏（可配置）
• 动画旋转重置
• 随地图旋转的可视罗盘指示器
• 自定义重置函数支持

高级控件

概览地图控件

显示当前视口范围的迷你概览地图。

复杂功能：

• 具有单独视图的独立 Map 实例
• 显示主地图范围的框覆盖物
• 交互式拖动以平移主地图
• 自动范围调整和居中
• 带有自定义标签的可折叠

100%

全屏控件

使用 Fullscreen API 启用全屏模式。

功能：

• 浏览器兼容性检测
• 自定义源元素支持
• 键盘访问选项
• 全屏状态更改的事件分派

与地图的控件集成

控件通过几种机制与 Map 集成：

DOM 容器集成

控件添加到 Map 管理的特定 DOM 容器：

100%

渲染周期集成

控件通过 render() 方法参与地图的渲染周期：

1. Map 触发 MapEventType.POSTRENDER
2. 调用控件的 render(mapEvent) 方法
3. 控件根据当前地图状态更新其 DOM
4. 每帧重复该过程

事件侦听器管理

控件使用 listenerKeys 数组跟踪事件侦听器以进行适当的清理：

100%

控件配置和默认值

控件系统提供 defaults() 函数，用于为大多数地图应用程序创建标准控件集。可以通过排除某些控件或添加其他控件来自定义此设置。

代码库中的示例使用模式：

• defaultControls() - 标准控件集
• defaultControls({attribution: false}) - 排除归属
• defaultControls().extend([customControl]) - 添加自定义控件