Google 地图 - 入门

Google 地图平台 - Maps JavaScript API 入门

本教程将指导你如何使用 Maps JavaScript API 在网页上显示一个简单、交互式的谷歌地图。

什么是 Maps JavaScript API？

Google 地图平台 (Google Maps Platform) 的 Maps JavaScript API 允许你将定制的 Google 地图直接嵌入到你自己的网页中。它是实现以下功能的强大工具：

显示与你的内容相关的地理位置。
在地图上可视化数据点（例如，商店位置、用户活动）。
提供交互功能，如平移 (panning)、缩放 (zooming) 和切换地图类型 (map types)。
添加标记 (markers)、线条 (lines)、形状 (shapes) 和信息窗口 (information windows)，以突出显示特定区域或路线。
与其他 Google 地图服务（如 Directions、Geocoding 和 Places）集成。

本入门章节重点介绍获取并运行基本地图的基本步骤。

在网页上加载地图的步骤

按照以下步骤嵌入你的第一个 Google 地图：

步骤 1：设置环境并获取 API 密钥

在开始之前，你需要一个 API 密钥 (API key)。此密钥用于验证你向 Google 服务发出的请求。

前往 Google Cloud Console。
创建新项目或选择现有项目。
为你的项目启用“Maps JavaScript API”服务。
创建凭据以获取 API 密钥。
重要提示： 保护你的 API 密钥！限制其在你的特定网站域名 (web domains) 上使用，以防止未经授权的使用。请参阅 API 密钥最佳实践。

步骤 2：创建基本的 HTML 页面

从标准的 HTML5 文档结构开始：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Google Map</title>
    <style>
        /* 地图容器的基础样式 */
        #map {
            height: 400px; /* 或任何你想要的高度 */
            width: 100%;  /* 使地图具有响应性 */
        }
        /* 可选：确保 html 和 body 占满整个高度 */
        html, body {
            height: 100%;
            margin: 0;
            padding: 0;
        }
    </style>
</head>
<body>
    <h3>My Google Map</h3>
    <!-- 将包含地图的 div 元素 -->
    <div id="map"></div>

    <!-- API 脚本将放在这里 -->
</body>
</html>

注意带有 id="map" 的 div 元素。这是地图将要渲染的地方。CSS 确保此 div 具有定义的高度，这对于地图显示至关重要。

步骤 3：加载 Maps JavaScript API

在结束 </body> 标签之前包含 API 脚本。将 YOUR_API_KEY 替换为你从步骤 1 中获得的密钥。

<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly" async defer></script>
<!--
  关键参数：
  - key=YOUR_API_KEY: 你的唯一 API 密钥（必需）。
  - callback=initMap: 指定 API 加载完成后要调用的全局函数。
  - v=weekly: 指定 API 版本（建议开发使用 weekly 通道）。
  - async: 允许并行下载脚本而不会阻塞 HTML 解析。
  - defer: 确保脚本在 HTML 完全解析后才执行。
-->

步骤 4：定义 `initMap` 回调函数

callback=initMap 参数告诉 API 在准备就绪后执行 initMap 函数。在 <script> 标签内（或在单独的 JS 文件中）创建此函数。此函数将创建和配置你的地图。

<script>
    // 初始化并添加地图
    async function initMap() {
        // 地图要居中的位置（例如，维萨卡帕特南）
        const position = { lat: 17.6868, lng: 83.2185 };

        // 请求所需的库。
        // 从 'maps' 库导入 Map 类
        const { Map } = await google.maps.importLibrary("maps");

        // 地图，居中于指定位置
        const map = new Map(document.getElementById("map"), {
            zoom: 12,             // 初始缩放级别（值越高，缩入越多）
            center: position,     // 将地图居中于 'position' 坐标
            mapId: "DEMO_MAP_ID", // 可选：用于基于云样式的 Map ID
            mapTypeId: 'roadmap' // 初始地图类型（roadmap, satellite, hybrid, terrain）
        });

        // 可选：在中心位置添加标记
        // const { Marker } = await google.maps.importLibrary("marker");
        // const marker = new Marker({
        //    map: map,
        //    position: position,
        //    title: '维萨卡帕特南'
        // });
    }

    // 调用 initMap - 这由脚本 URL 中的 callback 参数处理
    // initMap(); // 使用 callback 参数时无需显式调用
</script>

关键组件解释：

async function initMap(): 声明一个异步函数。使用 async 允许我们在内部使用 await。
const position = { lat: ..., lng: ... };: 使用现代对象字面量定义地理坐标（纬度 Latitude，经度 Longitude）。
await google.maps.importLibrary("maps"): 异步加载所需的 maps 库组件，包括 Map 类。这是加载特定 API 功能的现代方法。
new Map(document.getElementById("map"), {...}): 创建一个新的 Google Map 实例。它接受两个参数：

- 地图应显示在其中的 HTML 元素（我们的 `<div id="map">`）。

- 一个包含配置设置的 `MapOptions` 对象字面量：

    - `zoom`: 控制初始放大级别。数字越大，缩放越近。

    - `center`: 使用 `position` 对象设置初始地图中心。

    - `mapId`: （可选但推荐用于自定义）链接到在 Google Cloud Console 中配置的 Map ID，用于基于云的地图样式设置。使用 `mapId` 是设置地图样式的现代方法。

    - `mapTypeId`: 指定初始地图类型。常用值包括 `'roadmap'`、`'satellite'`、`'hybrid'`、`'terrain'`。

步骤 5：查看你的地图！

保存你的 HTML 文件并在网页浏览器中打开它。你应该能看到一个交互式 Google 地图，居中于指定位置（示例中是维萨卡帕特南）。

故障排除：

空白页面/地图未加载： 检查浏览器的开发者控制台（通常按 F12）查看错误。常见问题包括：
```
- API 密钥丢失或不正确。
```

- API 密钥限制阻止你的域名（例如 `localhost` 或 `file://`）使用它。

- 在 Cloud Console 中未启用 Maps JavaScript API。

- 你的 `initMap` 函数中有 JavaScript 错误。

```
- 地图 `div` 没有定义 `height`。
```
“initMap is not a function”错误： 确保你的 initMap 函数定义在全局作用域中（除非正确暴露，否则不要在其他函数内部定义），并且 API 脚本 URL 中的 callback=initMap 参数与你的函数名称完全匹配。
API 密钥安全： 记住在 Cloud Console 中限制你的 API 密钥用于生产环境。

示例：完整 HTML

以下是结合所有步骤的完整代码：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Google Map</title>
    <style>
        #map {
            height: 400px;
            width: 100%;
        }
        html, body {
            height: 100%;
            margin: 0;
            padding: 0;
        }
    </style>
</head>
<body>
    <h3>My Google Map</h3>
    <div id="map"></div>

    <script>
        // 初始化并添加地图
        async function initMap() {
            const position = { lat: 17.6868, lng: 83.2185 }; // 维萨卡帕特南

            // 请求所需的库。
            const { Map } = await google.maps.importLibrary("maps");
            // 可选：如果要添加标记，导入标记库
            // const { Marker } = await google.maps.importLibrary("marker");

            const map = new Map(document.getElementById("map"), {
                zoom: 12,
                center: position,
                mapId: "DEMO_MAP_ID", // 可选：替换为你自己的 Map ID
                mapTypeId: 'roadmap'
            });

            // 可选：添加标记
            // const marker = new Marker({
            //    map: map,
            //    position: position,
            //    title: '维萨卡帕特南'
            // });
        }
    </script>

    <!-- 加载 Google Maps API -->
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly" async defer></script>

</body>
</html>

请记住将 YOUR_API_KEY 替换为你实际的密钥。

预期输出：

在浏览器中打开此 HTML 文件将显示一个交互式 Google 地图，覆盖维萨卡帕特南区域，使用标准的道路地图样式，并放大以显示城市详情。