Google 地图 - 标记

Google Maps - 添加标记

标记 (Markers) 用于指示地图上的特定位置。它们是叠加层 (overlay) 的一种基本类型，通过在特定经纬度位置的图标来直观表示。

本章介绍如何添加基本标记、自定义其外观和行为，以及在地图上管理它们。

添加简单标记

要添加标记，首先需要加载 marker 库，然后实例化 google.maps.Marker 类（或在更复杂场景下使用更新的 google.maps.marker.AdvancedMarkerView）。你必须至少提供 position 和 map 属性。

1. 导入库： 将 marker 添加到你的 importLibrary 调用中。

const { Map } = await google.maps.importLibrary("maps");
const { Marker } = await google.maps.importLibrary("marker"); // <-- 添加此行

2. 创建标记： 在 initMap 函数内部，创建地图实例后，创建标记。

const marker = new google.maps.Marker({
    position: { lat: 17.3850, lng: 78.4867 }, // 海得拉巴
    map: map, // 将标记与 'map' 实例关联
    title: 'Hyderabad, India' // 可选：鼠标悬停时的文本提示
});

示例：在海得拉巴添加标记

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Simple Marker Map</title>
    <style>#map { height: 400px; width: 100%; } html, body { height: 100%; margin: 0; padding: 0; }</style>
</head>
<body>
    <div id="map"></div>
    <script>
        async function initMap() {
            const mapCenter = { lat: 17.3850, lng: 78.4867 }; // 海得拉巴
            const { Map } = await google.maps.importLibrary("maps");
            const { Marker } = await google.maps.importLibrary("marker"); // 导入 Marker 类

            const map = new Map(document.getElementById("map"), {
                zoom: 10,
                center: mapCenter,
                mapId: "DEMO_MAP_ID"
            });

            // 创建标记
            const marker = new Marker({
                position: mapCenter, // 将标记放置在相同的中心位置
                map: map,
                title: 'Hyderabad'
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly&libraries=marker" async defer></script>
    <!-- 注意：已在脚本 URL 中添加 &libraries=marker -->
</body>
</html>

预期输出：

地图居中于海得拉巴，并在中心位置放置了默认的红色 Google Maps 图钉标记。鼠标悬停在标记上时，会显示提示文本“Hyderabad”。

现代替代方案：AdvancedMarkerView

为了增强性能、自定义（包括使用 HTML/CSS 设置标记外观）和可访问性，可以考虑使用 AdvancedMarkerView。它需要导入 marker 库。

const { AdvancedMarkerView } = await google.maps.importLibrary("marker");

const advancedMarker = new AdvancedMarkerView({
    map: map,
    position: mapCenter,
    title: 'Hyderabad (Advanced)'
    // 你可以通过 'content' 属性在此处添加自定义 HTML 内容
});

虽然 Marker 对于基本用例来说更简单，但对于新开发来说，AdvancedMarkerView 是推荐的方法，特别是在处理大量标记或复杂样式时。在本教程的其余部分，我们将为了简单起见仍然使用基本的 Marker，但请注意这个强大的替代方案。

标记动画

你可以使用 animation 属性为 Marker 对象添加简单的动画。两种主要的动画是：

• google.maps.Animation.DROP: 标记添加时看起来像是从上方落到地图上。
• google.maps.Animation.BOUNCE: 标记在原地持续弹跳。

在创建标记时设置 animation 属性。

示例：添加一个下落的标记

<!DOCTYPE html>
<!-- ... (头部区域同前) ... -->
<body>
    <div id="map"></div>
    <script>
        async function initMap() {
            const mapCenter = { lat: 17.3850, lng: 78.4867 };
            const { Map, Animation } = await google.maps.importLibrary("maps"); // 导入 Animation
            const { Marker } = await google.maps.importLibrary("marker");

            const map = new Map(document.getElementById("map"), {
                zoom: 10,
                center: mapCenter,
                mapId: "DEMO_MAP_ID"
            });

            const marker = new Marker({
                position: mapCenter,
                map: map,
                title: 'Dropping Marker',
                animation: Animation.DROP // <-- 添加 animation 属性
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly&libraries=marker,maps" async defer></script>
    <!-- 注意：显式添加了 'maps' 库以确保加载 Animation 枚举 -->
</body>
</html>

预期输出：

地图加载时，标记将像下落一样动画到指定位置。

要使标记弹跳，将 Animation.DROP 更改为 Animation.BOUNCE。要通过编程方式停止动画，可以调用 marker.setAnimation(null);。

自定义标记

你可以将默认的红色图钉更改为自定义图像或使用预定义的矢量符号。

使用自定义图像图标：

将 icon 属性设置为你的图像文件的 URL。如果需要，你还可以提供一个 google.maps.Size 对象来指定图标的尺寸，或者一个 google.maps.Icon 对象来进行更精细的控制（尺寸、原点、锚点）。

const markerWithIcon = new google.maps.Marker({
    position: { lat: 17.44, lng: 78.34 }, // 另一个位置
    map: map,
    title: 'Custom Icon Marker',
    icon: 'https://maps.google.com/mapfiles/kml/shapes/info-i_maps.png' // 示例 URL
    /*
    // 更高级的图标自定义：
    icon: {
        url: 'path/to/your/custom-icon.png',
        scaledSize: new google.maps.Size(50, 50), // 显示尺寸（像素）
        origin: new google.maps.Point(0, 0), // 精灵图左上角坐标
        anchor: new google.maps.Point(25, 50) // 图标上锚定到经纬度坐标的点（例如，底部中心）
    }
    */
});

使用矢量符号：

将 icon 属性设置为一个 google.maps.Symbol 对象字面量。这将在“符号”章节中更详细介绍。

使标记可拖动：

通过设置 draggable: true 允许用户移动标记。

const draggableMarker = new google.maps.Marker({
    position: { lat: 17.40, lng: 78.45 },
    map: map,
    title: 'Drag Me!',
    draggable: true
});

// 你可以监听 'dragend' 事件来获取新位置
draggableMarker.addListener('dragend', (event) => {
    const newPosition = event.latLng;
    console.log('Marker dragged to:', newPosition.lat(), newPosition.lng());
    // 更新数据库等。
});

更改标记标签：

使用 label 属性在默认标记图标内部添加一个单字符标签。

const labeledMarker = new google.maps.Marker({
    position: { lat: 17.36, lng: 78.55 },
    map: map,
    label: 'A', // 可以是字符串或 MarkerLabel 对象
    title: 'Marker A'
});

/*
// 使用 MarkerLabel 对象进行更多控制：
const labeledMarkerB = new google.maps.Marker({
    position: { lat: 17.37, lng: 78.56 },
    map: map,
    label: {
        text: 'B',
        color: 'white',
        fontSize: '12px',
        fontWeight: 'bold'
    },
    title: 'Marker B'
});
*/

移除标记

要从地图上移除标记，调用其 setMap() 方法并将参数设置为 null。

// 假设 'marker' 是保存你的 Marker 对象的变量
marker.setMap(null);

这不会删除标记对象本身，只是将其从显示中移除。你可以稍后通过再次调用 marker.setMap(map); 将其重新添加到地图上。

示例：使用按钮添加和移除标记（概念性）

假设你有一些 HTML 按钮用于添加/移除标记：

<!-- HTML -->
<button id="addMarkerBtn">添加标记</button>
<button id="removeMarkerBtn">移除标记</button>
<div id="map"></div>

<script>
    let map;
    let marker = null; // 跟踪标记
    const markerPosition = { lat: 17.3850, lng: 78.4867 };

    async function initMap() {
        const { Map } = await google.maps.importLibrary("maps");
        const { Marker } = await google.maps.importLibrary("marker");

        map = new Map(document.getElementById("map"), { /* ... 地图选项 ... */ });

        document.getElementById('addMarkerBtn').addEventListener('click', () => {
            if (!marker) { // 仅在不存在时添加
                marker = new Marker({
                    position: markerPosition,
                    map: map,
                    title: '我的标记'
                });
            }
             // 如果已移除，可选地将其重新添加回来
             else if (marker.getMap() === null) {
                 marker.setMap(map);
             }
        });

        document.getElementById('removeMarkerBtn').addEventListener('click', () => {
            if (marker) {
                marker.setMap(null);
            }
        });
    }
</script>
<!-- 加载 Google Maps API -->

此示例演示了根据用户交互动态添加和移除标记的逻辑。

延伸阅读：

• 官方文档：标记
• Marker 类参考
• AdvancedMarkerView 文档
• Animation 枚举参考