做地图类前端时间久了会发现高德地图 JS API 自带的那根红色大头针和白色气泡几乎是我见过“被替换率”最高的默认组件。刚接触时觉得挺省事new 一个 Marker 就完事等真正做门店地图、运营点位、活动大屏时默认图标和窗口一放上去整个页面瞬间变成“开发 demo 风”。这篇就围绕高德地图 JS Web 开发里的两个高频需求展开怎么给 Marker 添加自定义图标以及怎么把 InfoWindow 改造成完全自定义的窗口标记。内容会从原理讲到可直接复制的代码最后把我踩过的几个坑拆开揉碎说清楚。适合已经会基本的地图初始化、但还没深入研究 Marker 和 InfoWindow 定制逻辑的同学文章里所有代码都以高德 JS API 2.0 为基准。1. 从默认大头针说起什么时候需要自定义图标与窗口标记1.1 默认能力为什么不够用先别急着写代码先想清楚你到底在解决什么问题。高德 JS API 默认的 Marker 是一张红色图钉InfoWindow 是一个白底、窄边框、右上角带关闭叉的气泡。这两个组件在“能显示点、能弹信息”这件事上没有毛病但放到真实业务里问题立刻冒出来门店地图场景下你要在每个点上放商户 Logo 或评分数字红色大头针完全没有信息承载能力运营看板场景下不同状态的点要用不同颜色区分默认图标改不了内部结构活动专题页里点图标弹出的是带按钮、带图片、带自定义样式的卡片默认气泡根本装不下品牌方对视觉统一有要求地图上的元素必须和页面其他模块是同一种设计语言。我在一个真实项目里见过最夸张的情况因为没人改图标上线后一个城市 40 多个门店点全是同款红图钉用户根本分不清哪家店在营业、哪家店在维护最后产品经理只能临时在气泡文本里加颜色符号强行区分。这就是典型的“默认组件看着能用实际不够用”。1.2 自定义带来的三种典型收益把图标和窗口换成自己的收益主要体现在三个维度第一是信息密度。自定义图标可以直接在点上放数字、放状态点、放缩写标签用户扫一眼地图就能完成信息预判不用挨个点开看详情。第二是视觉一致性。地图里的标记点、气泡卡片、页面卡片用同一套色板、圆角、阴影整个页面才不会像“地图是地图页面是页面”的两个孤立模块。第三是交互可控。默认窗口的行为是固定的自己定制的窗口可以挂按钮、挂图片、挂任何你想挂的事件甚至可以做成一个微型组件。这两个能力本质上是在动 Marker 和 InfoWindow 这两个高德底层覆盖物的“表皮”。所以后面的内容我按两条线分别拆。2. 自定义标记图标Icon 实例与 content 模板两条路线高德 Marker 自定义图标有两条路线很多人只知道第一条结果一遇到复杂样式就放弃了。2.1 路线一AMap.Icon 配图片适合“换皮肤不改结构”第一条路线是给 Marker 传一个AMap.Icon实例。核心逻辑是你准备一张图片告诉高德这个图片在地图上占多大、锚点在哪。代码大概是这样的const icon new AMap.Icon({ size: new AMap.Size(32, 32), // 图标占位尺寸 image: https://example.com/pin.png, // 图片地址 imageSize: new AMap.Size(32, 32), // 图片绘制尺寸 anchor: new AMap.Pixel(16, 32) // 锚点对准底部中心 }); const marker new AMap.Marker({ position: [116.402, 39.915], icon: icon, title: 门店A }); map.add(marker);注意几个容易翻车的参数。size是“图标容器”的大小高德会按这个尺寸规划点击热区imageSize是图片实际被绘制的大小如果只填size不填imageSize在某些情况会按图片原始尺寸绘制导致图标“炸”得很大anchor是锚点它决定经纬度坐标点落在图标的哪个位置。默认 Icon 的锚点是左上角(0, 0)如果不改Marker 的位置会偏到图片左上角而不是图钉底部尖尖视觉上这个点会“飘”起来。这条路线最大的优点是简单、性能好尤其适合大量点位的场景。缺点也很明显它只能换一张图没法在一个图标里组合多个 DOM 元素。你想在图标上同时展示“状态圆点”和“文字标签”就得另外想办法了。2.2 路线二content 模板配 CSS适合“完全重新设计”第二条路线是直接给 Marker 传content让高德把一个 HTML 字符串作为覆盖物渲染到地图上。这相当于你把 Marker 当成一个“浮在地图上的 div”来用想放什么就放什么。const marker new AMap.Marker({ position: [116.402, 39.915], content: div classpin span classpin__dot/span span classpin__label门店A/span /div , anchor: bottom-center, offset: new AMap.Pixel(0, -6) }); map.add(marker);然后配合 CSS 就能做出几乎任何样式的标记.pin { position: relative; display: inline-flex; align-items: center; gap: 4px; padding: 4px 10px; border-radius: 12px; background: #fff; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.16); font-size: 12px; color: #333; white-space: nowrap; } .pin::after { content: ; position: absolute; left: 50%; bottom: -6px; transform: translateX(-50%); border: 6px solid transparent; border-top-color: #fff; }content 方式的本质是把“点”变成“可任意排版的卡片”业务上最常见的做法是做成一个带小三角的气泡标签。它和 Icon 方式最大的区别是Icon 方式是“一张图”content 方式是“一堆 DOM”。DOM 灵活但数量变多后性能会劣化海量点位时要注意。2.3 两条路线的选型对比我在实际项目里一般按这个标准选对比维度Icon 方式content 方式自定义程度低只能换图高任意 HTML CSS性能表现好适合几百上千个点一般DOM 多时需优化动态改样式麻烦要换 Icon 实例方便直接改 DOM 类名图标内嵌文案不支持支持代码维护成本低中CSS 要同步维护典型场景品牌图钉、场景固定带状态、数字、标签的复合图标一句话总结点位上只有图片优先 Icon点位上要有动态信息、要跟随业务状态变化优先 content。多数门店地图、运营地图都会选 content因为它能塞的东西多后面接“点击弹窗”也更顺手。3. 自定义信息窗口isCustom 属性背后的样式接管逻辑3.1 isCustom 打开后发生了什么高德的 InfoWindow 有一个属性isCustom默认是 false表示用高德自带的窗口 UI。一旦设为 true高德就不再帮你套默认容器你传什么 content它就显示什么。很多新手以为“isCustom 只是样式变丑了”其实它是把窗口的整个生命周期和样式体系都交还给了你自己。const infoWindow new AMap.InfoWindow({ isCustom: true, offset: new AMap.Pixel(0, -24), autoMove: true });这里最容易被忽略的是isCustom: true之后高德默认提供的右上角关闭叉也没了。窗口打开后用户如果不知道自己点哪能关这个气泡就会一直“焊”在地图上。要解决这个问题你必须在自己的 content 里放一个关闭按钮并且手动调用infoWindow.close()。我见过不少人在这里来回试了很久最后发现“窗口关不掉”不是 bug而是 isCustom 的设计如此高德把关闭按钮也当成“默认 UI”的一部分你既然要定制连关闭逻辑也得一起接管。3.2 自定义窗口的组成与关闭逻辑自定义窗口我通常建议做成一个卡片结构包含头部、正文、关闭按钮function buildInfoHTML(shop) { return div classinfo-card div classinfo-card__hd strong${shop.name}/strong button classinfo-card__close typebutton×/button /div div classinfo-card__bd p classinfo-card__addr${shop.address}/p span classinfo-card__tag${shop.tag}/span /div /div ; }关闭逻辑有几种绑法。最稳妥的是事件委托地图容器本身监听 click如果点到关闭按钮就 close。注意一定不要让按钮的 click 冒泡到上层否则会出现“刚点开就立刻被关闭”的奇怪现象。map.getContainer().addEventListener(click, (e) { if (e.target.closest(.info-card__close)) { infoWindow.close(); e.stopPropagation(); } });3.3 offset 偏移的调整思路对于自定义窗口还有一个容易让人困惑的点offset到底怎么算。InfoWindow 的定位点是 Marker 的锚点offset是窗口相对锚点的整体偏移。默认窗口因为带箭头高德会帮你对齐换到 isCustom 后就得自己通过差值和 CSS 三角箭头来模拟“气泡尖对准锚点”的效果。一个可复用的思路是这样的先把窗口做成一个有箭头的卡片箭头位置固定例如用 CSS 的::after画三角窗口距离锚点的垂直间距设为 N 像素那么offset的 y 就设为-N箭头在水平方向居中窗口如果本身也是居中定位x 一般设为 0 或小偏移。实际调的时候我习惯先给窗口加一个半透明背景和明显边框在浏览器里反复调整 offset 的两个值确认箭头对准 Marker 后再去掉辅助样式。这个方法比一遍遍刷新页面盲试要快得多。4. 一个可以直接迁走的 Demo图标、窗口与点击交互的完整配合4.1 准备数据与项目结构下面给一个完整可运行的例子场景是“城市门店地图”地图上有一批门店点每个点用自定义 content 图标显示营业状态点击后弹出自定义窗口展示门店信息。先准备一份模拟数据const shops [ { name: 门店A, lng: 116.402, lat: 39.915, status: open, tag: 营业中, address: 示例路 1 号 }, { name: 门店B, lng: 116.410, lat: 39.920, status: closed, tag: 暂停营业, address: 示例路 2 号 }, { name: 门店C, lng: 116.395, lat: 39.908, status: open, tag: 营业中, address: 示例路 3 号 } ];坐标就是普通的经纬度数字不需要额外处理。注意我特意没有真地名你自己项目里换成后台返回的真实数据即可。4.2 核心代码逐段拆解初始化地图之前记得先配好高德 2.0 的安全密钥很多地图渲染不出来的问题都出在这script window._AMapSecurityConfig { securityJsCode: 你的安全密钥 }; /script script srchttps://webapi.amap.com/maps?v2.0key你的Key/script然后是地图初始化const map new AMap.Map(container, { zoom: 13, center: [116.402, 39.915], viewMode: 2D });接着写一个生成 content 图标的方法。这里我用 content 路线因为门店点有营业状态需要动态改变标签颜色function createPinHTML(shop) { const cls shop.status open ? pin--open : pin--closed; return div classpin ${cls} span classpin__dot/span span classpin__label${shop.name}/span /div ; }循环创建 Marker并把它们的 click 事件统一接到同一个 InfoWindow 实例上。共享实例是重点不要每个 Marker 都 new 一个 InfoWindow否则地图上可能出现多个气泡同时存在也很难统一管理关闭const infoWindow new AMap.InfoWindow({ isCustom: true, offset: new AMap.Pixel(0, -24), autoMove: true }); shops.forEach((shop) { const marker new AMap.Marker({ position: [shop.lng, shop.lat], content: createPinHTML(shop), anchor: bottom-center, offset: new AMap.Pixel(0, -6), title: shop.name }); marker.on(click, () { infoWindow.setContent(buildInfoHTML(shop)); infoWindow.open(map, marker.getPosition()); map.setCenter(marker.getPosition()); if (map.getZoom() 15) { map.setZoom(15); } }); map.add(marker); });setCenter和setZoom是可选的交互增强点击点位后让地图中心移动到该点并适当放大方便用户聚焦。这个细节在手机端尤其重要不然小屏上点一个边角处的 marker弹窗会被挤出屏幕。4.3 把这段逻辑搬到你自己的页面里直接把上面代码复制到项目里大概率能跑起来但要想真正变成沉淀我建议改造成一个小的“地图点位组件”把createPinHTML、buildInfoHTML拆成独立函数数据源统一传对象所有尺寸、颜色、偏移量抽成常量或 CSS 变量避免散落在代码里Marker 点击事件里只做一件事把当前shop对象交给统一的渲染函数这样以后加字段、改卡片样式都只动一个地方地图容器上只绑定一次关闭事件不要给每个关闭按钮单独绑定防止重复监听器堆积。我之前在一个项目中就是按这个思路封装后来从“城市门店”扩展到“服务网点 分时状态 详情弹窗”只改了数据结构和模板函数地图层的代码一行没动。5. 踩坑记录锚点偏移、窗口关不掉、层级盖住的完整排查链路再分享几个真实项目里踩过的坑每个都附上排查过程按“现象 → 排查 → 解决”的链路写。5.1 坑一图标“站”不住点击点位后定位点漂移现象是用自定义图片图标时Marker 看起来挂在地图上但把地图setCenter到marker.getPosition()之后视野中心反而偏到了图标右上角附近气泡弹出来位置也不对。排查时我在控制台打印了marker.getPosition()和marker.getIcon().getAnchor()发现坐标点本身没变但 Icon 默认锚点是(0, 0)也就是图片左上角。地图中心对齐的是“左上角”而不是“图钉底部”视觉上自然就漂了。解决方式很简单给 Icon 实例补上锚点const icon new AMap.Icon({ size: new AMap.Size(32, 32), image: imgUrl, imageSize: new AMap.Size(32, 32), anchor: new AMap.Pixel(16, 32) // 水平中心 垂直底部 });通用公式是如果图片宽度为 W、高度为 H锚点一般设成(W / 2, H)。如果你用的是 content 方式则直接在 Marker 上设置anchor: bottom-center语义更清晰。5.2 坑二自定义窗口打开后关不掉或者一打开就立刻消失这个坑有两副面孔。一副是“关不掉”isCustom 为 true 之后窗口里没有默认叉号用户也找不到哪里关。另一副是“关太快”点击 Marker 打开窗口的瞬间窗口闪现一下就被关闭了像什么都没发生。“关不掉”的原因前面已经说过isCustom 把默认关闭 UI 也交还给你了需要自己在 content 里放关闭按钮并调用infoWindow.close()。“关太快”则多半是地图容器上绑了 click 关闭逻辑marker 的 click 事件冒泡到容器后触发了 close。排查时先检查事件绑定。如果地图容器上确实监听了 click 并执行 close那么点击 Marker 时要把这个事件的冒泡终止掉或者在 marker 的 click 回调里用e.stopPropagation()marker.on(click, (e) { e.stopPropagation(); infoWindow.open(map, marker.getPosition()); });另外弹窗卡片内部的点击操作比如点击卡片上的按钮也要小心冒泡。给卡片容器加上stopPropagation能避免很多“点按钮结果把弹窗关掉”的诡异问题。5.3 坑三自定义 Marker 把 InfoWindow 窗口盖住了现象是窗口明明打开了但有一块内容被旁边的 marker 挡住了窗口的层级看起来不对。原因是 content 方式创建的 Marker 是真实 DOM如果你在 CSS 里给 marker 设置了很高的z-index它就会盖住下面默认层级的 InfoWindow 内容。排查时我用浏览器开发者工具检查了对应 DOM 的z-index发现 marker 的层级被设成了 999而高德 InfoWindow 默认层级并没有那么高。解决思路有两个方向方向一把 Marker 的z-index统一控制在一个较低区间比如 100 以内方向二给 InfoWindow 实例设置更高的zIndex高德支持这个参数const infoWindow new AMap.InfoWindow({ isCustom: true, zIndex: 1200, offset: new AMap.Pixel(0, -24) });优先推荐方向一。因为地图上 marker 数量往往远多于窗口全局把 marker 的层级压低既避免盖窗口也让“弹出态”的视觉层级更有层次感。5.4 坑四复用同一个 InfoWindow内容更新后还显示旧数据现象是点击门店 A 后弹窗正常点击门店 B 后弹窗里显示的依旧是门店 A 的信息。排查时发现我在infoWindow.open(map, marker.getPosition())之前没有调用setContent或者调用时传入的是同一个 DOM 元素高德只是把旧元素又展示了一遍并没有真正更新内容。解决方式是每次 marker 点击时都用新的 HTML 字符串调用一次setContent再用open打开。如果 setContent 传入的是已有的 HTMLElement 实例最好是cloneNode(true)或者每次动态创建新的节点避免高德内部复用同一个引用导致数据不刷新。更稳妥的做法是把“构建 content”和“打开窗口”拆成两个步骤确保打开前内容一定是新的marker.on(click, () { infoWindow.setContent(buildInfoHTML(shop)); infoWindow.open(map, marker.getPosition()); });把这几条坑串起来看自定义图标和窗口的核心风险就三条锚点是坐标系、关闭是生命周期、层级是渲染顺序。排查任何“视觉不对、交互不对、层级不对”的问题时先回到这三个维度去查基本都能快速定位。我在实际操作中还有一个习惯自定义窗口没调好之前先给卡片加半透明背景和彩色的边框肉眼确认对齐没问题后再把辅助样式删掉。对比反复刷新页面盲猜参数这个办法省下的时间相当可观。前端调试地图覆盖物很多问题不是 API 不会用而是缺少一个“能看清边界”的视觉抓手把这套方法用上大部分坑都不会陪你过夜。