Leaflet 自定义 Marker 图标实战：Icon 类、锚点配置与源码原理

本篇技术指南围绕 Leaflet 官方示例 example-one-icon.md 展开，讲解如何为地图上的 Marker 定制专属图标：从准备图标与阴影图片素材，到直接构造 Icon 实例、再进阶为继承 Icon 定义可复用的图标类（配合同一教程的 index.md 与完整示例 example.md）。读完本文，你将掌握 iconSize、iconAnchor、popupAnchor 等全部关键参数的含义与取值技巧，并理解 Leaflet 底层 Icon 是如何把这些配置渲染成真实 DOM 元素的。

教程示例概况：一个开箱即用的单图标页面

example-one-icon.md 是一个采用 tutorial_frame 布局的可运行示例页，页面内嵌一段 ES Module 脚本，完整演示了"自定义图标类 + 单 Marker"的最小闭环。其核心脉络只有三步：

1. 创建地图与 OSM 底图；
2. 定义继承自 Icon 的 LeafIcon 类，用 setDefaultOptions 固化共享样式参数；
3. 用 new LeafIcon({iconUrl: 'leaf-green.png'}) 创建绿色叶子图标并挂到 Marker 上。

下面我们逐步拆解，并在每一步结合仓库源码（src/layer/marker/Icon.js、src/layer/marker/Marker.js）说明背后的实现机制。

第一步：准备图标与阴影图片素材

自定义 Marker 图标通常需要两类图片：图标本体（icon）和它脚下的阴影（shadow）。本教程从 Leaflet logo 出发制作了 4 张图片：绿、红、橙三张 38×95 的叶子图标，以及一张 50×64 的阴影图：

• 图标图：docs/examples/custom-icons/leaf-green.png
• 图标图：docs/examples/custom-icons/leaf-red.png
• 图标图：docs/examples/custom-icons/leaf-orange.png
• 阴影图：docs/examples/custom-icons/leaf-shadow.png

需要注意：图中白色区域实际是透明的。一张边缘干净、带透明通道的 PNG 是图标"钉"在地图上不露破绽的前提——如果保留白色背景，图标会变成一个难看的白色方块。阴影图则可以包含半透明渐变，用于模拟图标在地图上的立体投影感。

第二步：搭建地图与底图

示例页顶部先完成了地图初始化与底图加载（来自 example-one-icon.md）：

import {LeafletMap, TileLayer, Marker, Icon} from 'leaflet';
const map = new LeafletMap('map').setView([51.5, -0.09], 13);

new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
	attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);

要点说明：

• 这里使用 ES Module 方式按需导入 LeafletMap、TileLayer、Marker、Icon 四个符号；new LeafletMap('map') 挂载到页面中 id="map" 的容器元素上，setView([51.5, -0.09], 13) 将视图定位到伦敦坐标、缩放级别 13。
• 底图是 OpenStreetMap 瓦片服务，{z}/{x}/{y} 是瓦片坐标占位符。按 OSM 使用规范，attribution 版权声明不可省略（完整示例见 example.md 的同一段初始化代码）。
• 由于 OSM 瓦片是跨域资源，若后续需要读取瓦片像素数据，可给 TileLayer 传 crossOrigin 选项——这与 Icon 的 crossOrigin 参数同理（见下文参数表）。

方式一：直接构造 Icon 实例（一次性定制）

如果只需要一两个图标，可以直接把全部选项传给 Icon 构造函数（见教程 index.md）：

const greenIcon = new Icon({
	iconUrl: 'leaf-green.png',
	shadowUrl: 'leaf-shadow.png',
	iconSize:     [38, 95], // size of the icon
	shadowSize:   [50, 64], // size of the shadow
	iconAnchor:   [22, 94], // point of the icon which will correspond to marker's location
	shadowAnchor: [4, 62],  // the same for the shadow
	popupAnchor:  [-3, -76] // point from which the popup should open relative to the iconAnchor
});

然后把它交给 Marker：

const marker = new Marker([51.5, -0.09], {icon: greenIcon}).addTo(map);

关键参数详解（依据 Icon.js 源码中的默认值与注释）

参数	默认值	说明
iconUrl	null（必填）	图标图片 URL，可为绝对路径或相对脚本的路径。若缺省会抛出 Error('iconUrl not set in Icon options (see the docs).')（见 Icon.js）。
iconRetinaUrl	null	Retina 屏专用的高清图标 URL，仅当浏览器 Browser.retina 为真时启用。
iconSize	null	图标图片的像素尺寸 [宽, 高]，例中为 [38, 95]。若缺省，会直接从图片实际尺寸推断；传单个数字则视为正方形。
iconAnchor	null	图标"尖端"相对其左上角的坐标。该点会被精确对齐到 Marker 的地理位置。若未指定，默认取尺寸的一半（即居中）；也可用 CSS 负 margin 实现（见 Icon.js）。例中 [22, 94] 表示图标底部尖端对准定位点。
popupAnchor	[0, 0]	Popup 弹出位置相对 iconAnchor 的偏移，例中 [-3, -76] 让气泡从图标尖端正上方弹出。
tooltipAnchor	<a href="https://link.gitcode.com/i/4bd8588647b53fd9aed1ddfc6581dc4b" target="_blank">0, 0]	Tooltip 提示框相对 iconAnchor 的偏移（源码默认值，[Icon.js）。
shadowUrl	null	阴影图片 URL。不设置则不渲染阴影。
shadowRetinaUrl	null	阴影的 Retina 版本 URL。
shadowSize	null	阴影图片尺寸，例中为 [50, 64]。
shadowAnchor	null	阴影"尖端"坐标；未指定时与 iconAnchor 相同（Icon.js 中 `options.shadowAnchor
className	''	同时赋给图标与阴影 <img> 的自定义 CSS 类名，便于用样式表微调。
crossOrigin	false	是否给图片加 crossOrigin 属性；传字符串则原样设置。需要读取图片像素数据（如 canvas 处理）时使用（Icon.js）。

锚点为什么重要

iconAnchor 是自定义图标最容易踩坑的参数。Leaflet 的默认蓝色图标是"大头针"形状，尖端在地图上；你的自定义图标若是一枚圆点，则希望圆心对准定位点；若是一棵树，则希望树干根部对准。从源码看，锚点通过负 margin 生效（Icon.js）：

img.style.marginLeft = `${-anchor.x}px`;
img.style.marginTop  = `${-anchor.y}px`;

即把图片相对 Marker 像素坐标向左、向上偏移锚点距离，从而实现"锚点对准定位点"。iconSize 则直接写进 width/height 样式（Icon.js）。理解了这一实现，你就能精确预判任意形状图标在地图上的最终落点。

方式二：继承 Icon 定义图标类（本示例核心）

当多个图标共享大量参数时，重复书写冗长的选项对象显然不划算。example-one-icon.md 演示的正解是：定义一个继承 Icon 的子类，把公共选项固化在静态块中：

class LeafIcon extends Icon {
	static {
		this.setDefaultOptions({
			shadowUrl: 'leaf-shadow.png',
			iconSize:     [38, 95],
			shadowSize:   [50, 64],
			iconAnchor:   [22, 94],
			shadowAnchor: [4, 62],
			popupAnchor:  [-3, -76]
		});
	}
}

setDefaultOptions 是 Leaflet 类系统（src/core/Class.js）提供的静态方法，用于把选项写入类的默认选项表，实例化时会与用户传入的选项合并。这样创建实例时只需传差异项：

const greenIcon = new LeafIcon({iconUrl: 'leaf-green.png'});

随后即可批量产出同风格、不同配色的图标（同教程 index.md 的做法）：

const greenIcon = new LeafIcon({iconUrl: 'leaf-green.png'}),
	redIcon = new LeafIcon({iconUrl: 'leaf-red.png'}),
	orangeIcon = new LeafIcon({iconUrl: 'leaf-orange.png'});

对应完整示例 example.md 中，三个图标被放到伦敦不同坐标并绑定弹出气泡：

new Marker([51.5, -0.09], {icon: greenIcon}).addTo(map).bindPopup("I am a green leaf.");
new Marker([51.495, -0.083], {icon: redIcon}).addTo(map).bindPopup("I am a red leaf.");
new Marker([51.49, -0.1], {icon: orangeIcon}).addTo(map).bindPopup("I am an orange leaf.");

而 example-one-icon.md 只保留其中第一句，作为单图标的精简演示：

const mGreen = new Marker([51.5, -0.09], {icon: greenIcon}).addTo(map);

一个类、三行实例化、三个风格统一的 Marker，这正是"继承 + 默认选项"模式的实战价值：样式集中管理、实例声明极简、后期改配色只动一处。

源码级原理：Icon 如何一步步渲染成 <img>

把参数变成真实 DOM 的链路在 Icon.js 中清晰可见：

1. Marker 初始化时会调用 options.icon.createIcon(oldIcon) 与 createShadow(oldIcon)（Marker.js）。
2. createIcon / createShadow 内部都走 _createIcon(name, oldIcon)：先由 _getIconUrl(name) 取 URL，再 _createImg(src, oldIcon) 创建/复用 <img> 元素，最后 _setIconStyles(img, name) 应用样式。
3. _setIconStyles 依次处理尺寸（nameSize）、锚点（iconAnchor/shadowAnchor）、CSS 类名（leaflet-marker-icon/leaflet-marker-shadow）与负 margin，最终产物是一个完全由选项驱动样式的 <img>。

值得注意的细节：

• 图片复用：oldIcon 存在且仍是 <img> 时直接复用元素、仅更新 src，避免重复创建 DOM，这对高频刷新场景更友好。
• Retina 自适应：_getIconUrl 的实现是 Browser.retina && options[name + 'RetinaUrl'] || options[name + 'Url']——在高分屏且提供了 iconRetinaUrl 时才加载高清图，否则回退普通图。
• 阴影可缺席：未设置 shadowUrl 时 createShadow 返回 null，Marker 不会渲染任何阴影元素。

顺带了解：Leaflet 默认蓝色图标从哪来

不传 icon 时，Marker 使用 DefaultIcon（默认选项定义见 DefaultIcon.js）：蓝底白边大头针 marker-icon.svg（25×41）、锚点 [12, 41]、阴影 marker-shadow.svg（41×41）。它还通过 _detectIconPath() 从 leaflet.css 的背景图或 <link> 标签自动推断图片所在目录。想全局换风格，可以像文档说明的那样改写 DefaultIcon.prototype.options，或直接覆写 Marker.prototype.options.icon。

进阶技巧与常见问题

• 动态换图标：Marker 提供 getIcon() / setIcon(icon) 方法（Marker.js）。setIcon 在图标已上地图时会重新初始化图标并 update()，适合做"选中态高亮""状态切换"等交互。
• 无障碍支持：Marker 默认把 alt 设为 'Marker'（Marker.js），可结合 title 选项为图标添加悬停提示与屏幕阅读器文本。
• 不想用图片？用 DivIcon：Leaflet 还提供 DivIcon，用 <div> 承载任意 HTML/CSS 内容代替图片，createShadow() 直接返回 null，适合文字标记、数字聚合点等场景。
• zIndex 与 hover 层级：Marker 默认按纬度自动排定 zIndex；如需图标置顶可设 zIndexOffset 或 riseOnHover: true（默认选项见 Marker.js）。

延伸阅读

• 完整多图标示例（含绿/红/橙三 Marker 与 Popup）：example.md
• 本教程主文档（含全部讲解与图示）：index.md
• Icon 类完整 API 参考：docs/reference.html 中的 Icon / Icon options 章节
• Marker 相关教程合集：docs/examples.md

至此，从单图标页 example-one-icon.md 出发，你已经掌握了 Leaflet 自定义 Marker 图标的完整链路：素材准备 → 参数语义 → 类继承复用 → 底层渲染原理，足以在真实项目中打造风格统一、定位精准的自定义地图标记。