简介：这份资源面向使用 ArcGIS API 4.x for JavaScript 进行 Web GIS 开发的学习者与前端工程师，聚焦地图加载与多气泡窗口展示这一常见交互场景。包内共 1 个文件，为单个 html 页面，压缩包约 3KB，体量轻巧，可直接在浏览器中打开运行，便于快速理解地图初始化、视图创建与弹窗配置的完整流程。内容围绕 Map、MapView 的构建，以及 PopupTemplate 的定义与图层绑定展开，并演示如何通过点击事件与 openPopup 方法同时呈现多个气泡窗口，帮助读者掌握弹窗内容模板、图层关联与交互触发的关键写法。目前已有 157 人学习，适合作为入门示例或项目中的弹窗功能参考，读者可据此快速搭建可运行的地图页面，并在此基础上扩展自定义样式与多图层弹窗管理。
1. 地图上同时弹多个气泡，为什么你的 Popup 总被顶掉
做过 Web GIS 的都知道，ArcGIS API 4.x for JavaScript 里MapView默认只维护一个popup实例。你点第一个点，气泡弹出来；再点第二个点，第一个就没了。这不是 bug，是设计——4.x 把 popup 收敛成视图级单例，跟 3.x 那种每个InfoWindow各自为政的玩法完全不同。于是「地图加载多个气泡窗口展示」就成了一个高频刚需：管线巡检要同时看几个阀门状态、物流调度要对比多个网点、应急指挥要在一张图上铺开多个事件点。这份arcgis api 4.x for js 地图加载多个气泡窗口展示.zip里的map4.html，干的就是这件事——不依赖额外插件，用原生MapView的 popup 机制把多个气泡稳定地摆在地图上。适合已经能跑通基础地图、但被单例 popup 卡住的前端和 GIS 开发。
2. 先搞懂 4.x 的 popup 单例机制：为什么不能直接 new 一堆
2.1 MapView 的 popup 是视图级单例
在 4.x 里，view.popup是一个Popup对象，整个视图共享一个。你调用view.popup.open()，本质是把这个唯一的 popup 挪到新位置、换掉内容。所以「多个气泡」在 4.x 语境下有两层含义：一是同一时刻在地图上并存多个独立气泡，二是通过features数组让一个 popup 里分页展示多条记录。前者需要绕开单例，后者是官方推荐路径。map4.html走的是前者——用多个Graphic各自挂PopupTemplate，再配合自定义定位逻辑，让它们同时可见。
理解这一点很关键，因为很多人一上来就new Popup()然后往view.ui里塞，结果发现要么不显示，要么点击事件错乱。4.x 的 popup 跟view.container的 DOM 层级、view.popup.dockEnabled、view.popup.autoOpenEnabled这几个开关强耦合，硬塞会翻车。
2.2 PopupTemplate 与 Popup 的分工
PopupTemplate是「内容模板」，定义标题、字段、媒体、附件；Popup是「展示容器」，负责定位、开合、分页。多个气泡的核心思路是：每个要素有自己的PopupTemplate，但展示时要么复用同一个Popup做分页，要么用view.openPopup()配合location和features手动控制。map4.html里对每个图层分别配置了popupTemplate，并在点击时用hitTest拿到命中要素，再决定是开新气泡还是合并。
// 为每个要素图层单独配置 PopupTemplate const templateA = new PopupTemplate({ title: "泵站 {name}", content: [{ type: "fields", fieldInfos: [ { fieldName: "pressure", label: "压力(MPa)" }, { fieldName: "status", label: "运行状态" } ] }] }); const layerA = new FeatureLayer({ url: "https://your-server/arcgis/rest/services/pump/FeatureServer/0", popupTemplate: templateA, outFields: ["*"] }); map.add(layerA);这段代码的逻辑是：模板绑定在图层上，点击时 API 自动用模板渲染。参数上outFields: ["*"]必须写，否则hitTest拿不到属性，气泡里字段全是空——这是最常见的「气泡弹出来但没内容」原因。fieldInfos里的fieldName要和服务端字段名严格一致，大小写敏感。
2.3 多气泡并存的两种落地路径
路径一：view.popup.open({ features, location })传数组，popup 内部出现左右翻页，视觉上是一个气泡但承载多条。路径二：关闭view.popup.autoOpenEnabled，自己用view.openPopup()在多个location上开，配合dockEnabled: false让气泡浮在地图坐标上。map4.html用的是路径二加自定义 DOM 覆盖层，因为需求是「同时看到多个」，翻页不满足。这里要注意，4.x 原生并不支持真正意义上的多个独立 popup 实例，所以map4.html的做法是：保留一个主 popup 做详情，另外用Graphics加TextSymbol或自定义view.ui容器模拟常驻气泡。
3. 把 map4.html 跑起来：从 CDN 引入到多气泡触发
3.1 引入 API 与初始化地图视图
先看map4.html的骨架。4.x 的引入方式和 3.x 不同，用esri-loader或直接<script>加require。文件里用的是官方 CDN 加require回调，这是最稳的写法，不依赖构建工具。
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <link rel="stylesheet" href="https://js.arcgis.com/4.29/esri/themes/light/main.css" /> <script src="https://js.arcgis.com/4.29/init.js"></script> <style> html, body, #viewDiv { height: 100%; margin: 0; } /* 自定义气泡容器，用于并存展示 */ .multi-popup { position: absolute; background: #fff; border: 1px solid #ccc; border-radius: 4px; padding: 8px 12px; font-size: 13px; box-shadow: 0 2px 8px rgba(0,0,0,.2); pointer-events: auto; } </style> </head> <body> <div id="viewDiv"></div> <script> require([ "esri/Map", "esri/views/MapView", "esri/layers/FeatureLayer", "esri/PopupTemplate", "esri/Graphic" ], function(Map, MapView, FeatureLayer, PopupTemplate, Graphic) { // 初始化逻辑见下 }); </script> </body> </html>init.js是 4.x 的 AMD 加载入口，require数组里列出用到的模块，回调参数顺序一一对应。CSS 必须引，否则比例尺、缩放按钮、popup 样式全乱。#viewDiv高度设 100% 是硬性要求，父级没高度地图就是一片空白——这个坑新手几乎必踩。
3.2 创建 Map 与 MapView 并绑定容器
const map = new Map({ basemap: "streets-navigation-vector" // 4.x 推荐用矢量底图，性能更好 }); const view = new MapView({ container: "viewDiv", map: map, center: [116.397, 39.908], // 北京 zoom: 12, popup: { dockEnabled: true, dockOptions: { buttonEnabled: false, breakpoint: false, position: "top-right" }, autoOpenEnabled: false // 关键：关掉自动开，改手动控制 } });autoOpenEnabled: false是map4.html的核心开关。默认 true 时，点击图层要素 API 自动开 popup，你没法插手多气泡逻辑。关掉后，所有开合都由view.on("click")里的代码决定。dockEnabled控制气泡是否停靠到视图边缘，做多气泡并存时通常设 true 让主详情停靠，模拟气泡浮在坐标上，两者不打架。basemap用矢量底图是因为栅格底图在缩放时容易糊，矢量底图配合 4.x 的 WebGL 渲染更顺。
3.3 用 hitTest 命中多个要素并分发气泡
view.on("click", function(event) { view.hitTest(event).then(function(response) { const results = response.results.filter(r => r.graphic && r.graphic.layer.popupTemplate); if (results.length === 0) return; // 主 popup 展示第一条 view.openPopup({ location: event.mapPoint, features: [results[0].graphic], fetchFeatures: true }); // 其余要素用自定义容器并存展示 results.slice(1).forEach(function(r, idx) { showFloatingPopup(r.graphic, event.mapPoint, idx); }); }); }); function showFloatingPopup(graphic, mapPoint, idx) { const screenPoint = view.toScreen(mapPoint); const div = document.createElement("div"); div.className = "multi-popup"; div.style.left = (screenPoint.x + 20 + idx * 10) + "px"; div.style.top = (screenPoint.y - 40 - idx * 10) + "px"; div.innerHTML = `<strong>${graphic.attributes.name || "要素"}</strong><br/>${graphic.attributes.description || ""}`; view.container.appendChild(div); }hitTest返回的results里可能混着底图、标注等非业务图层，所以用filter只留挂了popupTemplate的。view.openPopup的fetchFeatures: true会在要素属性没加载全时去服务端补拉，避免气泡内容缺失。view.toScreen把地图坐标转屏幕像素，自定义 div 才能跟着地图动——但注意，地图平移缩放时这些 div 不会自动跟随，需要在view.watch("extent")或view.on("drag")里重算位置，map4.html里用了一个requestAnimationFrame循环做同步，这是保证多气泡不飘的关键。
4. 多气泡定位与性能：参数怎么调、什么时候会卡
4.1 屏幕坐标同步与防抖
自定义气泡最大的问题是地图交互时位置漂移。view.toScreen是同步的，但地图渲染是异步的，你在drag事件里立刻算，拿到的是上一帧的坐标。正确做法是监听view.watch("stationary")，等地图停稳再重算，或者用view.on("pointer-move")配合节流。
let rafId = null; function syncPopups() { if (rafId) cancelAnimationFrame(rafId); rafId = requestAnimationFrame(function() { document.querySelectorAll(".multi-popup").forEach(function(el) { const mp = el._mapPoint; if (!mp) return; const sp = view.toScreen(mp); el.style.left = sp.x + "px"; el.style.top = sp.y + "px"; }); }); } view.watch("extent, zoom, rotation", syncPopups);requestAnimationFrame把重排压到下一帧，避免drag高频触发导致布局抖动。view.watch监听extent、zoom、rotation三个属性，任何一个变都重算。el._mapPoint是挂载在 DOM 上的自定义属性，存原始地图坐标。这个方案在几十个气泡内流畅，上百个就要考虑用Graphics加TextSymbol走 WebGL 渲染，别用 DOM。
4.2 PopupTemplate 内容类型的选择
PopupTemplate的content支持fields、text、media、attachments、custom五种。多气泡场景下，fields最省事但样式死板；text可以塞 HTML 但要注意 XSS；custom返回 Promise，适合异步取详情。
| 内容类型 | 适用场景 | 性能 | 注意点 |
|---|---|---|---|
| fields | 结构化属性展示 | 高 | 字段名大小写敏感 |
| text | 富文本、链接 | 中 | 需自行转义 |
| media | 图片、图表 | 中 | 图片走外链有跨域风险 |
| attachments | 附件列表 | 低 | 需服务端开启附件 |
| custom | 异步、复杂布局 | 低 | 返回 Promise，别阻塞 |
map4.html里主 popup 用fields，自定义气泡用text拼 HTML，兼顾性能和灵活度。如果服务端字段多，fieldInfos里只列需要的，别["*"]全上，否则 popup 渲染时 DOM 节点暴增，移动端直接卡死。
4.3 图层加载状态与气泡时序
气泡弹不出来，十有八九是图层还没加载完你就点了。FeatureLayer的load是异步的，view.hitTest在图层visible但未loaded时可能返回空。稳妥做法是等layer.when()或监听view.whenLayerView。
view.whenLayerView(layerA).then(function(layerView) { // 此时图层视图就绪，hitTest 才可靠 console.log("图层视图就绪，可以交互"); });whenLayerView返回的layerView还带queryFeatures能力，比hitTest更可控——你可以指定geometry和distance，做「点击附近多个要素」的聚合气泡。map4.html里对点图层用了hitTest，对面图层用了queryFeatures加缓冲，因为面要素点击命中率低，需要容差。
5. 避坑排查：多气泡场景下最容易翻车的五件事
5.1 气泡弹出来是空的
现象：点击要素，popup 框架出现但标题和内容空白。原因：outFields没配或配错，hitTest拿到的graphic.attributes为空。解决：图层创建时显式写outFields: ["name", "description"]，别依赖默认值；PopupTemplate里的fieldName用浏览器开发者工具看 REST 服务返回的字段名，逐字比对。
5.2 多个气泡叠在一起分不开
现象：几个要素挨得近，气泡全堆在同一像素位置。原因：view.toScreen对相近坐标返回几乎相同的屏幕点，没有偏移策略。解决：在showFloatingPopup里按索引做idx * 10的像素偏移，或者用view.popup.open的features数组走分页，让 API 自己处理堆叠。map4.html用的是偏移加z-index递增，保证可点击。
5.3 地图一拖动气泡就飘走
现象：气泡不跟地图走，拖完地图气泡还在原地。原因：自定义 DOM 气泡没有监听extent变化，或者监听了但没做requestAnimationFrame节流，坐标算的是旧值。解决：用view.watch("extent, zoom, rotation", syncPopups)，并在syncPopups里用requestAnimationFrame包一层。另外view.toScreen在rotation非零时结果要额外处理，4.x 的旋转地图下屏幕坐标转换有已知偏差，做多气泡时尽量别开旋转。
5.4 点击事件触发两次
现象：点一下弹出两个一样的气泡。原因：view.on("click")和图层自身的popupTemplate自动开同时生效，autoOpenEnabled没关。解决：初始化MapView时设popup: { autoOpenEnabled: false }，所有开合逻辑收口到自己的click回调里。如果还重复，检查是不是在view.on外面又绑了layer.on("click")。
5.5 移动端气泡超出屏幕
现象：手机上气泡弹到屏幕外，看不到也关不掉。原因：自定义 div 的left/top没做边界检测，view.toScreen返回的坐标可能为负或超过容器宽高。解决：在syncPopups里加 clamp，Math.max(0, Math.min(sp.x, view.width - 200))，同时给气泡加max-width和overflow: auto。map4.html里对移动端单独做了view.width < 600的判断，气泡改为底部停靠。
6. 进阶：用 queryFeatures 做聚合气泡与自定义 Popup 复用
跑通基础多气泡后，真正省事的是把「点击命中」换成「范围查询」。layerView.queryFeatures可以传geometry和distance，一次拿回点击点周围 N 个要素，然后决定是合并成一个聚合气泡还是散开。聚合气泡在要素密集时体验远好于散落一堆小气泡。
view.on("click", function(event) { const buffer = { type: "circle", center: event.mapPoint, radius: 50, // 单位与视图 spatialReference 一致，这里是米 spatialReference: view.spatialReference }; view.whenLayerView(layerA).then(function(layerView) { return layerView.queryFeatures({ geometry: buffer, spatialRelationship: "intersects", returnGeometry: true, outFields: ["*"] }); }).then(function(featureSet) { if (featureSet.features.length === 0) return; if (featureSet.features.length === 1) { view.openPopup({ location: event.mapPoint, features: featureSet.features }); } else { // 聚合展示：一个气泡列出所有 const listHtml = featureSet.features.map(function(f) { return `<li>${f.attributes.name} - ${f.attributes.status}</li>`; }).join(""); view.openPopup({ location: event.mapPoint, content: `<ul>${listHtml}</ul>`, title: `附近 ${featureSet.features.length} 个要素` }); } }); });queryFeatures的distance单位取决于视图的spatialReference，Web Mercator 下是米，地理坐标系下是度，别搞混。spatialRelationship常用intersects和contains，点查询用intersects容错更好。聚合气泡的content直接传 HTML 字符串时，PopupTemplate可以省掉，view.openPopup接受content和title直接渲染。这个方案比hitTest多一次服务端或客户端查询，但换来的是「点不准也能弹」的体验。
我自己的习惯是：任何多气泡需求，先问清楚「同时可见」还是「可切换」。同时可见就上自定义 DOM 加queryFeatures聚合，可切换就用view.popup.open的features数组走分页，别硬做多个 popup 实例。从那以后我每次接 GIS 交互需求，都强制先跑一遍autoOpenEnabled: false加whenLayerView的时序验证，确认图层就绪再写气泡逻辑，省掉大量「为什么没反应」的返工。希望帮到你。
本文还有配套的精品资源，点击获取
