仪表盘嵌地图必须用 JavaScript API 实现交互，iframe 因上下文隔离、样式失效、初始化失败等问题不可用；需确保容器有显式高度、DOM 就绪后初始化、密钥合规，并通过事件绑定与数据联动。
仪表盘里嵌地图，不是加个 <iframe></iframe> 就完事——交互功能（比如点击标记查数据、拖拽刷新表格、缩放联动图表）必须靠 JavaScript API 实现，否则只是张静态图。
为什么 iframe 在仪表盘里基本不可用
仪表盘页面通常动态渲染、DOM 反复更新，而 <iframe></iframe> 是独立上下文：无法监听地图事件、不能从外部 JS 控制视角、标记点无法绑定表格行数据、缩放后也不能触发仪表盘重绘。更关键的是，多数仪表盘框架（如 Grafana 嵌入页、Vue/React 管理的 dashboard）会把 iframe 当作黑盒，样式隔离导致高度塌陷、响应式失效。
常见错误现象：<td><div id="map"></div></td> 里地图空白，控制台无报错——本质是 AMap.Map 或 BMap.Map 初始化时读到容器宽高为 0px，直接跳过渲染。
- 表格单元格（
<td>）默认不设像素尺寸，父级又没显式 height，地图 SDK 拒绝启动 <li>仪表盘初始化顺序混乱：地图脚本执行时 DOM 还没挂载完成，<code>document.getElementById('map')返回 null - 使用百度地图 v3.0 但页面走 HTTP 协议，地图白屏且控制台静默失败（不报 CORS，只加载空白 tile）
- 容器
<div id="map"> 的父元素（至少向上两层）必须有明确 CSS <code>height，推荐写死像素值或min-height，避免用100%（父级若无高度，百分比无效） - 地图初始化代码必须放在 DOM 就绪后执行：
AMap.ready(() => { new AMap.Map(...) })或 Vue 的mounted()/ React 的useEffect(() => { ... }, []) - 密钥有效且域名已白名单：高德 Key 需在「Web 端」类型下添加当前仪表盘域名（如
dashboard.example.com），百度 AK 要勾选「JavaScript API」并确认未过期
AMap.Map 或 BMap.Map 初始化前必须确认的三件事
高德或百度地图 SDK 对容器环境极其敏感，漏掉任一条件都会白屏。
立即学习“前端免费学习笔记（深入）”；
示例（高德）：
AMap.ready(() => {
const map = new AMap.Map('map', {
zoom: 12,
center: [116.404, 39.915],
// 关键：关闭默认 UI，避免和仪表盘控件冲突
features: ['bg', 'road', 'building'],
pitch: 0,
viewMode: '2D'
});
});
让地图和仪表盘数据真正联动的关键操作
单纯显示地图没意义，重点是让地图上的交互能驱动表格、图表更新，反之亦然。
- 标记点（
AMap.Marker）的content不要用纯 HTML 字符串，改用createMarker(dataRow)函数动态生成，确保每个标记绑定对应表格行的完整数据对象 - 监听
marker.on('click', e => {...})后，不要只弹 alert，而是调用仪表盘的数据筛选函数，比如filterTableByLocation(e.target.getExtData().id) - 如果仪表盘支持地理围栏筛选（如“显示半径 5km 内门店”），用
AMap.GeometryUtil.distance计算坐标距离，别手写 Haversine 公式 - 避免在地图上叠加大量标记：超过 100 个点务必启用聚合（
AMap.MarkerClusterer），否则卡顿明显
移动端仪表盘地图适配最容易被忽略的点
桌面端跑通的地图，放到手机上常出现缩放失灵、双指拖拽变滚动页面、标记图标糊成一团——这不是代码问题，是 CSS 和事件穿透没处理。
- 给地图容器加
style="touch-action: none;"，否则 iOS Safari 会劫持双指手势去缩放整个页面 - 禁用地图容器父级的
user-select: none（某些仪表盘框架默认加），否则长按标记无法触发 click - 标记图标用 SVG 或 2x PNG，CSS 中设置
width: 24px; height: 24px; image-rendering: -webkit-optimize-contrast;防模糊 - 不要依赖
window.innerWidth动态重设地图尺寸，改用map.resize()并监听window.addEventListener('resize', () => map.resize())
复杂点在于：地图 SDK 自身不感知仪表盘状态变更。比如用户切 Tab 页再回来，地图可能已销毁或纹理丢失，这时得监听页面可见性（document.visibilityState）并在 visibilitychange 时手动 map.refresh() 或重建实例——这点文档几乎不提，但生产环境必踩。
