Google Maps Embed API & JavaScript API

前言

很多年前写过一篇 Google Map 谷歌地图, 这篇算是翻新版本.

 

Google Map Registration

Google Maps Platform 是整个 Google Map 的大本营. 里面有许许多多的 Services. Embed 和 JavaScript API 只是其中的两个.

首先, Services 不是免费的, 像 Maps JavaScript API 1000 个 request 要 7 块钱美金, 但 Google 每个月有 free USD 200 让你花. 所以可以算是间接免费.

但是申请账户需要绑定银行卡哦.

下图是它的 Documentation

这篇的内容, 大部分都是来自 JS API 和 Embed API 文档.

申请的部分我就不 step by step 讲了. 大概有几个东西需要弄:

1. 申请 Google Cloud (Map 属于 Cloud 的一部分)

2. 绑卡

3. Create New Project

4. Enable Services (Maps Embed / JavaScript API)

5. 做 API Key (API Key 要设定只有在指定的 Domain 内能用哦 (这个叫 Key restrictions), 因为 API Key 是放在 HTML 公开的, 任何人都可以直接拿到.

 

Google Maps Embed API

Embed Map 就是把 Map 嵌套进网站里. 效果:

它是通过 iframe 完成的. 左上角是一个 location info. 中间有一个 drop point 就是目标地点 (通常就是公司的地址)

要制作 iframe 不需要什么 coding. 用 Generating an iframe 就可以了.

输入查询, 比如公司名字 > 点击 Looks good!

然后输入 API Key

API 在 Cloud 里面

接着 copy iframe 的 code, 放到要 display 的页面区域就可以了.

Options

想配置 config 可以通过 parameters. 参考: Embedding a map

上面我们使用了 iframe generator, 但其实它就是替我们生成 parameters 而已.

下面这个是手写的 iframe src

https://www.google.com/maps/embed/v1/place?q=place_id:ChIJcXt2BFgZ2jERY1RQlGLGTzU&zoom=10&key=your-key

通常可能需要配置的变量是: version, place_id (或者直接用 q, q stand for query), zoom, key, language. 参考: place mode

局限

Embed API 虽然简单, 但是也有不少局限性.

1. 不支持 multiple location. 它只可以放一个地点. 如果公司有许多分行. 那就不够用了.

2. marker (中间的 drop point 术语叫 marker) 没有任何点击事件. location info 在右上角并不显眼. 用户可能会点击 marker, 但却没有任何反应.

而这两个局限可以通过 Maps JavaScript API 来解决.

 

Google Maps JavaScript API

最终效果

一开始有 3 个 location, 点击 location 会出现 location info.

 

Simple Map

最终效果有几个难点, 我们先从最简单的开始.

HTML

<body>
  <div class="map"></div>
  <script type="module" src="./home.ts"></script>
</body>

有一个 div 就可以了，待会儿地图出现在 div 这个位置。

Styles

.map {
  width: 768px;
  aspect-ratio: 3 / 1;
}

div 需要设一个尺寸，地图大小。

Scripts

安装

yarn add @googlemaps/js-api-loader
yarn add @types/google.maps --dev

import and create Loader

import { Loader } from '@googlemaps/js-api-loader';

const apiKey = 'my-api-key';

// 1. 创建 loader
const loader = new Loader({
  apiKey,
  version: 'weekly', // by default 也是 'weekly'，要指定版本就放 version: '3.40'
});

Loader，顾名思义，它就是用来加载 Google Maps Library 用的。

// 2. 加载 MapsLibrary
const { Map } = await loader.importLibrary('maps');
const mapElement = document.querySelector<HTMLElement>('.map')!;

// 3. 使用 MapsLibrary 制作地图
new Map(mapElement, {
  // 4. 一定要指定位置和 zoom 哦
  center: {
    lat: 1.284491,
    lng: 103.845951,
  },
  zoom: 10,
});

我们可以选择在任意时刻去 importLibrary，它是异步的。

效果

 

Scolling Problem

默认情况下，在 map 上 scrolling 的效果是 zoom。这个体验不一定是用户期望的，因为用户 scroll 更可能是想滚动页面内容。

解决方法是在 config 添加 gestureHandling。

new Map(mapElement, {
  gestureHandling: "cooperative",
});

效果

当用户不小心 scroll 到的地图，它不会 zoom，而是会 scroll 页面内容，与此同时会出现提示，告知用户想 zoom 的话，请使用 ctrl + scroll。

 

Custom Map Styles

上面最终效果的主题颜色并不是默认的，它是灰色系的。

我们到 Google Cloud 去创建特定的 styles。

然后打开 editor

有一堆的 styles 可以调

设定好后 save & publish。

接着我们需要创建一个 Map ID。

然后把 Map ID 和 Styles 关联起来

最后记下 Map ID，并回到我们的代码，设置 Map ID。

new Map(mapElement, {
  center: {
    lat: 1.284491,
    lng: 103.845951,
  },
  zoom: 10,
  gestureHandling: 'cooperative',
  mapId : 'my-map-id' // 设置 Map ID
});

这样地图就会有自定义的 styles 了。

Styling without Google Cloud

参考：

New map styles missing global saturation option?

Google maps 3.54 adding style to the map

gmapsbook – Styles & Themes

Google Cloud 的 style editor 不是很方便，它没有提供 theme，只能一个一个小细节去调，这非常的麻烦。

我们还有一个 old school (已废弃，但还能用) 的方法，可以自定义 styles。

去这里 mapstyle.withgoogle.com 设置，然后 copy JSON

 

注：它默认的 labels.icon 会把 Singapore 给 hide 起来，所以我修改了它的 JSON file。

接着把 JSON copy paste 到代码中

const { Map, StyledMapType } = await loader.importLibrary('maps');
const mapElement = document.querySelector<HTMLElement>('.map')!;

const mapOptions: google.maps.MapOptions = {
  center: {
    lat: 1.284491,
    lng: 103.845951,
  },
  zoom: 12,
  gestureHandling: 'cooperative',
  mapId,
};

const map = new Map(mapElement, mapOptions);

const myMapStyle = new StyledMapType(
  [], // <-- put json array here
);
map.mapTypes.set('myMapStyle', myMapStyle);
map.setMapTypeId('myMapStyle');

提醒：

MapOptions.styles 是早期的设置 styles 方式，在没有设置 mapId 的情况下才可以这样设置 styles。

如果有了 mapId 就必须使用 map.setMapTypeId 来设置 styles。

mapId 不仅仅是为了 map styles，其它功能也可能需要 mapId，所以 Best Practice 是这样的：

  1. 一定要 set mapId，即便不是为了 styles，它还有其它用途

  2. 有了 mapId 就不可能使用 styles 属性，只可以使用 map.setMapTypeId

 

Places Library

参考: Docs – Places Library 

它是一个 service，可以通过 query 找到 place info。比如 query=my-company-name

它会返回坐标、地址、reviews count、reviews rating、opening hours 等等。

它有许多方法可以用来 search，但目前只用到 Find Place from Query 就足够了。 

代码

const map = new Map(mapElement, mapOptions);

const { PlacesService, PlacesServiceStatus } = await loader.importLibrary('places'); // 先 import library

const searchTerm = 'Pestline KL';
const businessName = 'Pestline Sdn Bhd - KL Branch';

const service = new PlacesService(map);
service.findPlaceFromQuery(
  {
    query: searchTerm,
    fields: ['place_id', 'geometry', 'name', 'formatted_address', 'rating', 'user_ratings_total'],
  },
  (results, status) => {
    if (status === PlacesServiceStatus.OK && results) {
      console.log('found', results.filter(result => result.name === businessName)[0]);
    }
  },
);

还有什么可用的 fields 可以参考这里

注: query=my-company-name 是有可能会找到超过 1 个 results 的哦，我会通过 filter business name 来获取准确的那一个。

效果

分别对应了 info window 需要的内容

name, formatted_address, rating, user_ratings_total

view larger map 需要 place_id

directions 则是 name + formatted_address

geometry 是给 marker 用的

注: query=my-company-name 也有可能找不到，或者找错 company 的哦。哪怕你的 query 完全等于你的 google business name 也有可能找错哦。

因为它是 query 全世界，所以可能有时候会傻傻的，一个解决方法是限制它的查询范围。

placesService.findPlaceFromQuery(
  {
    query: searchTerm,
    fields: ['place_id', 'geometry', 'name', 'formatted_address', 'rating', 'user_ratings_total'],
    // 设置 radius，限制搜索范围
    locationBias: { lat: 3.854687, lng: 102.129477, radius: 1000 * 1000 },
  },
  (results, status) => {
    if (status === PlacesServiceStatus.OK && results) {
      console.log('found', results!.filter(result => result.name === businessName)[0]);
    }
  },
);

locationBias 就是用来限制查找范围的，可以给它一个 origin 加上一个 radius 那范围就是一个圈内查找。我试过确实会比较准确一点。

 

Marker

const { AdvancedMarkerElement } = await loader.importLibrary('marker'); // 先 import library

new AdvancedMarkerElement({
  map,
  position: {
    lat: 1.284491,
    lng: 103.845951,
  },
  title: 'Uluru', // hover marker 时会出现
});

position 就拿上面 place info 的 geometry。

提醒：要使用 marker 一定要设置 mapId (上面教了) 哦。如果只是为了测试，可以使用 Map.DEMO_MAP_ID 暂时替代。

Marker Styling

参考: 

Docs – feedbackBasic marker customization

Docs – feedbackCreate markers with HTML and CSS

默认的 marker 是红色的. 通常和网站主题颜色不搭.

想改颜色的话，可以使用 PinElement

const map = new Map(mapElement, mapOptions);

const { AdvancedMarkerElement, PinElement } = await loader.importLibrary('marker');

// 创建 PinElement
const pin = new PinElement({
  // 设置喜欢的颜色
  background: 'pink',
  borderColor: 'blue',
  glyphColor: 'green',
  scale: 1.5, // 大小
});

new AdvancedMarkerElement({
  map,
  position: {
    lat: 1.284491,
    lng: 103.845951,
  },
  title: 'Uluru',
  content: pin.element, // 把 pin element 放进 content
});

效果

content 属性可以放任意的 HTMLElement，所以可以完全自定义

const img = document.createElement('img');
img.src = 'https://maps.google.com/mapfiles/kml/shapes/airports.png';

new AdvancedMarkerElement({
  map,
  position: {
    lat: 1.284491,
    lng: 103.845951,
  },
  title: 'Uluru',
  content: img,
});

放图片也行，效果：

Zoom to All Marker

上面 create map 的时候，我们 hardcode 了 center 和 zoom，这样是不 ok 的。

正确的做法是依据所有的 marker 调整 zoom，尽可能的显示所有 markers。

参考: Stack Overflow – Auto-center map with multiple markers in Google Maps API v3

const map = new Map(mapElement, {
  gestureHandling: 'cooperative',
  mapId,
  maxZoom: 10, // 避免 auto zoom 太大
});

const bounds = new google.maps.LatLngBounds();
bounds.extend({
  // 收集 marker 坐标 1
  lat: 1.284491,
  lng: 103.845951,
});
bounds.extend({
  // 收集 marker 坐标 2
  lat: 1.284491,
  lng: 103.845951,
});
map.fitBounds(bounds); // 调整 map zoom 和 center

主要用到了 LatLngBounds 和 fitBounds 方法，担心自动 zoom 太大的话，可以 set 一个 maxZoom。

 

Info Window

参考: Docs – Info Windows

const map = new Map(mapElement, mapOptions);

const { AdvancedMarkerElement } = await loader.importLibrary('marker');

const img = document.createElement('img');
img.src = 'https://maps.google.com/mapfiles/kml/shapes/airports.png';

const marker = new AdvancedMarkerElement({
  map,
  position: {
    lat: 1.284491,
    lng: 103.845951,
  },
  title: 'Uluru',
  content: img,
  gmpClickable: true,
});

// 创建 info window
const infowindow = new google.maps.InfoWindow({
  content: '<h1 class="my-h1">Hello World</h1>', // raw html 或者 HTMLElement
});

// 点击事件
marker.addListener('click', () => {
  infowindow.open({
    anchor: marker,
    map,
    shouldFocus: false,
  });
});

assign raw HTML 给 InfoWindow.content 就可以了。CSS Selector 可以直接 select 到 .map .my-h1。

 

Google Map Link

最后说一下 reviews，view larger map，directions 的 link

参考:

Stack Overflow – Link to Google Maps Directions using place_id

Stack Overflow – Getting Google Maps link from place_id

Docs – directions

reviews link

const reviewsLink = `https://search.google.com/local/reviews?placeid=${data.placeId}`

placeId 到 place info 里拿.

view larger map link

const viewLargerMapLink = `https://maps.google.com/maps?q=place_id:${data.placeId}`

directions link

const directionsLink = `https://www.google.com/maps/dir/?api=1&destination=${encodeURIComponent(
  `${data.name},${data.address}`
)}`

direction 没有用到 placeId，反而是用到了 name 和 formatted_address。

 

Get Latitude, Longitude by Address

参考: Docs – feedbackGeocoding Service

Cloud 需要 enable Geocoding API。

const { Geocoder, GeocoderStatus } = await loader.importLibrary('geocoding'); // 先 import library
const address = 'Skudai'; // can put full address or keyword e.g. city
const geocoder = new Geocoder();
geocoder.geocode({ address }, (results, status) => {
  if (status !== GeocoderStatus.OK) {
    window.alert('Get latitude longitude from Google API failure.');
    throw new Error('Get latitude longitude from Google API failure');
  }
  console.log(results![0].geometry.location.toJSON()); // { lat: 1.5343616, lng: 103.6594267}
});

不需要 map 对象，直接使用 Geocoder 就可以了。

反过来用 longitube, latitude 找 address 也是可以

const { Geocoder, GeocoderStatus } = await loader.importLibrary('geocoding');
const geocoder = new Geocoder();
geocoder.geocode({ location: { lat: 123, lng: 123 } }, (results, status) => {
  if (status === GeocoderStatus.OK) {
    const address = results![0].formatted_address;
    console.log(address);
  }
});

 

nearbySearch

参考: Docs – Nearby Search Requests

nearby 的过程是这样的

首先给它一个坐标 lat, lng

再给它一个半径 radius。比如想查询方圆百里就是 坐标 + radius 50km

最后再告诉它你要找什么，比如餐厅、酒店，甚至是一些知名公司，比如苹果专卖店等等。

const map = new Map(mapElement, mapOptions);

const { PlacesService } = await loader.importLibrary('places');
const service = new PlacesService(map);
service.nearbySearch(
  {
    location: await getLatLngAsync('Taman Universiti'), // getLatLngAsync 上面教过的
    keyword: 'KLC Language Centre', // 知名店铺
    radius: 50 * 1000, // radius 的单位是 meter, * 1000 相等于 50 km 的意思.
  },
  (result, _status) => {
    console.log(result![0].geometry!.location!.toJSON());
  },
);

1. PlacesService 依赖 map 对象, 这个上面教过了, 只是没有教 nearbySearch

2. radius 的单位是 meter

3. 返回的 result 是一个 array, 里面有许多资料, 比如公司的 reviews 等等.

 

Distance, Duration, Direction

参考: Docs – feedbackDirections Service

Cloud 需要 enable Directions API 哦。

上面搜索到了 nearby, 我们自然希望它按照距离排序, 或者显示距离. 这样用户有个谱可以选择.

const { DirectionsService } = await loader.importLibrary('routes');

const directionsService = new DirectionsService();
directionsService.route(
  {
    origin: await getLatLngAsync('Taman Universiti'),
    destination: result![0].geometry!.location!, // result from nearbySearch
    travelMode: google.maps.TravelMode.DRIVING,
  },
  (result, _status) => {
    console.log(result!.routes[0].legs[0].distance!.text); // 5.6 km
    console.log(result!.routes[0].legs[0].duration!.text); // 12 mins
  },
);

result 里面还有 steps，一步一步带你走到目的地，每个 step 里头也有距离，时间哦。

 

posted @ 2022-07-11 19:07  兴杰  阅读(784)  评论(0)  编辑  收藏  举报