Google 地图 - UI 控件

Google Maps - 定制 UI 控件

Maps JavaScript API 提供了一套默认的用户界面 (UI) 控件，允许用户与地图进行交互（如缩放和平移）。你可以对哪些控件显示以及它们的位置进行精细控制。

默认控件

默认情况下，Google 地图通常包含以下控件：

• 缩放 (Zoom)： 显示 ’+’ 和 ’-’ 按钮（通常在右侧）以改变地图的缩放级别。
• 地图类型 (Map Type)： 允许用户在地图类型之间切换（例如，Roadmap，Satellite）。通常出现在左上角。
• 街景 (Street View)： 显示 Pegman 图标（通常在右侧），可以拖到地图上以激活街景影像。
• 全屏 (Fullscreen)： 允许用户以全屏模式打开地图（通常在右上角）。
• 旋转 (Rotate)： 在 45° 倾斜影像可用时自动出现，允许旋转（通常与缩放控件分组）。

具体外观和位置会根据地图大小和设备略有不同。

示例：带有默认控件的地图

在“入门”章节中创建的基本地图显示了这些默认控件。

预期输出：

标准地图视图，包含缩放控件（+/-）、地图类型选择（Map/Satellite）、街景 Pegman 图标和全屏按钮。

禁用所有默认 UI 控件

你可以通过在 MapOptions 中将 disableDefaultUI 选项设置为 true 来一次性隐藏 所有 默认控件。

示例：禁用默认 UI

修改 initMap 函数以包含此选项：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Map Without Default UI</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 position = { lat: 17.6868, lng: 83.2185 };
            const { Map } = await google.maps.importLibrary("maps");

            const map = new Map(document.getElementById("map"), {
                zoom: 10,
                center: position,
                mapId: "DEMO_MAP_ID",
                mapTypeId: 'roadmap',
                disableDefaultUI: true // <-- 添加此行
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly" async defer></script>
</body>
</html>

预期输出：

地图将不显示任何标准控件（缩放、地图类型、街景、全屏）。你仍然可以通过拖动进行平移，以及使用滚轮/手势进行缩放，但屏幕上的按钮将消失。

启用/禁用单个控件

除了禁用所有控件，你还可以使用 MapOptions 中的布尔选项单独控制每个 UI 元素。如果 disableDefaultUI 为 false（默认值），你可以选择性地开启或关闭控件。

• zoomControl: true（默认）/ false
• mapTypeControl: true（默认）/ false
• streetViewControl: true（默认）/ false
• fullscreenControl: true（默认）/ false
• scaleControl: false（默认）/ true（显示地图比例尺元素）
• rotateControl: true（默认，需要时出现）/ false

注意：旧 API 版本中的 panControl 和 overviewMapControl 已弃用，不再可用。

示例：启用比例尺控件并禁用街景

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Custom Controls 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 position = { lat: 19.0760, lng: 72.8777 }; // 孟买
            const { Map } = await google.maps.importLibrary("maps");

            const map = new Map(document.getElementById("map"), {
                zoom: 11,
                center: position,
                mapId: "DEMO_MAP_ID",
                mapTypeId: 'satellite',
                // disableDefaultUI: false, // 默认为 false，因此并非严格需要
                zoomControl: true,          // 保留缩放
                mapTypeControl: true,       // 保留地图类型
                streetViewControl: false,   // <-- 禁用街景
                fullscreenControl: true,    // 保留全屏
                scaleControl: true          // <-- 启用比例尺
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly" async defer></script>
</body>
</html>

预期输出：

地图显示孟买的卫星视图。包含缩放、地图类型和全屏控件。街景 Pegman 已隐藏，但地图比例尺（例如，“2 公里”）现在可见，通常在右下角。

控件选项和定位

你可以使用专用的 Options 对象（例如，zoomControlOptions、mapTypeControlOptions）进一步自定义某些控件的外观和位置。最常见的自定义是更改位置。

要更改控件的位置，请在其 Options 对象内设置 position 属性。使用 google.maps.ControlPosition 枚举中的值。

可用位置 (google.maps.ControlPosition)：

• TOP_CENTER、TOP_LEFT、TOP_RIGHT
• LEFT_TOP、RIGHT_TOP
• LEFT_CENTER、RIGHT_CENTER
• LEFT_BOTTOM、RIGHT_BOTTOM
• BOTTOM_CENTER、BOTTOM_LEFT、BOTTOM_RIGHT

注意：旧的 style 选项（如 google.maps.ZoomControlStyle.SMALL 或 google.maps.MapTypeControlStyle.DROPDOWN_MENU）在现代 API 中已不再有效支持。定位是主要的布局自定义方式。

示例：定位控件

让我们将地图类型控件移到顶部中心，并将缩放控件移到左下角。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Positioned Controls 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 position = { lat: 34.0522, lng: -118.2437 }; // 洛杉矶
            // 与 Map 一起导入 ControlPosition
            const { Map, ControlPosition } = await google.maps.importLibrary("maps");

            const map = new Map(document.getElementById("map"), {
                zoom: 10,
                center: position,
                mapId: "DEMO_MAP_ID",
                mapTypeId: 'roadmap',
                streetViewControl: false,
                fullscreenControl: false,

                // 启用并配置地图类型控件
                mapTypeControl: true,
                mapTypeControlOptions: {
                    // style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR, // 样式已弃用
                    position: ControlPosition.TOP_CENTER // <-- 定位它
                },

                // 启用并配置缩放控件
                zoomControl: true,
                zoomControlOptions: {
                    position: ControlPosition.LEFT_BOTTOM // <-- 定位它
                }
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly" async defer></script>
</body>
</html>

预期输出：

地图显示洛杉矶。地图/卫星按钮现在位于地图顶部边缘的中心。缩放 (+/-) 按钮位于左下角。街景和全屏控件被隐藏。

延伸阅读：

• 官方文档：控件
• ControlPosition 枚举参考