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> <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>
ลองใช้ตัวอย่าง
แม้ในตัวอย่างง่ายๆ นี้ ยังมีบางสิ่งที่ควรทราบ:
- เราประกาศแอปพลิเคชันเป็น HTML5 โดยใช้การประกาศ
<!DOCTYPE html>
- เราสร้างเอลิเมนต์
div
ชื่อ "แผนที่" เพื่อเก็บแผนที่ - เรากำหนดฟังก์ชัน JavaScript ที่สร้างแผนที่ใน
div
- เราโหลด Maps JavaScript API โดยใช้ตัวโหลด Bootstrap
โดยจะอธิบายขั้นตอนเหล่านี้ด้านล่าง
โหลด 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();
แพ็กเกจ js-api-loader ของ NPM
ใช้ @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>
โดยเฉพาะด้วย
กำลังโหลด 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 และ 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 โหลดเสร็จสมบูรณ์ อ่านเพิ่มเติมเกี่ยวกับพารามิเตอร์ของ URLasync
: ขอให้เบราว์เซอร์ดาวน์โหลดและเรียกใช้สคริปต์แบบไม่พร้อมกัน เมื่อเรียกใช้สคริปต์ สคริปต์จะเรียกใช้ฟังก์ชันที่ระบุโดยใช้พารามิเตอร์callback
ห้องสมุด
ขณะโหลด Maps JavaScript API ผ่าน URL คุณเลือกที่จะโหลดไลบรารีเพิ่มเติมได้โดยใช้โอเปอเรเตอร์ await
เพื่อเรียกใช้ importLibrary()
จากภายในฟังก์ชันอะซิงโครนัส ไลบรารีคือโมดูลของโค้ดที่มอบฟังก์ชันเพิ่มเติมให้กับ Maps JavaScript API หลักแต่ไม่โหลดขึ้นมา เว้นแต่คุณจะขออย่างเจาะจง ดูข้อมูลเพิ่มเติมได้ที่
ไลบรารีใน Maps JavaScript API
แมปองค์ประกอบ DOM
<div id="map"></div>
เพื่อให้แผนที่แสดงบนหน้าเว็บ เราต้องจองพื้นที่สำหรับแผนที่นั้น
โดยทั่วไปเราจะทำโดยการสร้างองค์ประกอบ div
ที่มีชื่อ และรับการอ้างอิงองค์ประกอบนี้ใน Document Object Model (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 และ Maps JavaScript API จึงแบ่งออกเป็น "ไทล์" และ "ระดับการซูม" ของแผนที่ ในระดับการซูมต่ำ ชิ้นส่วนแผนที่ชุดเล็กๆ จะครอบคลุมพื้นที่กว้าง ในระดับการซูมที่สูงขึ้น ชิ้นส่วนแผนที่จะมีความละเอียดสูงและครอบคลุมพื้นที่ที่เล็กกว่า ระดับความละเอียดโดยประมาณที่คุณคาดว่าจะเห็นในแต่ละระดับการซูมมีดังนี้
- 1: โลก
- 5: ผืนดินขนาดใหญ่/ทวีป
- 10: เมือง
- 15: ถนน
- 20: อาคาร
รูปภาพ 3 ภาพต่อไปนี้แสดงสถานที่เดียวกันในโตเกียวที่ระดับการซูม 0, 7 และ 18
สำหรับข้อมูลเกี่ยวกับวิธีที่ Maps 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 ดูหลักเกณฑ์เกี่ยวกับวิธีโพสต์คำถามที่ยอดเยี่ยมได้ในหน้าการสนับสนุน