ภาพรวม

เลือกแพลตฟอร์ม: 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();

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();

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;
}

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>
ดูตัวอย่าง

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

แม้จะมีตัวอย่างง่ายๆ นี้ สิ่งที่ควรทราบมีดังต่อไปนี้

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

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

โหลด Maps JavaScript API

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

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

ตัวโหลดการเปิดเครื่อง

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

<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_HERE",
    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();

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();

แพ็กเกจ 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 และ Callback ข้อมูลต่อไปนี้แสดงการใช้วิธีการเริ่มต้นของ 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,
  });
});

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,
  });
});

ประกาศแอปพลิเคชันของคุณว่าเป็น 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> โดยเฉพาะด้วย

กําลังโหลด JavaScript API ของ Maps

โหลด 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&callback=initMap">
</script>

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

หากต้องการโหลดแผนที่ 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 และ Callback ข้อมูลต่อไปนี้แสดงการใช้วิธีการเริ่มต้นของ 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,
  });
});

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,
  });
});

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

โปรดสังเกตในตัวอย่างข้างต้นว่าแอตทริบิวต์หลายรายการได้รับการตั้งค่าในแท็ก 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 สอดคล้องกับแผนที่ของ Earth ซึ่งมีการซูมเข้าออกโดยสมบูรณ์ ส่วนระดับการซูมที่ใหญ่กว่าจะซูมเข้าที่ความละเอียดสูงขึ้น

zoom: 8

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

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

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

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

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

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

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

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

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

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

การแก้ปัญหา

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

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

หากรหัสใช้ไม่ได้ ให้ทําดังนี้

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

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