Angular Google Maps 高级标记实战MapAdvancedMarker 组件完整指南【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/componentsMapAdvancedMarker是angular/google-maps提供的 Angular 指令它封装了 Google Maps JavaScript API 中的google.maps.marker.AdvancedMarkerElement类让你能够在GoogleMap组件的内部以声明式的方式渲染高级标记Advanced Marker。相比传统MapMarker高级标记支持自定义 DOM 内容、海拔高度vector map、拖拽与无障碍交互等能力。读完本文你将掌握 MapAdvancedMarker 的全部输入输出、初始化与更新机制、事件监听方式以及如何与google-map、信息窗口和聚类器协同工作直接用于生产项目。前置条件mapId 是硬性要求使用map-advanced-marker之前必须满足一个关键前提父级google-map必须配置一个有效的mapId。这一点在官方 README 中被明确标注Note:Use ofmap-advanced-markerrequires agoogle-mapwith a validmapId.原因在于AdvancedMarkerElement依赖 Google 的矢量地图渲染管线而矢量地图必须通过 Map ID 启用。从源码看GoogleMap组件在合并地图选项时会透传mapId见 google-map.ts 的_combineOptions方法其中mapId: this.mapId || options.mapId只有地图实例携带了 mapId高级标记才能正确渲染。如果你的地图没有 mapId请先到 Google Cloud Console 创建 Map ID 并配置到google-map的mapId输入上。安装与加载 Google Maps API在集成MapAdvancedMarker之前需要先完成基础环境搭建详见 google-maps/README.md安装依赖在 Angular 项目中执行ng add angular/google-maps包名见 package.json依赖types/google.maps提供类型支持。获取 API Key按照 Google Maps Platform 官方流程申请 API Key。加载 API推荐使用动态库导入Dynamic Library Import方式在应用的index.html中引入加载脚本并替换YOUR_API_KEY_GOES_HERE。组件内部会在渲染时按需通过importLibrary自动加载所需的 JavaScript 库见下文“初始化流程”。基础用法官方示例详解README 给出了一个完整可运行的示例——点击地图添加高级标记。先看组件类google-map-demo.component.tsimport {Component} from angular/core; import {GoogleMap, MapAdvancedMarker} from angular/google-maps; Component({ selector: google-map-demo, templateUrl: google-map-demo.html, imports: [GoogleMap, MapAdvancedMarker], }) export class GoogleMapDemo { center: google.maps.LatLngLiteral {lat: 24, lng: 12}; zoom 4; advancedMarkerOptions: google.maps.marker.AdvancedMarkerElementOptions {gmpDraggable: false}; advancedMarkerPositions: google.maps.LatLngLiteral[] []; addAdvancedMarker(event: google.maps.MapMouseEvent) { this.advancedMarkerPositions.push(event.latLng.toJSON()); } }对应的模板google-map-demo.component.htmlgoogle-map mapIdyourMapId height400px width750px [center]center [zoom]zoom (mapClick)addAdvancedMarker($event) for (position of advancedMarkerPositions; track position) { map-advanced-marker [position]position [options]advancedMarkerOptions / } /google-map关键点拆解MapAdvancedMarker是内容子组件content child必须嵌套在google-map内部才能渲染到地图上见 README。使用 Angular 17 的新控制流语法for循环渲染标记列表并用track position优化变更检测。通过mapClick事件获取点击位置event.latLngtoJSON()转换为LatLngLiteral后存入数组即可实现“点击地图加标记”的交互。组件类中使用的是独立组件standalone写法直接在imports中引入GoogleMap和MapAdvancedMarker若使用 NgModule 方式则导入GoogleMapsModule两者均已在 public-api.ts 中导出。输入Input详解MapAdvancedMarker提供了 7 个输入其实现位于 map-advanced-marker.ts输入类型说明positionLatLngLiteral \| LatLng \| LatLngAltitude \| LatLngAltitudeLiteral标记位置。注意带海拔altitude的标记仅在矢量地图上受支持。标记可在构造时不带位置但在提供位置之前不会显示titlestring悬停文本提供后会同时作为无障碍文本例如供屏幕阅读器使用写入AdvancedMarkerElementcontentNode \| PinElement \| null标记视觉内容对应的 DOM 元素。注意AdvancedMarkerElement不会克隆传入的 DOM 元素——一旦把某个 DOM 元素传给一个高级标记再把它传给另一个标记会“移动”该元素并导致前一个标记看起来是空的gmpDraggableboolean是否允许拖拽。带海拔的标记不可拖拽gmpClickableboolean是否可点击。为true时触发gmp-click事件并支持键盘方向键导航等无障碍交互zIndexnumber标记的层级值越大显示越靠上optionsAdvancedMarkerElementOptions一次性传入的完整构造选项对象用于覆盖上述独立输入之外的其余配置输入与 options 的优先级规则这里存在一个易踩坑的规则由源码的_combineOptions方法定义map-advanced-marker.tsprivate _combineOptions(): google.maps.marker.AdvancedMarkerElementOptions { const options this._options || DEFAULT_MARKER_OPTIONS; return { ...options, title: this._title || options.title, position: this._position || options.position, content: this._content || options.content, zIndex: this._zIndex ?? options.zIndex, gmpDraggable: this._draggable ?? options.gmpDraggable, gmpClickable: this._clickable ?? options.gmpClickable, map: this._googleMap.googleMap, }; }即独立输入如[position]优先于options对象中的同名配置独立输入未设置时才回退到options中的值。其中title、position、content使用||空值回退而zIndex、gmpDraggable、gmpClickable使用??仅null/undefined回退false和0会被保留。默认标记选项源码中还定义了一个默认选项常量DEFAULT_MARKER_OPTIONSmap-advanced-marker.ts未显式设置任何选项时标记会出现在 Google 总部Googleplex位置export const DEFAULT_MARKER_OPTIONS { position: {lat: 37.221995, lng: -122.184092}, };输出事件Output详解MapAdvancedMarker通过MapEventManager的“懒监听”lazy emitter机制暴露事件——只有当你订阅了某个事件时底层监听器才会真正注册未订阅的事件不会产生性能开销。输出事件类型说明mapClickMapMouseEvent单击标记时触发mapDblclickMouseEvent原生事件双击标记时触发mapMouseoutMouseEvent原生事件鼠标移出标记时触发mapMouseoverMapMouseEvent原生事件鼠标移过标记时触发mapMouseupMouseEvent原生事件在标记上松开鼠标按键时触发mapRightclickMouseEvent原生事件右键点击标记时触发mapDragMapMouseEvent拖拽过程中反复触发mapDragendMapMouseEvent拖拽结束时触发mapDragstartMapMouseEvent开始拖拽时触发gmpClickAdvancedMarkerClickEvent可点击标记gmpClickable为true被点击时触发用于无障碍交互场景markerInitializedEventEmitterAdvancedMarkerElement标记初始化完成后触发携带底层原生标记对象事件监听代码示例见 map-advanced-marker.tsOutput() readonly mapClick: Observablegoogle.maps.MapMouseEvent this._eventManager.getLazyEmittergoogle.maps.MapMouseEvent(click); Output() readonly mapDblclick: ObservableMouseEvent this._eventManager.getLazyEmitterMouseEvent(dblclick, native);注意native参数它表示该事件通过原生addEventListener注册适用于dblclick、mouseout、mouseover、mouseup、auxclick等标记元素上的 DOM 事件而click、drag系列与gmp-click则走addListener。这一区别在测试文件中也有明确验证见 map-advanced-marker.spec.ts。底层实现初始化、更新与销毁初始化流程ngOnInitMapAdvancedMarker在ngOnInit中完成初始化map-advanced-marker.ts流程如下非浏览器环境SSR下直接返回避免服务端渲染时操作 DOM若google.maps.marker.AdvancedMarkerElement已同步可用且父地图已就绪立即初始化否则在 Angular Zone 之外等待两个 Promise 完成父GoogleMap的_resolveMap()与google.maps.importLibrary(marker)然后使用动态加载到的MarkerLibrary.AdvancedMarkerElement构造函数进行初始化。这种设计让组件既兼容传统同步加载脚本也支持 Google 推荐的动态库导入方式。创建与事件挂接_initialize_initialize方法map-advanced-marker.ts在runOutsideAngular中创建底层标记对象目的是避免 Google Maps 内部事件触发无谓的 Angular 变更检测随后将标记挂到地图advancedMarker.map map把事件目标交给MapEventManager只有你订阅的事件会被带回 Angular Zone最后通过markerInitialized.next(...)通知外部。初始化完成后可通过公开属性advancedMarker直接访问底层的google.maps.marker.AdvancedMarkerElement原生对象。响应式更新ngOnChanges当任一输入发生变化时ngOnChanges会精准同步对应属性到底层标记对象map-advanced-marker.tstitle、gmpDraggable、gmpClickable、content、position、zIndex各自独立更新不会触发重建。销毁清理ngOnDestroyngOnDestroy中会完成markerInitialized、事件管理器并将标记从地图上卸载advancedMarker.map null确保无内存泄漏map-advanced-marker.ts。与周边模块的协作信息窗口与聚类器MapAdvancedMarker并非孤立存在它实现了两个关键接口供信息窗口与聚类器复用MapAnchorPointmap-anchor-point.ts定义getAnchor()方法返回MVCObject | AdvancedMarkerElement使标记可以充当MapInfoWindow的锚点信息窗口弹窗定位依据。MarkerDirective/MAP_MARKERmarker-utilities.tsMapAdvancedMarker在providers中以useExisting方式将自己注册为MAP_MARKER注入令牌map-advanced-marker.ts聚类器组件可通过该令牌统一获取各种标记指令并调用其_resolveMarker()从而同时兼容传统MapMarker与MapAdvancedMarker。此外组件还暴露了exportAs: mapAdvancedMarker允许在模板中通过模板引用变量如#markermapAdvancedMarker访问组件实例。测试验证与行为保证map-advanced-marker.spec.ts 使用fake-google-map-utils构造假的 Google Maps 对象进行单元测试验证了以下关键行为可作为你使用时的行为参照初始化参数正确性构造标记时传入合并后的完整选项对象含默认选项与map独立输入生效设置全部 7 个输入后构造参数与预期一致options 输入生效仅传options时构造参数为{...options, map: mapSpy}输入优先于 options同时设置独立输入与options时独立输入的值胜出如position、title、gmpDraggable、gmpClickable、zIndex事件懒监听模板中未绑定的事件如drag、gmp-click不会注册底层监听器在初始化后订阅mapDrag监听器会即时补注册——这就是“懒监听”机制的运行时验证。常见使用场景与注意事项小结推荐场景需要自定义标记外观传入任意Node或PinElement作为content需要拖拽标记gmpDraggable: true需要键盘可访问、可聚焦的交互标记gmpClickable: true在矢量地图上需要海拔定位或更精细的zIndex控制。务必牢记的坑没有mapId就无法渲染——这是使用map-advanced-marker的第一前提content不会被克隆——同一个 DOM 元素不能复用于多个标记否则标记之间会“抢”元素带海拔的标记不支持拖拽且仅矢量地图支持独立输入优先于options——混用时请明确你的优先级预期避免出现“options 明明设置了 position 却不生效”的困惑事件采用懒监听模式未订阅的事件不会产生额外监听器开销可放心按需订阅。至此你已掌握MapAdvancedMarker的完整用法从 mapId 前置条件、安装加载到全部输入输出、底层初始化与更新机制以及与信息窗口、聚类器的协作方式足以在实际的 Angular Google Maps 项目中直接落地使用。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Angular Google Maps 高级标记实战：MapAdvancedMarker 组件完整指南
Angular Google Maps 高级标记实战MapAdvancedMarker 组件完整指南【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/componentsMapAdvancedMarker是angular/google-maps提供的 Angular 指令它封装了 Google Maps JavaScript API 中的google.maps.marker.AdvancedMarkerElement类让你能够在GoogleMap组件的内部以声明式的方式渲染高级标记Advanced Marker。相比传统MapMarker高级标记支持自定义 DOM 内容、海拔高度vector map、拖拽与无障碍交互等能力。读完本文你将掌握 MapAdvancedMarker 的全部输入输出、初始化与更新机制、事件监听方式以及如何与google-map、信息窗口和聚类器协同工作直接用于生产项目。前置条件mapId 是硬性要求使用map-advanced-marker之前必须满足一个关键前提父级google-map必须配置一个有效的mapId。这一点在官方 README 中被明确标注Note:Use ofmap-advanced-markerrequires agoogle-mapwith a validmapId.原因在于AdvancedMarkerElement依赖 Google 的矢量地图渲染管线而矢量地图必须通过 Map ID 启用。从源码看GoogleMap组件在合并地图选项时会透传mapId见 google-map.ts 的_combineOptions方法其中mapId: this.mapId || options.mapId只有地图实例携带了 mapId高级标记才能正确渲染。如果你的地图没有 mapId请先到 Google Cloud Console 创建 Map ID 并配置到google-map的mapId输入上。安装与加载 Google Maps API在集成MapAdvancedMarker之前需要先完成基础环境搭建详见 google-maps/README.md安装依赖在 Angular 项目中执行ng add angular/google-maps包名见 package.json依赖types/google.maps提供类型支持。获取 API Key按照 Google Maps Platform 官方流程申请 API Key。加载 API推荐使用动态库导入Dynamic Library Import方式在应用的index.html中引入加载脚本并替换YOUR_API_KEY_GOES_HERE。组件内部会在渲染时按需通过importLibrary自动加载所需的 JavaScript 库见下文“初始化流程”。基础用法官方示例详解README 给出了一个完整可运行的示例——点击地图添加高级标记。先看组件类google-map-demo.component.tsimport {Component} from angular/core; import {GoogleMap, MapAdvancedMarker} from angular/google-maps; Component({ selector: google-map-demo, templateUrl: google-map-demo.html, imports: [GoogleMap, MapAdvancedMarker], }) export class GoogleMapDemo { center: google.maps.LatLngLiteral {lat: 24, lng: 12}; zoom 4; advancedMarkerOptions: google.maps.marker.AdvancedMarkerElementOptions {gmpDraggable: false}; advancedMarkerPositions: google.maps.LatLngLiteral[] []; addAdvancedMarker(event: google.maps.MapMouseEvent) { this.advancedMarkerPositions.push(event.latLng.toJSON()); } }对应的模板google-map-demo.component.htmlgoogle-map mapIdyourMapId height400px width750px [center]center [zoom]zoom (mapClick)addAdvancedMarker($event) for (position of advancedMarkerPositions; track position) { map-advanced-marker [position]position [options]advancedMarkerOptions / } /google-map关键点拆解MapAdvancedMarker是内容子组件content child必须嵌套在google-map内部才能渲染到地图上见 README。使用 Angular 17 的新控制流语法for循环渲染标记列表并用track position优化变更检测。通过mapClick事件获取点击位置event.latLngtoJSON()转换为LatLngLiteral后存入数组即可实现“点击地图加标记”的交互。组件类中使用的是独立组件standalone写法直接在imports中引入GoogleMap和MapAdvancedMarker若使用 NgModule 方式则导入GoogleMapsModule两者均已在 public-api.ts 中导出。输入Input详解MapAdvancedMarker提供了 7 个输入其实现位于 map-advanced-marker.ts输入类型说明positionLatLngLiteral \| LatLng \| LatLngAltitude \| LatLngAltitudeLiteral标记位置。注意带海拔altitude的标记仅在矢量地图上受支持。标记可在构造时不带位置但在提供位置之前不会显示titlestring悬停文本提供后会同时作为无障碍文本例如供屏幕阅读器使用写入AdvancedMarkerElementcontentNode \| PinElement \| null标记视觉内容对应的 DOM 元素。注意AdvancedMarkerElement不会克隆传入的 DOM 元素——一旦把某个 DOM 元素传给一个高级标记再把它传给另一个标记会“移动”该元素并导致前一个标记看起来是空的gmpDraggableboolean是否允许拖拽。带海拔的标记不可拖拽gmpClickableboolean是否可点击。为true时触发gmp-click事件并支持键盘方向键导航等无障碍交互zIndexnumber标记的层级值越大显示越靠上optionsAdvancedMarkerElementOptions一次性传入的完整构造选项对象用于覆盖上述独立输入之外的其余配置输入与 options 的优先级规则这里存在一个易踩坑的规则由源码的_combineOptions方法定义map-advanced-marker.tsprivate _combineOptions(): google.maps.marker.AdvancedMarkerElementOptions { const options this._options || DEFAULT_MARKER_OPTIONS; return { ...options, title: this._title || options.title, position: this._position || options.position, content: this._content || options.content, zIndex: this._zIndex ?? options.zIndex, gmpDraggable: this._draggable ?? options.gmpDraggable, gmpClickable: this._clickable ?? options.gmpClickable, map: this._googleMap.googleMap, }; }即独立输入如[position]优先于options对象中的同名配置独立输入未设置时才回退到options中的值。其中title、position、content使用||空值回退而zIndex、gmpDraggable、gmpClickable使用??仅null/undefined回退false和0会被保留。默认标记选项源码中还定义了一个默认选项常量DEFAULT_MARKER_OPTIONSmap-advanced-marker.ts未显式设置任何选项时标记会出现在 Google 总部Googleplex位置export const DEFAULT_MARKER_OPTIONS { position: {lat: 37.221995, lng: -122.184092}, };输出事件Output详解MapAdvancedMarker通过MapEventManager的“懒监听”lazy emitter机制暴露事件——只有当你订阅了某个事件时底层监听器才会真正注册未订阅的事件不会产生性能开销。输出事件类型说明mapClickMapMouseEvent单击标记时触发mapDblclickMouseEvent原生事件双击标记时触发mapMouseoutMouseEvent原生事件鼠标移出标记时触发mapMouseoverMapMouseEvent原生事件鼠标移过标记时触发mapMouseupMouseEvent原生事件在标记上松开鼠标按键时触发mapRightclickMouseEvent原生事件右键点击标记时触发mapDragMapMouseEvent拖拽过程中反复触发mapDragendMapMouseEvent拖拽结束时触发mapDragstartMapMouseEvent开始拖拽时触发gmpClickAdvancedMarkerClickEvent可点击标记gmpClickable为true被点击时触发用于无障碍交互场景markerInitializedEventEmitterAdvancedMarkerElement标记初始化完成后触发携带底层原生标记对象事件监听代码示例见 map-advanced-marker.tsOutput() readonly mapClick: Observablegoogle.maps.MapMouseEvent this._eventManager.getLazyEmittergoogle.maps.MapMouseEvent(click); Output() readonly mapDblclick: ObservableMouseEvent this._eventManager.getLazyEmitterMouseEvent(dblclick, native);注意native参数它表示该事件通过原生addEventListener注册适用于dblclick、mouseout、mouseover、mouseup、auxclick等标记元素上的 DOM 事件而click、drag系列与gmp-click则走addListener。这一区别在测试文件中也有明确验证见 map-advanced-marker.spec.ts。底层实现初始化、更新与销毁初始化流程ngOnInitMapAdvancedMarker在ngOnInit中完成初始化map-advanced-marker.ts流程如下非浏览器环境SSR下直接返回避免服务端渲染时操作 DOM若google.maps.marker.AdvancedMarkerElement已同步可用且父地图已就绪立即初始化否则在 Angular Zone 之外等待两个 Promise 完成父GoogleMap的_resolveMap()与google.maps.importLibrary(marker)然后使用动态加载到的MarkerLibrary.AdvancedMarkerElement构造函数进行初始化。这种设计让组件既兼容传统同步加载脚本也支持 Google 推荐的动态库导入方式。创建与事件挂接_initialize_initialize方法map-advanced-marker.ts在runOutsideAngular中创建底层标记对象目的是避免 Google Maps 内部事件触发无谓的 Angular 变更检测随后将标记挂到地图advancedMarker.map map把事件目标交给MapEventManager只有你订阅的事件会被带回 Angular Zone最后通过markerInitialized.next(...)通知外部。初始化完成后可通过公开属性advancedMarker直接访问底层的google.maps.marker.AdvancedMarkerElement原生对象。响应式更新ngOnChanges当任一输入发生变化时ngOnChanges会精准同步对应属性到底层标记对象map-advanced-marker.tstitle、gmpDraggable、gmpClickable、content、position、zIndex各自独立更新不会触发重建。销毁清理ngOnDestroyngOnDestroy中会完成markerInitialized、事件管理器并将标记从地图上卸载advancedMarker.map null确保无内存泄漏map-advanced-marker.ts。与周边模块的协作信息窗口与聚类器MapAdvancedMarker并非孤立存在它实现了两个关键接口供信息窗口与聚类器复用MapAnchorPointmap-anchor-point.ts定义getAnchor()方法返回MVCObject | AdvancedMarkerElement使标记可以充当MapInfoWindow的锚点信息窗口弹窗定位依据。MarkerDirective/MAP_MARKERmarker-utilities.tsMapAdvancedMarker在providers中以useExisting方式将自己注册为MAP_MARKER注入令牌map-advanced-marker.ts聚类器组件可通过该令牌统一获取各种标记指令并调用其_resolveMarker()从而同时兼容传统MapMarker与MapAdvancedMarker。此外组件还暴露了exportAs: mapAdvancedMarker允许在模板中通过模板引用变量如#markermapAdvancedMarker访问组件实例。测试验证与行为保证map-advanced-marker.spec.ts 使用fake-google-map-utils构造假的 Google Maps 对象进行单元测试验证了以下关键行为可作为你使用时的行为参照初始化参数正确性构造标记时传入合并后的完整选项对象含默认选项与map独立输入生效设置全部 7 个输入后构造参数与预期一致options 输入生效仅传options时构造参数为{...options, map: mapSpy}输入优先于 options同时设置独立输入与options时独立输入的值胜出如position、title、gmpDraggable、gmpClickable、zIndex事件懒监听模板中未绑定的事件如drag、gmp-click不会注册底层监听器在初始化后订阅mapDrag监听器会即时补注册——这就是“懒监听”机制的运行时验证。常见使用场景与注意事项小结推荐场景需要自定义标记外观传入任意Node或PinElement作为content需要拖拽标记gmpDraggable: true需要键盘可访问、可聚焦的交互标记gmpClickable: true在矢量地图上需要海拔定位或更精细的zIndex控制。务必牢记的坑没有mapId就无法渲染——这是使用map-advanced-marker的第一前提content不会被克隆——同一个 DOM 元素不能复用于多个标记否则标记之间会“抢”元素带海拔的标记不支持拖拽且仅矢量地图支持独立输入优先于options——混用时请明确你的优先级预期避免出现“options 明明设置了 position 却不生效”的困惑事件采用懒监听模式未订阅的事件不会产生额外监听器开销可放心按需订阅。至此你已掌握MapAdvancedMarker的完整用法从 mapId 前置条件、安装加载到全部输入输出、底层初始化与更新机制以及与信息窗口、聚类器的协作方式足以在实际的 Angular Google Maps 项目中直接落地使用。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
