简介这份资源面向使用 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 charsetutf-8 / link relstylesheet hrefhttps://js.arcgis.com/4.29/esri/themes/light/main.css / script srchttps://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 idviewDiv/div script require([ esri/Map, esri/views/MapView, esri/layers/FeatureLayer, esri/PopupTemplate, esri/Graphic ], function(Map, MapView, FeatureLayer, PopupTemplate, Graphic) { // 初始化逻辑见下 }); /script /body /htmlinit.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 || 要素}/strongbr/${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 但要注意 XSScustom返回 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里加 clampMath.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单位取决于视图的spatialReferenceWeb Mercator 下是米地理坐标系下是度别搞混。spatialRelationship常用intersects和contains点查询用intersects容错更好。聚合气泡的content直接传 HTML 字符串时PopupTemplate可以省掉view.openPopup接受content和title直接渲染。这个方案比hitTest多一次服务端或客户端查询但换来的是「点不准也能弹」的体验。我自己的习惯是任何多气泡需求先问清楚「同时可见」还是「可切换」。同时可见就上自定义 DOM 加queryFeatures聚合可切换就用view.popup.open的features数组走分页别硬做多个 popup 实例。从那以后我每次接 GIS 交互需求都强制先跑一遍autoOpenEnabled: false加whenLayerView的时序验证确认图层就绪再写气泡逻辑省掉大量「为什么没反应」的返工。希望帮到你。本文还有配套的精品资源点击获取