Google 地图 - 符号

Google 地图 - 使用符号 (Symbols)

符号 (Symbols) 提供了一种方式，可以使用预定义的矢量路径（如圆形或箭头）或自定义 SVG 路径作为标记 (markers) 的图标或折线 (polylines) 上的装饰。它们提供了灵活的样式设置，并且可以在缩放时保持质量不失真。

google.maps.Symbol 接口

符号由一个符合 google.maps.Symbol 接口的对象字面量定义。主要属性包括：

• path：定义符号的形状。可以是：

• - Google Maps SymbolPath 中的预定义路径（例如，`CIRCLE`，`FORWARD_CLOSED_ARROW`）。

• - SVG 路径字符串（例如，`'M 0,0 L 10,10 Z'`）。

• scale：符号大小的缩放比例（一个数值）。
• fillColor：填充颜色（例如，'#FF0000'，'blue'）。
• fillOpacity：填充不透明度（0.0 到 1.0）。
• strokeColor：边框颜色。
• strokeOpacity：边框不透明度。
• strokeWeight：边框厚度（像素）。
• rotation：旋转角度（以度为单位，顺时针）。
• anchor：符号相对于其 LatLng 坐标的位置（例如，new google.maps.Point(0, 0) 表示左上角）。在使用作标记图标时相关。
• labelOrigin：标签（如果使用）相对于符号锚点的位置。与标记标签相关。

预定义符号路径 (google.maps.SymbolPath)

API 提供了几个内置的矢量路径：

• CIRCLE：一个圆形。
• FORWARD_CLOSED_ARROW：一个实心的前向箭头。
• FORWARD_OPEN_ARROW：一个开放式前向箭头（人字形）。
• BACKWARD_CLOSED_ARROW：一个实心的后向箭头。
• BACKWARD_OPEN_ARROW：一个开放式后向箭头。

您需要从 core 库导入 SymbolPath： const { SymbolPath } = await google.maps.importLibrary("core");

将符号用作标记图标

与其为标记的 icon 属性提供 URL，不如提供一个 Symbol 对象字面量。

示例：将后向箭头符号用作标记

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Symbol as Marker Icon</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.4330, lng: 78.4121 }; // 海得拉巴区域
            const { Map } = await google.maps.importLibrary("maps");
            const { Marker } = await google.maps.importLibrary("marker");
            const { SymbolPath } = await google.maps.importLibrary("core"); // 导入 SymbolPath

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

            // 定义符号
            const arrowSymbol = {
                path: SymbolPath.BACKWARD_CLOSED_ARROW,
                scale: 6,              // 使其更大
                fillColor: '#B40404',  // 深红色填充
                fillOpacity: 0.8,
                strokeColor: '#8A0808', // 更深的边框
                strokeWeight: 2,
                rotation: 0            // 指向左侧（默认）
            };

            // 使用符号创建标记作为其图标
            const marker = new Marker({
                position: mapCenter,
                map: map,
                icon: arrowSymbol,     // <-- 在这里使用符号对象
                title: 'Backward Arrow Symbol',
                draggable: true        // 如果需要，使其可拖动
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly&libraries=marker,core" async defer></script>
     <!-- 添加了 libraries=marker,core -->
</body>
</html>

预期输出：一张显示海得拉巴区域的地图，中心有一个深红色、后向箭头的标记。

为符号标记添加动画

使用符号作为图标的标记可以像普通标记一样，使用 animation 属性 (DROP 或 BOUNCE) 添加动画。

示例：为符号标记添加 Drop 动画

修改上一个示例中的标记创建代码：

// ... 在 initMap 函数内，定义 arrowSymbol 之后 ...
// 导入 Animation： const { Animation } = await google.maps.importLibrary("maps");

const marker = new google.maps.Marker({
    position: mapCenter,
    map: map,
    icon: arrowSymbol,
    title: 'Dropping Arrow Symbol',
    animation: google.maps.Animation.DROP // <-- 添加动画
});

您还需要从 maps 库导入 Animation： const { Animation } = await google.maps.importLibrary("maps"); 并在脚本 URL 中的 libraries 参数中添加 maps。

预期输出：加载时，箭头标记将呈现向下“掉落”的动画效果。

在折线 (Polylines) 上使用符号

可以将符号附加到折线 (polylines) 上，以指示方向或添加装饰。这通过使用 PolylineOptions 中的 icons 属性来完成。icons 属性接受一个 google.maps.IconSequence 对象数组。

关键 IconSequence 属性：

• icon：要显示的 Symbol 对象。
• offset：符号应出现在线起点处的距离（例如，'0%'，'50px'，'100%'）。
• repeat：沿着线的重复符号之间的距离（例如，'20px'，'10%'）。如果设置，符号会重复。
• fixedRotation：如果为 true，符号的旋转相对于屏幕是固定的；如果为 false（默认值），它会随着线的方向旋转。

示例：为折线添加箭头

<!DOCTYPE html>
<!-- ... 头部 ... -->
<body>
    <div id="map"></div>
    <script>
        async function initMap() {
            const mapCenter = { lat: 40.7, lng: -74 }; // 纽约市区域
            const { Map } = await google.maps.importLibrary("maps");
            const { SymbolPath } = await google.maps.importLibrary("core");

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

            const pathCoords = [
                { lat: 40.71, lng: -74.01 }, { lat: 40.72, lng: -73.99 },
                { lat: 40.73, lng: -74.00 }, { lat: 40.74, lng: -73.98 }
            ];

            // 定义箭头符号
            const arrowSymbol = {
                path: SymbolPath.FORWARD_OPEN_ARROW,
                scale: 3,
                strokeColor: '#0000FF',
                strokeWeight: 2
            };

            // 使用箭头图标序列创建折线
            const polyline = new google.maps.Polyline({
                path: pathCoords,
                strokeColor: '#FF0000',
                strokeOpacity: 0.8,
                strokeWeight: 2,
                map: map,
                icons: [{
                    icon: arrowSymbol,
                    offset: '50%', // 在中点放置一个箭头
                }, {
                    icon: arrowSymbol,
                    offset: '0%',   // 起点箭头
                    repeat: '100px' // 每 100 像素重复一次
                }]
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly&libraries=core" async defer></script>
    <!-- 添加了 libraries=core -->
</body>
</html>

预期输出：地图上的一条红色折线，沿着折线放置了蓝色的开放式箭头。一个箭头固定在 50% 位置，其他箭头从起点开始每 100 像素重复一次。

自定义 SVG 路径

为了完全控制，您可以在 path 属性中使用 SVG 路径表示法来定义符号的形状。

const customSymbol = {
    path: 'M -5,0 L 5,0 L 0,5 Z', // 简单的三角形 SVG 路径数据
    scale: 4,
    fillColor: 'green',
    fillOpacity: 1,
    strokeWeight: 1
};

然后，这个自定义符号可以像预定义的符号一样，用作标记图标或用于折线上。

延伸阅读：

• 符号官方文档
• Symbol 接口参考
• SymbolPath 枚举参考
• IconSequence 接口参考
• SVG 路径语法 (MDN)