Controls

本文档解释 Mapbox GL JS 中的 control 系统。Controls 是 UI 组件,提供交互元素用于操作地图、显示信息或向 Mapbox GL JS 地图界面添加功能。有关 markers 和 popups 的信息,请参阅 Markers and Popups。

Control 架构

Mapbox GL JS 中的 controls 遵循插件架构,其中每个 control 实现一个公共接口。Controls 通过 map.addControl() 方法添加到地图,并且可以定位在地图周围的不同位置。

当 control 被添加到地图时:

1. 地图调用 control 的 onAdd() 方法,将自身作为参数传递
2. Control 创建并返回一个 HTML 元素
3. 地图将此元素添加到指定位置的 DOM 中
4. 当 control 被移除时,地图调用 control 的 onRemove() 方法

IControl 接口

100%

Control 定位

Controls 可以定位在地图周围的八个不同位置。基于 CSS 的定位系统在地图画布周围创建结构化布局。

100%

位置在将 control 添加到地图时指定为字符串:

map.addControl(new NavigationControl(), 'top-left');

有效的位置包括:

• 'top-left'
• 'top-right'（默认）
• 'bottom-left'
• 'bottom-right'
• 'top'
• 'right'
• 'bottom'
• 'left'

内置 Controls

NavigationControl

NavigationControl 提供用于放大、缩小和将地图的 bearing 重置为北方的按钮。

100%

GeolocateControl

GeolocateControl 使用浏览器的 geolocation API 在地图上定位用户。它可以配置为在用户移动时跟踪用户的位置。

100%

GeolocateControl 可以使用以下选项配置:

• positionOptions: Geolocation API 的选项
• trackUserLocation: 是否跟踪用户位置
• showUserLocation: 是否在地图上显示用户位置
• showUserHeading: 是否显示用户 heading（方向）

ScaleControl

ScaleControl 显示一个比例条,显示当前地图视图中的距离,在公制和英制系统之间自动切换单位。

100%

ScaleControl 可以使用以下选项配置:

• maxWidth: 比例条的最大宽度
• unit: 单位系统（公制、英制或海里）

FullscreenControl

FullscreenControl 提供一个按钮在正常模式和全屏模式之间切换地图。

100%

AttributionControl

AttributionControl 显示地图数据的归属信息,这通常是数据提供者要求的。

100%

自定义 Controls

可以通过实现 IControl 接口来创建自定义 controls。自定义 control 必须至少实现两个方法:

1. onAdd(map): 在 control 被添加到地图时调用,返回一个 HTML 元素
2. onRemove(map): 在 control 从地图中移除时调用

创建自定义 controls 时,你应该使用现有的 CSS 类来保持一致的视觉样式:

• mapboxgl-ctrl: 所有 controls 的基类
• mapboxgl-ctrl-group: 分组 controls 的容器（如 NavigationControl）

Control 样式

Controls 使用 mapbox-gl.css 文件中定义的 CSS 类进行样式设置。样式系统包括 control 容器、按钮、图标和各种状态的类。

100%

CSS 为不同状态提供样式:

• 正常状态: 默认样式
• 悬停状态: 当用户悬停在 control 上时增强样式
• 禁用状态: 视觉上指示 control 不可用
• 活动状态: 指示 control 处于活动状态

Control 可访问性

Controls 包括几个可访问性功能:

• 带有焦点样式的键盘导航支持
• Windows 高对比度模式的高对比度支持
• 屏幕阅读器的适当 ARIA 属性
• 图标的文本替代

100%

国际化

可以通过向 Map 构造函数提供 locale 对象来本地化 controls。这允许翻译 control 文本和工具提示。

默认的 locale 字符串在 default_locale.ts 文件中定义:

100%

Locale 对象将像 'NavigationControl.ZoomIn' 这样的键映射到翻译后的字符串。

Control 选项表

Control	关键选项	描述
NavigationControl	showCompass	显示/隐藏指南针按钮
	showZoom	显示/隐藏缩放按钮
	visualizePitch	是否在指南针旋转中显示 pitch
GeolocateControl	positionOptions	Geolocation API 的选项
	trackUserLocation	是否跟踪用户位置
	showUserLocation	是否在地图上显示用户位置
	showUserHeading	是否显示用户 heading（方向）
ScaleControl	maxWidth	比例条的最大宽度
	unit	单位系统（公制、英制或海里）
FullscreenControl	container	要全屏的元素
AttributionControl	compact	是否以紧凑模式显示
	customAttribution	自定义归属文本