Maps JavaScript API 快速参考

Maps JavaScript API 是一种客户端 Web API,用于在网页上创建 2D 和 3D 地图,添加标记、自定义图形、动画和交互式数据层,以及使用地点库构建位置功能。

Maps JavaScript API:关键信息

  • 产品:Maps JavaScript API
  • 别名:Maps JS API、Maps JS API v3
  • 类别:Google 地图
  • 平台:JavaScript(浏览器)
  • 运行位置:客户端(应用或浏览器代码)
  • 发布阶段:GA
  • 生命周期:有效
  • 概览:Maps JavaScript API 概览
  • 适用区域:全球。功能覆盖范围(例如 3D 地图、路况、路线和边界样式设置)因国家/地区而异;欧洲经济区服务条款适用于欧洲经济区账单邮寄地址。(覆盖范围详情)

Maps JavaScript API:何时使用

在以下情况下使用 Maps JavaScript API:

  • 您需要在网页上显示一个包含自定义标记、图形或数据层的交互式 2D 或 3D 地图。
  • 您需要使用高级标记和多段线,根据自己的数据流显示实时资产位置和行驶路线。
  • 您需要在浏览器中绘制地理围栏(圆形、多边形),并测试坐标是否落在这些围栏内。
  • 您需要在 Web 应用中通过 Places 库使用客户端地点搜索、自动补全或地点详情功能。

在以下情况下,请勿使用 Maps JavaScript API:

  • 您需要嵌入营业地点地图或路线链接,而无需编写自定义 JavaScript。请改用 Maps Embed API。
  • 您只需要一个链接,即可打开 Google 地图并显示特定地点、搜索结果或路线。请改用地图网址。
  • 您需要将拼车或预约配送车队跟踪功能与移动端 Driver SDK 和后端 JWT 身份验证集成。请改用 Fleet Engine Service。

Maps JavaScript API:设置

官方 Maps JavaScript API 软件包:

  • npm:@googlemaps/js-api-loader
  • npm:@types/google.maps
  • npm:@googlemaps/markerclusterer

Maps JavaScript API:常见错误

  • 问题:如果 API 密钥或结算信息配置有误,系统不会显示错误,而是会显示暗色地图或带有“仅用于开发目的”水印的负片效果街景图像。解决方法:在云项目中启用结算功能,在每个请求中添加有效的 API 密钥,并在浏览器控制台中查看具体的错误代码。请参阅 /maps/documentation/javascript/error-messages。
  • 问题:在未启用旧版 API 的新项目中,PlacesService、DirectionsService 和 DistanceMatrixService 等旧版服务会抛出 LegacyApiNotActivatedMapError。修复方法:使用由 Places API(新版)和 Routes API 提供支持的新等效项(Place 类、Route 类、RouteMatrix 类)。请参阅 /maps/legacy#LegacyApiNotActivatedMapError。
  • 问题:从 v3.65 开始,卫星地图和混合地图不再切换到 45° 角航拍图像,并且 map.setTilt(45) 不起作用。解决方法:使用 3D 地图,而不是 45° 角航拍图像。请参阅 /maps/deprecations。
  • 问题:高级标记需要地图 ID;创建地图时若未提供地图 ID,则无法使用 AdvancedMarkerElement。解决方法:在 Cloud 控制台中创建地图 ID(或使用 DEMO_MAP_ID 进行测试),并在地图上设置 mapId。请参阅 /maps/documentation/javascript/advanced-markers/start。

Maps JavaScript API:旧版和已弃用的功能

  • Directions Service (google.maps.DirectionsService):自 2025 年 3 月 1 日起为旧版。替换为:Route 类。症状:在未启用旧版 Directions API 的项目上出现 LegacyApiNotActivatedMapError。请参阅迁移指南。
  • 距离矩阵服务 (google.maps.DistanceMatrixService):自 2025 年 3 月 1 日起弃用。替换:RouteMatrix 类。症状:在未启用旧版 Distance Matrix API 的项目上出现 LegacyApiNotActivatedMapError。请参阅迁移指南。
  • Places Service (google.maps.places.PlacesService):自 2025 年 3 月 1 日起成为旧版。替代项:Place 类(Places API [新版])。症状:在未启用旧版 Places API 的项目上出现 LegacyApiNotActivatedMapError。请参阅迁移指南。
  • google.maps.Marker:自 2024 年 2 月 22 日起弃用。替换:google.maps.marker.AdvancedMarkerElement。具体情况:仍可正常运行,且未计划停用;现有 bug 不会修复。请参阅迁移指南。
  • KmlLayer:自 2026 年 4 月 30 日起弃用。替代方案:数据集的数据驱动型样式,或使用数据层的第三方 KML 解析器。症状:KmlLayer 在 3.66 版及更高版本中不可用;支持该功能的最后一个版本 3.65 版将于 2027 年 5 月停用。请参阅迁移指南。
  • 热图图层(可视化库):自 2026 年 5 月 20 日起停用。替代方案:deck.gl HeatmapLayer 等第三方库。症状:自 2026 年 5 月起无法使用。请参阅迁移指南。
  • 绘图库:自 2026 年 6 月 4 日起停用。替代方案:Terra Draw。症状:自 2026 年 5 月起无法使用。请参阅迁移指南。
  • 45° 角航拍图像:自 2026 年 5 月 20 日起停用。替代方案:3D 地图。症状:map.setTilt(45) 无效;卫星视图保持俯视视角。请参阅迁移指南。
  • google.maps.event.addDomListener() 和 addDomListenerOnce():自 2022 年 4 月 7 日起已弃用。替代方案:标准 DOM addEventListener()。
  • 地点自动补全服务中的 bounds、location 和 radius 选项:自 2023 年 5 月 18 日起已弃用。替换为:locationBias 和 locationRestriction。
  • Places UI Kit 中的 gmp-place-content-config (PlaceContentConfigElement):已废弃。替代方案:直接向地点详情元素或在地点搜索配置中添加内容元素。
  • Local Context Library:已停用。替代方案:Places Library。

Maps JavaScript API 的用途

请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。

Maps JavaScript API:地址验证

Maps JavaScript API:边界的数据驱动型样式

Maps JavaScript API:数据集的数据驱动型样式

Maps JavaScript API:数据集

  • 向地图添加 KML 图层。注意:在 Maps JavaScript API 中,KmlLayer 已弃用(最后支持的版本为 v3.65,将于 2027 年 5 月停用);请迁移到边界或数据集的数据驱动型样式,或在数据层上加载 GeoJSON。Android 和 iOS 仍通过 Maps SDK 实用程序库支持 KML 图层。
  • 向地图添加 GeoRSS 图层。注意:Maps JavaScript API 中已弃用(KmlLayer 在 v3.65 中最后一次受支持,将于 2027 年 5 月停用);请将 GeoRSS Feed 转换为 GeoJSON,并使用 map.data.addGeoJson() 将其加载到数据层。
  • 向地图添加 GeoJSON 数据。

Maps JavaScript API:路线和路线规划

Maps JavaScript API:海拔

Maps JavaScript API:Fleet Engine

Maps JavaScript API:地理编码

Maps JavaScript API:地图

Maps JavaScript API:地图注释

Maps JavaScript API:地图样式设置

Maps JavaScript API:其他

Maps JavaScript API:仿真 3D 地图

Maps JavaScript API:地点

Maps JavaScript API:Places UI Kit

  • 向网页或移动应用添加一个界面元素,用于显示 AI 赋能的特定地点摘要和评价。注意:仅在网页上受支持(Maps JavaScript API Places UI Kit);移动版 Places UI Kit 不包含 AI 摘要元素。欧洲经济区 (EEA) 合规要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请使用 Maps JavaScript API 中的客户端 Places UI Kit 组件,而不是从后端服务器调用 Places API Web 服务。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 对地点数据界面元素应用 CSS 样式。注意:CSS 自定义属性适用于 Maps JavaScript API Places UI Kit 元素;Places SDK for Android 和 Places SDK for iOS 则使用主题和样式属性,以编程方式设置 Place UI Kit 视图的样式。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 使用界面元素自定义工具自定义地点数据界面元素的样式和配置。注意:欧洲经济区 (EEA) 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页或移动应用添加一个界面元素,用于显示特定地点的相关信息。注意:欧洲经济区 (EEA) 合规要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页中添加一个界面元素,用于根据查询字符串显示地点列表。注意:网页(Maps JavaScript API)和移动应用(Places SDK for Android 和 Places SDK for iOS)均支持此功能。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页添加一个界面元素,用于显示特定位置附近的地点列表。注意:网页(Maps JavaScript API)和移动应用(Places SDK for Android 和 Places SDK for iOS)均支持此功能。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页或应用添加基本的自动补全界面元素,该元素会根据查询字符串返回 Google 地点标识符。注意:欧洲经济区 (EEA) 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq

Maps JavaScript API:街景