ภาพรวม

เลือกแพลตฟอร์ม: Android iOS JavaScript

Maps JavaScript API ช่วยให้ปรับแต่งแผนที่ด้วยเนื้อหาและภาพของคุณเองเพื่อแสดงบนหน้าเว็บและอุปกรณ์เคลื่อนที่ได้ Maps JavaScript API มีแผนที่พื้นฐาน 4 ประเภท (โรดแมป ดาวเทียม ไฮบริด และภูมิประเทศ) ที่คุณแก้ไขได้โดยใช้เลเยอร์และรูปแบบ การควบคุมและเหตุการณ์ รวมถึงบริการและไลบรารีต่างๆ

ผู้ชม

เอกสารประกอบนี้ออกแบบมาสำหรับผู้ที่คุ้นเคยกับแนวคิดการเขียนโปรแกรมเชิงโปรแกรมและออบเจ็กต์ของ JavaScript คุณควรทำความคุ้นเคยกับ Maps จากมุมมองของผู้ใช้ด้วย มีบทแนะนำ JavaScript มากมายบนเว็บ

เอกสารเชิงแนวคิดนี้ออกแบบมาเพื่อช่วยให้คุณเริ่มสำรวจและพัฒนาแอปพลิเคชันด้วย Maps JavaScript API ได้อย่างรวดเร็ว รวมถึงเผยแพร่เอกสารอ้างอิง Maps JavaScript API ด้วย

สวัสดีทุกคน

วิธีที่ง่ายที่สุดในการเริ่มดูข้อมูลเกี่ยวกับ Maps JavaScript API คือการดูตัวอย่างง่ายๆ ตัวอย่างต่อไปนี้แสดงแผนที่ที่มีศูนย์กลางอยู่ที่ซิดนีย์ นิวเซาท์เวลส์ ออสเตรเลีย

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

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

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

style.css

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html
ดูตัวอย่าง

ลองใช้ตัวอย่าง

ถึงตัวอย่างง่ายๆ นี้ แต่ก็ยังมีสิ่งที่ควรทราบอยู่ 2-3 อย่าง

  1. เราประกาศแอปพลิเคชันเป็น HTML5 โดยใช้การประกาศ <!DOCTYPE html>
  2. เราสร้างองค์ประกอบ div ที่ชื่อ "map" เพื่อเก็บแผนที่
  3. เรากำหนดฟังก์ชัน JavaScript ที่สร้างแผนที่ใน div
  4. เราโหลด Maps JavaScript API โดยใช้ Booter Loader

โดยจะอธิบายขั้นตอนเหล่านี้ด้านล่าง

โหลด Maps JavaScript API

เครื่องมือโหลด Bootstrapped เป็นวิธีที่แนะนำในการโหลด Maps JavaScript API นอกจากนี้ ยังมีตัวโหลด JS API ไว้เป็นทางเลือกด้วย เราขอแนะนำให้คุณตรวจสอบทั้ง 2 วิธี แล้วเลือกวิธีที่เหมาะกับโครงสร้างของโค้ดในโปรเจ็กต์มากที่สุด

ดูรายละเอียดเพิ่มเติมได้ที่โหลด Maps JavaScript API

ตัวโหลด Bootstrap

โหลด Maps JavaScript API ด้วยการเพิ่มตัวโหลด Bootstrap แบบอินไลน์ลงในโค้ดของแอปพลิเคชัน ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

หากต้องการโหลดไลบรารีในรันไทม์ ให้ใช้โอเปอเรเตอร์ await เพื่อเรียกใช้ importLibrary() จากภายในฟังก์ชันอะซิงโครนัสตามที่แสดงไว้ที่นี่

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

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

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.js

แพ็กเกจ NPM js-api-loader

ใช้ @googlemaps/js-api-loader เพื่อใช้ NPM ในการโหลด Maps JavaScript API ติดตั้งผ่าน NPM โดยใช้คำสั่งต่อไปนี้

npm install @googlemaps/js-api-loader

สามารถนำเข้าแพ็กเกจนี้ไปยังแอปพลิเคชันด้วย:

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

ตัวโหลดแสดงอินเทอร์เฟซ Promise และโค้ดเรียกกลับ ข้อมูลต่อไปนี้แสดงการใช้งานเมธอด Promise เริ่มต้น load()

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

ประกาศแอปพลิเคชันของคุณเป็น HTML5

เราขอแนะนําให้คุณประกาศ DOCTYPE ที่แท้จริงภายในเว็บแอปพลิเคชัน ในตัวอย่างด้านล่างนี้ เราได้ประกาศแอปพลิเคชันของเราเป็น HTML5 โดยใช้ HTML5 แบบง่าย DOCTYPE ดังที่แสดงด้านล่าง

<!DOCTYPE html>

เบราว์เซอร์ปัจจุบันส่วนใหญ่จะแสดงผลเนื้อหาที่มีการประกาศด้วย DOCTYPE นี้ใน "โหมดมาตรฐาน" ซึ่งหมายความว่าแอปพลิเคชันของคุณควรเป็นไปตามข้อกำหนดข้ามเบราว์เซอร์มากกว่า นอกจากนี้ DOCTYPE ยังออกแบบมาให้มีประสิทธิภาพลดลงด้วย โดยเบราว์เซอร์ที่ไม่เข้าใจจะไม่สนใจเบราว์เซอร์นี้ และใช้ "โหมดที่ไม่มาตรฐาน" เพื่อแสดงเนื้อหาของตัวเอง

โปรดทราบว่า CSS บางส่วนที่ทำงานในโหมดไม่มาตรฐานไม่สามารถใช้ได้ในโหมดมาตรฐาน กล่าวอย่างเจาะจงคือ ขนาดแบบเปอร์เซ็นต์ทั้งหมดจะต้องรับค่ามาจากองค์ประกอบบล็อกระดับบนสุด และหากองค์ประกอบระดับบนเหล่านั้นระบุขนาดไม่ได้ ระบบจะถือว่ามีขนาดเป็น 0 x 0 พิกเซล ด้วยเหตุนี้ เราจึงรวมการประกาศ <style> ต่อไปนี้

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

การประกาศ CSS นี้ระบุว่าคอนเทนเนอร์แผนที่ <div> (ที่มีรหัส map) ควรใช้พื้นที่ไม่เกิน 100% ของความสูงของเนื้อหา HTML โปรดทราบว่าเราต้องประกาศเปอร์เซ็นต์เหล่านี้โดยเฉพาะสำหรับ <body> และ <html> ด้วย

การโหลด Maps JavaScript API

Maps JavaScript API โหลดโดยใช้แท็ก script ซึ่งสามารถเพิ่มในหน้าในไฟล์ HTML หรือใส่ในแบบไดนามิกโดยใช้ไฟล์ JavaScript แยกต่างหาก เราขอแนะนำให้คุณอ่านทั้ง 2 วิธี แล้วเลือกวิธีที่เหมาะกับโครงสร้างของโค้ดในโปรเจ็กต์มากที่สุด

การโหลดในบรรทัด

หากต้องการโหลด Maps JavaScript API แบบในหน้าในไฟล์ HTML ให้เพิ่มแท็ก script ดังที่แสดงด้านล่าง

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

การโหลดแบบไดนามิก

หากต้องการโหลด Maps JavaScript API ในบรรทัดแบบไดนามิกโดยใช้ไฟล์ JavaScript แยกต่างหาก โปรดดูตัวอย่างด้านล่าง วิธีนี้ทำให้คุณจัดการโค้ดทั้งหมดสำหรับการทำงานกับ API จากไฟล์ .js ที่แยกต่างหากได้ และเทียบเท่ากับการเพิ่มแท็กสคริปต์ในหน้า

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

การโหลดแบบไดนามิก

แพ็กเกจ @googlemaps/js-api-loader พร้อมให้ใช้งานเพื่อมอบประสบการณ์การโหลดแบบไดนามิกที่ราบรื่นยิ่งขึ้น โดยสามารถติดตั้งผ่าน NPM ได้ดังนี้

npm install @googlemaps/js-api-loader

สามารถนำเข้าแพ็กเกจนี้ไปยังแอปพลิเคชันด้วย:

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

ตัวโหลดแสดงอินเทอร์เฟซ Promise และโค้ดเรียกกลับ ข้อมูลต่อไปนี้แสดงการใช้งานเมธอด Promise เริ่มต้น load()

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

แอตทริบิวต์แท็กสคริปต์

สังเกตในตัวอย่างด้านบนว่ามีการตั้งค่าแอตทริบิวต์หลายรายการในแท็ก script ซึ่งเป็นรายการที่แนะนำ คำอธิบายของแต่ละแอตทริบิวต์มีดังนี้

  • src: URL ที่ใช้โหลด Maps JavaScript API รวมถึงสัญลักษณ์และคำจำกัดความทั้งหมดที่จำเป็นสำหรับการใช้ Maps JavaScript API URL ในตัวอย่างนี้มีพารามิเตอร์ 2 ตัว ได้แก่ key ซึ่งใช้ระบุคีย์ API และ callback ที่ใช้ระบุชื่อฟังก์ชันส่วนกลางที่จะเรียกใช้เมื่อ Maps JavaScript API โหลดเสร็จสมบูรณ์ อ่านเพิ่มเติมเกี่ยวกับพารามิเตอร์ของ URL
  • async: ขอให้เบราว์เซอร์ดาวน์โหลดแบบอะซิงโครนัสและเรียกใช้สคริปต์ เมื่อระบบเรียกใช้สคริปต์ สคริปต์จะเรียกฟังก์ชันที่ระบุโดยใช้พารามิเตอร์ callback

ห้องสมุด

ขณะโหลด Maps JavaScript API ผ่าน URL คุณอาจเลือกโหลดไลบรารีเพิ่มเติมได้โดยใช้โอเปอเรเตอร์ await เพื่อเรียกใช้ importLibrary() จากภายในฟังก์ชันแบบไม่พร้อมกัน ไลบรารีคือโมดูลโค้ดที่มีฟังก์ชันการทำงานเพิ่มเติมสำหรับ Maps JavaScript API หลัก แต่จะไม่มีการโหลด เว้นแต่คุณจะขออย่างเจาะจง ดูข้อมูลเพิ่มเติมได้ที่ ไลบรารีใน Maps JavaScript API

องค์ประกอบ DOM ของแผนที่

<div id="map"></div>

เพื่อให้แผนที่แสดงในหน้าเว็บ เราต้องจองพื้นที่สำหรับแผนที่นั้น โดยปกติเราจะดําเนินการด้วยการสร้างองค์ประกอบ div ที่มีชื่อ และรับการอ้างอิงถึงองค์ประกอบนี้ในโมเดลออบเจ็กต์เอกสาร (DOM) ของเบราว์เซอร์

ในตัวอย่างด้านบน เราใช้ CSS เพื่อกำหนดความสูงของ div ของแมปเป็น "100%" ซึ่งจะขยายให้พอดีกับขนาดบนอุปกรณ์เคลื่อนที่ คุณอาจต้องปรับค่าความกว้างและความสูงตามขนาดหน้าจอและระยะห่างจากขอบของเบราว์เซอร์ โปรดทราบว่า div ส่วนใหญ่จะใช้ความกว้างจากองค์ประกอบที่มี และ div ที่ว่างเปล่ามักจะมีความสูงเป็น 0 ด้วยเหตุนี้ คุณจึงต้องกำหนดความสูงใน <div> อย่างชัดแจ้งเสมอ

ตัวเลือกแผนที่

มีตัวเลือกที่จำเป็น 2 รายการสำหรับทุกแผนที่ ได้แก่ center และ zoom

map = new Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

ระดับการซูม

ความละเอียดเริ่มต้นที่จะแสดงแผนที่จะกำหนดโดยคุณสมบัติ zoom โดยการซูม 0 จะสอดคล้องกับแผนที่ของโลกที่ซูมออกอย่างเต็มที่ และระดับการซูมที่ใหญ่ขึ้นจะมีความละเอียดสูงกว่า

zoom: 8

การนำเสนอแผนที่ของทั้งโลกเป็นภาพเดียวอาจต้องใช้แผนที่ขนาดมหึมาหรือแผนที่ขนาดเล็กที่มีความละเอียดต่ำมาก ด้วยเหตุนี้ รูปภาพแผนที่ภายใน Google Maps และ Maps JavaScript API จะแบ่งออกเป็น "ไทล์" แผนที่และ "ระดับการซูม" ในระดับการซูมต่ำ ชุดชิ้นส่วนแผนที่ขนาดเล็กจะครอบคลุมพื้นที่กว้าง ส่วนในระดับการซูมที่สูงขึ้น ชิ้นส่วนแผนที่จะมีความละเอียดสูงกว่าและครอบคลุมพื้นที่ที่เล็กลง ระดับความละเอียดโดยประมาณที่คุณคาดว่าจะเห็นในแต่ละระดับการซูมมีดังนี้

  • 1: โลก
  • 5: ผืนดินขนาดใหญ่/ทวีป
  • 10: เมือง
  • 15: ถนน
  • 20: อาคาร

ภาพ 3 ภาพต่อไปนี้แสดงตำแหน่งเดียวกันของโตเกียวที่ระดับการซูม 0, 7 และ 18

ดูข้อมูลเกี่ยวกับวิธีโหลดชิ้นส่วนแผนที่ JavaScript API ตามระดับการซูมปัจจุบันได้ในคู่มือพิกัดแผนที่และชิ้นส่วนแผนที่

ออบเจ็กต์แผนที่

map = new Map(document.getElementById("map"), {...});

คลาส JavaScript ที่แสดงแผนที่คือคลาส Map วัตถุคลาสนี้จะกำหนดแผนที่เดียวในหน้าเว็บ (คุณสร้างอินสแตนซ์ของคลาสนี้ได้มากกว่า 1 รายการ โดยแต่ละออบเจ็กต์จะกำหนดแผนที่แยกกันในหน้า) เราสร้างอินสแตนซ์ใหม่ของคลาสนี้โดยใช้โอเปอเรเตอร์ new ของ JavaScript

เมื่อสร้างอินสแตนซ์แผนที่ใหม่ คุณจะต้องระบุองค์ประกอบ HTML <div> ในหน้าเว็บเป็นคอนเทนเนอร์สำหรับแผนที่ โหนด HTML เป็นองค์ประกอบย่อยของออบเจ็กต์ document ของ JavaScript และเราได้รับการอ้างอิงถึงองค์ประกอบนี้ผ่านเมธอด document.getElementById()

โค้ดนี้จะกำหนดตัวแปร (ชื่อ map) และกำหนดตัวแปรนั้นให้กับออบเจ็กต์ Map ใหม่ ฟังก์ชัน Map() เรียกว่าตัวสร้าง และคำจำกัดความแสดงอยู่ด้านล่าง

ผู้ผลิต คำอธิบาย
Map(mapDiv:Node, opts?:MapOptions ) สร้างแผนที่ใหม่ภายในคอนเทนเนอร์ HTML ที่กำหนด ซึ่งโดยทั่วไปจะเป็นองค์ประกอบ DIV โดยใช้พารามิเตอร์ (ไม่บังคับ) ที่ส่งผ่าน

การแก้ปัญหา

คีย์ API และข้อผิดพลาดในการเรียกเก็บเงิน

ในบางกรณี ระบบอาจแสดงแผนที่ที่มืดหรือภาพ Street View "เชิงลบ" ซึ่งมีข้อความระบุว่า "สำหรับการพัฒนาเท่านั้น" แสดงลายน้ำ ลักษณะการทำงานนี้มักบ่งบอกถึงปัญหาเกี่ยวกับคีย์ API หรือการเรียกเก็บเงิน หากต้องการใช้ผลิตภัณฑ์ Google Maps Platform คุณต้องเปิดใช้การเรียกเก็บเงินในบัญชี และคำขอทั้งหมดต้องมีคีย์ API ที่ถูกต้อง ขั้นตอนต่อไปนี้จะช่วยแก้ปัญหานี้ได้

หากรหัสของคุณใช้ไม่ได้ ให้ทำดังนี้

เพื่อช่วยให้คุณทำให้โค้ดแผนที่ทำงานได้สำเร็จ Brendan Kenny และ Mano Marks จึงได้ชี้ให้เห็นถึงข้อผิดพลาดที่พบบ่อยและวิธีแก้ไขในวิดีโอนี้

  • มองหาการพิมพ์ผิด โปรดทราบว่า JavaScript เป็นภาษาที่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
  • ตรวจสอบข้อมูลเบื้องต้น - ปัญหาที่พบได้ทั่วไปส่วนใหญ่เกิดจากการสร้างแผนที่ครั้งแรก เช่น
    • ยืนยันว่าคุณระบุพร็อพเพอร์ตี้ zoom และ center ในตัวเลือกแผนที่
    • ตรวจสอบว่าคุณได้ประกาศองค์ประกอบ div ที่แผนที่จะปรากฏบนหน้าจอแล้ว
    • ตรวจสอบว่าองค์ประกอบ div สำหรับแผนที่มีความสูง โดยค่าเริ่มต้น องค์ประกอบ div จะสร้างขึ้นโดยมีความสูงเป็น 0 ดังนั้นจะมองไม่เห็น
    ดูตัวอย่างสำหรับการใช้ข้อมูลอ้างอิง
  • ใช้โปรแกรมแก้ไขข้อบกพร่อง JavaScript เพื่อช่วยระบุปัญหา อย่างเช่นปัญหาที่มีในเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ Chrome เริ่มต้นด้วยการหาข้อผิดพลาดในคอนโซล JavaScript
  • โพสต์คำถามไปยัง Stack Overflow ดูหลักเกณฑ์เกี่ยวกับการโพสต์คำถามที่ดีได้ในหน้าการสนับสนุน