ภาพรวม

เลือกแพลตฟอร์ม: 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>
ดูตัวอย่าง

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

แม้จะเป็นตัวอย่างง่ายๆ นี้ แต่มี 2-3 อย่างที่ควรทราบ ได้แก่

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

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

โหลด Maps JavaScript API

เราแนะนำให้ใช้เครื่องมือโหลด Bootstrap สำหรับโหลด 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();

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 และโค้ดเรียกกลับ ข้อมูลต่อไปนี้แสดงการใช้เมธอด 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> ด้วย

กำลังโหลด 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,
  });
});

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 สัมพันธ์กับแผนที่ของโลกที่ซูมออกอย่างเต็มที่ และระดับการซูมที่กว้างขึ้นและมีความละเอียดสูงกว่า

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 ดูหลักเกณฑ์การโพสต์คำถามที่ดีได้ในหน้าการสนับสนุน