AdvancedMarkerElement在各类模态框中无法显示的技术问题

问题现象 #

• 浏览器控制台无任何错误输出
• 使用新版AdvancedMarkerElement创建的标记，在模态框外部可正常显示，但在模态框内不显示
• 使用已弃用的Marker()方法创建标记时，模态框内能够正常工作

代码复现 #

let markerLibrary: google.maps.MarkerLibrary | null = null
let placesLibrary: google.maps.PlacesLibrary | null = null
let mapLibrary: google.maps.MapsLibrary | null = null

const marker = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;
markerLibrary = marker 

const { Map } = await google.maps.importLibrary('maps') as google.maps.MapsLibrary
const center = new google.maps.LatLng(43.2955357,-2.8849016)
mapInstance.value = new Map(elMap,{
  zoom: 16,
  mapId: 'DEMO_MAP_ID',
  center,
  disableDefaultUI: true
})

// 此标记在模态框内不显示
const marker = new markerLibrary!.AdvancedMarkerElement({
  position: center,
  map: mapInstance.value,
  // zIndex: 99999999,
})

/* 
// 此方法已弃用，但在模态框内正常工作
new markerLibrary.Marker({
  map: mapInstance.value,
  position: center
})  */

解决思路及方案 #

AdvancedMarkerElement基于Web Components实现，与旧版Marker的DOM渲染机制不同，模态框的堆叠上下文或样式限制可能导致其无法正常显示，可尝试以下方案：

1. 显式设置标记的z-index
   取消代码中zIndex的注释，设置一个高于模态框的z-index值（例如zIndex: 1060，若使用Bootstrap模态框，其默认z-index为1050）：

const marker = new markerLibrary!.AdvancedMarkerElement({
  position: center,
  map: mapInstance.value,
  zIndex: 1060,
})

2. 检查模态框的样式设置

• 确保模态框内容容器的overflow属性不是hidden，避免标记被裁剪
• 确认地图所在容器的position属性为relative或absolute，保证标记的定位上下文正确

3. 延迟初始化地图和标记
   若模态框是动态显示的，可在模态框完全显示后（例如监听框架对应的显示完成事件）再初始化地图和标记，确保DOM渲染完成后再加载地图组件。

内容的提问来源于stack exchange，提问作者Carlos Sanchez Acero