标记与图标

本文档涵盖 Leaflet 的标记和图标系统，支持在地图上放置可交互、可点击的标记。标记使用可自定义的图标表示地理点，支持用户交互包括拖拽、点击和键盘导航。关于矢量图形和路径的信息，请参阅 矢量图层。关于弹窗和提示框覆盖层，请参阅 弹窗与提示框。

架构概览

标记系统由两个主要组件组成：处理定位和交互的 Marker 类，以及定义视觉外观的图标系统。标记扩展基类 Layer，并与 Leaflet 的事件系统和地图 pane 集成进行渲染。

标记与图标类层次结构

100%

Marker 类实现

Marker 类扩展 Layer，管理地理定位、DOM 元素生命周期和用户交互。标记使用 LatLng 位置和可选的 Icon 实例进行初始化。

标记选项和配置

选项	类型	默认值	描述
icon	Icon	DefaultIcon()	用于渲染的图标实例
draggable	Boolean	false	启用标记拖拽
keyboard	Boolean	true	启用键盘辅助功能
title	String	''	浏览器提示文本
alt	String	'Marker'	图标图片的替代文本
zIndexOffset	Number	0	用于堆叠的 Z-index 偏移
opacity	Number	1.0	标记不透明度
riseOnHover	Boolean	false	悬停时置于顶层

图标系统架构

图标系统使用插件模式，不同的图标类型实现相同的接口。基类 Icon 定义创建契约，而具体实现处理特定的渲染方法。

图标创建流程

100%

图标类型

Icon（基于图片的图标） 基类 Icon 创建带有可配置 URL、尺寸和锚点的 <img> 元素。它支持 Retina 显示屏和阴影图片。

// Icon 配置选项
const customIcon = new Icon({
    iconUrl: 'marker-icon.png',
    iconRetinaUrl: 'marker-icon-2x.png',
    iconSize: [25, 41],
    iconAnchor: [12, 41],
    popupAnchor: [1, -34],
    shadowUrl: 'marker-shadow.png',
    shadowSize: [41, 41]
});

DefaultIcon（默认蓝色标记） DefaultIcon 扩展 Icon，使用预定义的蓝色标记图片和自动路径检测。它尝试相对于 Leaflet CSS 文件定位图标资源。

DivIcon（基于 HTML 的图标）
DivIcon 创建 <div> 元素而不是图片，允许自定义 HTML 内容和 CSS 样式。它忽略与图片相关的选项，从不创建阴影。

标记生命周期和定位

标记遵循标准的 Layer 生命周期，对图标创建、定位和基于纬度的 Z-index 管理有特殊处理。

标记生命周期流程

100%

定位和 Z-Index 管理

标记基于其纬度自动计算 Z-index 值以确保正确的视觉堆叠。南部的标记显示在北部标记之上。

// _setPos() 中的 Z-index 计算
this._zIndex = pos.y + this.options.zIndexOffset;

交互与事件

标记支持全面的交互，包括拖拽、键盘导航和标准指针事件。交互系统与 Leaflet 的事件传播机制集成。

标记事件流

100%

标记事件

事件	描述	事件数据
move	标记位置变化时触发	{oldLatLng, latlng}
click	标准指针点击	标准 DOM 事件数据
drag*	拖拽事件	位置和拖拽状态数据

拖拽系统

标记拖拽通过 MarkerDrag 类（扩展 Handler）实现，处理指针事件、自动平移和位置更新。MarkerDrag 处理程序在标记的 _initInteraction() 方法中初始化，使用 Draggable 工具进行底层拖拽处理。

MarkerDrag 处理程序流程

100%

与地图 Pane 集成

标记使用地图的 pane 系统进行 DOM 组织，为图标和阴影使用独立的 pane 以确保正确的渲染顺序。

标记 Pane 使用

100%

辅助功能

标记包含全面的辅助功能支持，包括键盘导航、ARIA 属性和屏幕阅读器兼容性。

// _initIcon() 中的辅助功能设置
if (options.keyboard) {
    icon.tabIndex = '0';
    icon.setAttribute('role', 'button');
}