Google Maps API 教程

Google API 教程

Google API 是 Google 提供给开发者的应用程序接口集合,涵盖地图、搜索、翻译、机器学习、云服务等众多能力。本文聚焦 Google Maps JavaScript API,展示如何在网页中集成地图。

Google API 概览

Google Maps API:地图展示与地理信息
Google Search API:搜索能力(已多数废弃)
Google Translate API:翻译服务
Google Cloud API:云计算、AI、存储
Google Auth API:OAuth 登录

Google Maps 能力

地图展示(多种地图类型)
标记(Marker)与信息窗口
路线规划与方向服务
地理编码(地址 ↔ 坐标)
街景与绘图工具

基本流程

1. 获取 API Key(Google Cloud Console)
2. 启用 Maps JavaScript API
3. 在 HTML 中加载脚本
4. 创建地图并添加功能

注意

# 国内访问
# Google Maps 在中国大陆访问受限
# 国内替代方案:高德地图、百度地图
# 教程用于学习 API 设计思路

# API Key 安全
# 限制 Key 的域名与用途
# 不要在前端暴露高权限 Key

Google 地图 API

1. 获取 API Key

# 步骤
1. 访问 Google Cloud Console
   https://console.cloud.google.com
2. 创建项目(或选择现有)
3. 启用 API 与服务 → Maps JavaScript API
4. 凭据 → 创建凭据 → API 密钥
5. 复制 Key

# 安全限制(强烈建议)
- 限制 HTTP 引用(只允许你的域名)
- 限制 IP 地址
- 限制 API(只启用需要的)

2. 引入脚本

<script
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_KEY&callback=initMap"
  async defer>
</script>

3. 第一个地图

<!DOCTYPE html>
<html>
<head>
  <style>
    #map { width: 100%; height: 400px; }
  </style>
</head>
<body>
  <div id="map"></div>

  <script>
    // 回调函数
    function initMap() {
      // 中心点(北京)
      var location = { lat: 39.9042, lng: 116.4074 };

      // 创建地图
      var map = new google.maps.Map(
        document.getElementById("map"), {
          zoom: 12,
          center: location
        }
      );

      // 添加标记
      new google.maps.Marker({
        position: location,
        map: map,
        title: "北京"
      });
    }
  </script>

  <!-- 引入 API -->
  <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_KEY&callback=initMap" async defer></script>
</body>
</html>

4. 常见类

google.maps.Map          地图
google.maps.Marker       标记
google.maps.InfoWindow   信息窗口
google.maps.Polyline     折线
google.maps.Polygon      多边形
google.maps.Circle       圆形
google.maps.Geocoder     地理编码
google.maps.DirectionsService  路线
google.maps.StreetViewService  街景

Google 地图基础

1. 地图选项

var map = new google.maps.Map(el, {
  center: { lat: 39.9042, lng: 116.4074 },
  zoom: 12,                    // 缩放级别 0-21
  mapTypeId: "roadmap",        // 地图类型
  disableDefaultUI: false,     // 是否显示默认控件
  zoomControl: true,           // 缩放控件
  scrollwheel: true,           // 滚轮缩放
  draggable: true,             // 可拖拽
  fullscreenControl: true,     // 全屏
  streetViewControl: true,     // 街景
  mapTypeControl: true         // 类型切换
});

2. 地图操作

// 设置中心
map.setCenter({ lat: 31.2304, lng: 121.4737 });

// 设置缩放
map.setZoom(15);

// 获取中心/缩放
var center = map.getCenter();
var zoom = map.getZoom();

// 边界
map.fitBounds(bounds);   // 适应边界

// 监听事件
google.maps.event.addListener(map, "click",
  function(e) {
    console.log("点击坐标:", e.latLng.lat(), e.latLng.lng());
  });

// 移除事件
google.maps.event.clearListeners(map, "click");

3. 标记(Marker)

// 基本标记
var marker = new google.maps.Marker({
  position: { lat: 39.9, lng: 116.4 },
  map: map,
  title: "标记标题",
  icon: "https://example.com/pin.png",  // 自定义图标
  draggable: true          // 可拖动
});

// 标记点击
marker.addListener("click", function() {
  alert("点击了标记!");
});

// 动画
marker.setAnimation(google.maps.Animation.DROP);
// BOUNCE 弹跳 / DROP 掉落

// 删除标记
marker.setMap(null);

4. 信息窗口

var infoWindow = new google.maps.InfoWindow({
  content: "<h3>北京</h3><p>中国首都</p>",
  maxWidth: 300
});

marker.addListener("click", function() {
  infoWindow.open(map, marker);
});

// 动态内容
infoWindow.setContent("<b>更新内容</b>");
infoWindow.close();

Google 地图叠加层

1. 折线(Polyline)

var path = [
  { lat: 39.9, lng: 116.4 },
  { lat: 31.2, lng: 121.5 },
  { lat: 22.5, lng: 114.1 }
];

var polyline = new google.maps.Polyline({
  path: path,
  geodesic: true,
  strokeColor: "#FF0000",
  strokeOpacity: 1.0,
  strokeWeight: 3
});
polyline.setMap(map);

2. 多边形(Polygon)

var triangle = [
  { lat: 39.9, lng: 116.3 },
  { lat: 39.9, lng: 116.5 },
  { lat: 39.8, lng: 116.4 }
];

var polygon = new google.maps.Polygon({
  paths: triangle,
  strokeColor: "#0000FF",
  strokeWeight: 2,
  fillColor: "#00FF00",
  fillOpacity: 0.3
});
polygon.setMap(map);

// 可编辑
polygon.setEditable(true);

3. 圆形与矩形

// 圆形
var circle = new google.maps.Circle({
  strokeColor: "#FF0000",
  strokeOpacity: 0.8,
  strokeWeight: 2,
  fillColor: "#FF0000",
  fillOpacity: 0.2,
  map: map,
  center: { lat: 39.9, lng: 116.4 },
  radius: 5000     // 米
});

// 矩形
var rectangle = new google.maps.Rectangle({
  bounds: {
    north: 40.0, south: 39.8,
    east: 116.6, west: 116.2
  },
  map: map
});

4. 图层(图层)

// 交通图层
var trafficLayer = new google.maps.TrafficLayer();
trafficLayer.setMap(map);

// 公交图层
var transitLayer = new google.maps.TransitLayer();
transitLayer.setMap(map);

// 自行车图层
var bikeLayer = new google.maps.BicyclingLayer();
bikeLayer.setMap(map);

// 移除图层
trafficLayer.setMap(null);

5. 信息窗口与叠加组合

// 点击多边形显示信息
polygon.addListener("click", function(e) {
  infoWindow.setPosition(e.latLng);
  infoWindow.setContent("点击了多边形");
  infoWindow.open(map);
});

Google 地图事件

1. 地图事件

// 点击地图
map.addListener("click", function(e) {
  console.log("位置:", e.latLng.lat(), e.latLng.lng());
});

// 双击
map.addListener("dblclick", function(e) { ... });

// 拖动
map.addListener("drag", function() { ... });
map.addListener("dragend", function() {
  console.log("新中心:", map.getCenter());
});

// 缩放
map.addListener("zoom_changed", function() {
  console.log("缩放级别:", map.getZoom());
});

// 类型切换
map.addListener("maptypeid_changed", function() { ... });

// 边界变化
map.addListener("bounds_changed", function() { ... });

2. 标记事件

marker.addListener("click", function() { ... });
marker.addListener("mouseover", function() { ... });
marker.addListener("mouseout", function() { ... });
marker.addListener("dragend", function(e) {
  // 拖动结束获取新位置
  console.log("新坐标:", e.latLng.lat(), e.latLng.lng());
});

3. 事件工具函数

// 添加一次性事件
google.maps.event.addListenerOnce(map, "idle", function() {
  console.log("地图加载完成(仅一次)");
});

// 绑定对象属性
// 多个标记绑定同一事件
var clickHandler = function(e) {
  console.log("标记:", this.getTitle());
};
markers.forEach(function(m) {
  m.addListener("click", clickHandler);
});

4. 事件实践:点击添加标记

var markers = [];

map.addListener("click", function(e) {
  var marker = new google.maps.Marker({
    position: e.latLng,
    map: map,
    draggable: true
  });
  markers.push(marker);

  // 显示坐标信息
  var info = new google.maps.InfoWindow({
    content: "纬度: " + e.latLng.lat().toFixed(4) +
             "<br>经度: " + e.latLng.lng().toFixed(4)
  });
  info.open(map, marker);
});

// 清除所有标记
function clearMarkers() {
  markers.forEach(function(m) { m.setMap(null); });
  markers = [];
}

Google 地图控件集

1. 内置控件

# Google 地图内置控件
缩放控件(zoomControl)
类型切换(mapTypeControl)
全屏(fullscreenControl)
街景(streetViewControl)
比例尺(scaleControl)
旋转(rotateControl)

# 配置
var map = new google.maps.Map(el, {
  center: ...,
  zoom: 12,
  mapTypeControl: true,
  mapTypeControlOptions: {
    position: google.maps.ControlPosition.TOP_LEFT,
    style: google.maps.MapTypeControlStyle.DROPDOWN_MENU
  },
  scaleControl: true,
  scaleControlOptions: {
    position: google.maps.ControlPosition.BOTTOM_LEFT
  }
});

2. 控件位置

google.maps.ControlPosition
  TOP_LEFT / TOP_CENTER / TOP_RIGHT
  LEFT_CENTER / RIGHT_CENTER
  BOTTOM_LEFT / BOTTOM_CENTER / BOTTOM_RIGHT

// 示例
position: google.maps.ControlPosition.TOP_RIGHT

3. 自定义控件

// 自定义控件类
function HomeControl(controlDiv, map) {
  controlDiv.style.padding = "5px";
  var controlUI = document.createElement("div");
  controlUI.style.cssText =
    "background:#fff;padding:8px 12px;cursor:pointer;" +
    "border:1px solid #ccc;border-radius:4px;";
  controlUI.textContent = "回到北京";
  controlDiv.appendChild(controlUI);

  controlUI.addEventListener("click", function() {
    map.setCenter({ lat: 39.9042, lng: 116.4074 });
    map.setZoom(12);
  });
}

// 添加到地图
var controlDiv = document.createElement("div");
new HomeControl(controlDiv, map);
map.controls[google.maps.ControlPosition.TOP_LEFT]
  .push(controlDiv);

4. 控件显示控制

// 隐藏默认控件
disableDefaultUI: true

// 单独控制
zoomControl: false
mapTypeControl: false
fullscreenControl: false
streetViewControl: false
scaleControl: true

Google 地图类型

1. 内置地图类型

# ROADMAP    普通街道地图(默认)
# SATELLITE  卫星影像
# HYBRID     卫星 + 标注
# TERRAIN    地形图

// 设置
map.setMapTypeId("satellite");

// 或初始化时
var map = new google.maps.Map(el, {
  mapTypeId: google.maps.MapTypeId.SATELLITE
});

2. 自定义地图样式

// 深色主题地图
var darkStyle = [
  {
    "featureType": "all",
    "elementType": "geometry",
    "stylers": [{ "color": "#242f3e" }]
  },
  {
    "featureType": "water",
    "elementType": "geometry",
    "stylers": [{ "color": "#17263c" }]
  },
  {
    "featureType": "road",
    "elementType": "labels.text.fill",
    "stylers": [{ "color": "#8a8a8a" }]
  }
];

var styledMap = new google.maps.StyledMapType(
  darkStyle,
  { name: "深色主题" }
);

map.mapTypes.set("dark", styledMap);
map.setMapTypeId("dark");

3. 地图类型控件

// 自定义类型按钮
mapTypeControlOptions: {
  mapTypeIds: [
    "roadmap",
    "satellite",
    "dark"     // 自定义类型
  ],
  style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR
}

4. 常用样式场景

# 深色主题: 数据大屏
# 简约主题: 新闻/博客
# 高对比: 无障碍
# 无标签: 纯地图底图

# 在线样式生成
# https://mapstyle.withgoogle.com
# 生成 JSON 样式粘贴使用

Google 地图参考手册

1. 核心类速查

# 地图
google.maps.Map           地图对象
google.maps.MapOptions    地图配置

# 几何
google.maps.LatLng        经纬度坐标
google.maps.LatLngBounds  边界范围
google.maps.Point         像素点
google.maps.Size          尺寸

# 叠加层
google.maps.Marker        标记
google.maps.InfoWindow    信息窗口
google.maps.Polyline      折线
google.maps.Polygon       多边形
google.maps.Circle        圆形
google.maps.Rectangle     矩形
google.maps.GroundOverlay 地面覆盖

# 服务
google.maps.Geocoder      地理编码
google.maps.DirectionsService  路线服务
google.maps.DistanceMatrixService 距离矩阵
google.maps.PlacesService 地点服务
google.maps.StreetViewService  街景

2. 常用方法速查

map.setCenter(latlng)      设置中心
map.setZoom(level)         设置缩放
map.setMapTypeId(type)     设置类型
map.fitBounds(bounds)      适应边界
map.panTo(latlng)          平移
map.getBounds()            获取边界

marker.setMap(map)         显示标记
marker.setPosition(latlng) 移动标记
marker.getPosition()       获取位置
marker.setAnimation()      设置动画
marker.setMap(null)        移除标记

infoWindow.open(map, anchor) 打开
infoWindow.close()            关闭
infoWindow.setContent(html)   设置内容

3. 常量速查

google.maps.MapTypeId
  ROADMAP SATELLITE HYBRID TERRAIN

google.maps.Animation
  DROP BOUNCE

google.maps.ControlPosition
  TOP_LEFT TOP_CENTER TOP_RIGHT ...
  LEFT_CENTER RIGHT_CENTER ...

google.maps.TravelMode
  DRIVING WALKING BICYCLING TRANSIT

google.maps.GeocoderStatus
  OK ZERO_RESULTS ERROR ...

地图 API Map() 构造器

1. Map 构造器

// 语法
new google.maps.Map(container, options)

// 完整选项
var options = {
  center: { lat: 39.9, lng: 116.4 },  // 必选
  zoom: 12,                           // 必选
  minZoom: 3,                         // 最小缩放
  maxZoom: 18,                        // 最大缩放
  mapTypeId: "roadmap",
  heading: 0,                         // 方向(街景)
  tilt: 0,                            // 倾斜
  draggable: true,
  scrollwheel: true,
  disableDoubleClickZoom: false,
  keyboardShortcuts: true,
  backgroundColor: "#fff",
  styles: [],                         // 自定义样式
  gestureHandling: "auto",            // 手势处理
  restriction: { latLngBounds: ... }, // 区域限制
  mapId: "MAP_ID"                     // 高级功能 ID
};

2. 创建示例

<div id="map" style="width:100%;height:500px;"></div>

<script>
function initMap() {
  // 多个地图实例
  var map1 = new google.maps.Map(
    document.getElementById("map"), {
      center: { lat: 39.9042, lng: 116.4074 },
      zoom: 12
    });

  var map2 = new google.maps.Map(
    document.getElementById("map2"), {
      center: { lat: 31.2304, lng: 121.4737 },
      zoom: 13
    });
}
</script>

3. 地图状态管理

// 保存/恢复地图状态
function saveState(map) {
  return {
    center: map.getCenter().toJSON(),
    zoom: map.getZoom(),
    type: map.getMapTypeId()
  };
}

function restoreState(map, state) {
  map.setCenter(state.center);
  map.setZoom(state.zoom);
  map.setMapTypeId(state.type);
}

// 使用
var state = saveState(map);
// ... 其他操作
restoreState(map, state);

4. 事件绑定在构造器

// 构造时不可直接传事件
// 需创建后 addListener
var map = new google.maps.Map(el, options);

map.addListener("idle", function() {
  console.log("地图空闲(加载完成)");
});

Google 地图教程总结

1. 知识回顾

API Key:Cloud Console 获取并配置限制
Map():构造地图,center/zoom 必选
Marker:标记与信息窗口
叠加层:折线、多边形、圆形、图层
事件:click、drag、zoom_changed 等
控件:内置控件与自定义控件
地图类型:标准/卫星/地形 + 自定义样式

2. 进阶功能

# 地理编码(Geocoding)
var geocoder = new google.maps.Geocoder();
geocoder.geocode(
  { address: "天安门" },
  function(results, status) {
    if (status === "OK") {
      var loc = results[0].geometry.location;
      console.log("坐标:", loc.lat(), loc.lng());
    }
  });

# 路线规划(Directions)
var directions = new google.maps.DirectionsService();
var renderer = new google.maps.DirectionsRenderer();
renderer.setMap(map);

directions.route({
  origin: "北京",
  destination: "上海",
  travelMode: "DRIVING"
}, function(result, status) {
  if (status === "OK") {
    renderer.setDirections(result);
  }
});

3. 国内替代方案

# Google Maps 国内访问受限
# 推荐替代
高德地图 JS API    amap.com
百度地图 JS API    lbsyun.baidu.com
腾讯位置服务       lbs.qq.com

# API 设计类似
# 学习 Google Maps 后可快速迁移

4. 最佳实践

API Key 严格限制(域名/IP)
地图容器必须有明确宽高
大数据量标记用 MarkerClusterer
移动端考虑手势与性能
监听 idle 事件再加载数据

5. 官方资源

文档:  developers.google.com/maps/documentation
示例:  developers.google.com/maps/documentation/javascript/examples
定价:  cloud.google.com/maps-platform/pricing
控制台: console.cloud.google.com

# 结语
# 掌握地图 API 的核心模式,
# 即可快速构建 LBS 应用。

第 1 / 10 节

Google API 教程

Google API 教程

Google API 概览

Google Maps 能力

基本流程

注意

Google 地图 API

Google 地图 API

1. 获取 API Key

2. 引入脚本

3. 第一个地图

4. 常见类

Google 地图基础

Google 地图基础

1. 地图选项

2. 地图操作

3. 标记(Marker)

4. 信息窗口

Google 地图叠加层

Google 地图叠加层

1. 折线(Polyline)

2. 多边形(Polygon)

3. 圆形与矩形

4. 图层(图层)

5. 信息窗口与叠加组合

Google 地图事件

Google 地图事件

1. 地图事件

2. 标记事件

3. 事件工具函数

4. 事件实践:点击添加标记

Google 地图控件集

Google 地图控件集

1. 内置控件

2. 控件位置

3. 自定义控件

4. 控件显示控制

Google 地图类型

Google 地图类型

1. 内置地图类型

2. 自定义地图样式

3. 地图类型控件

4. 常用样式场景

Google 地图参考手册

Google 地图参考手册

1. 核心类速查

2. 常用方法速查

3. 常量速查

地图 API Map() 构造器

地图 API Map() 构造器

1. Map 构造器

2. 创建示例

3. 地图状态管理

4. 事件绑定在构造器

Google 地图 教程总结

Google 地图 教程总结

1. 知识回顾

2. 进阶功能

3. 国内替代方案

4. 最佳实践

5. 官方资源

Google 地图教程总结

Google 地图教程总结