รับ Maps Demo Key: ทดลองใช้ฟีเจอร์บางอย่างของ Maps JavaScript API และ Places UI Kit โดยไม่มีค่าใช้จ่ายด้วย Maps Demo Key โดยไม่ต้องระบุข้อมูลสำหรับการเรียกเก็บเงิน

Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

โหลด Maps JavaScript API

คู่มือนี้จะแสดงวิธีโหลด Maps JavaScript API ซึ่งทำได้ 3 วิธีดังนี้

ใช้การนําเข้าไลบรารีแบบไดนามิก
ใช้แท็กการโหลดสคริปต์โดยตรง
ใช้แพ็กเกจ js-api-loader ของ NPM

ใช้การนำเข้าไลบรารีแบบไดนามิก

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

โหลด 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>

นอกจากนี้ คุณยังเพิ่มโค้ดตัวโหลด Bootstrap ลงในโค้ด JavaScript ได้โดยตรงด้วย

หากต้องการโหลดไลบรารีที่รันไทม์ ให้ใช้โอเปอเรเตอร์ await เพื่อเรียก importLibrary() จากภายในฟังก์ชัน async การประกาศตัวแปรสำหรับคลาสที่จำเป็นช่วยให้คุณข้ามการใช้เส้นทางที่สมบูรณ์ (เช่น google.maps.Map) ได้ ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();index.js

เมื่อแอปพลิเคชันของคุณต้องการไลบรารีหลายรายการพร้อมกัน ให้ใช้ Promise.all() เพื่อขอไลบรารีเหล่านั้นพร้อมกัน

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

หลีกเลี่ยงการเรียกใช้ await google.maps.importLibrary() ในบรรทัดแยกกันตามลำดับ คำสั่ง await ตามลำดับจะบล็อกการดำเนินการจนกว่าไลบรารีแต่ละรายการจะดาวน์โหลดและเริ่มต้นเสร็จสิ้นก่อนที่จะขอไลบรารีถัดไป ซึ่งจะสร้าง Waterfall ของเครือข่ายที่เพิ่มเวลาในการโหลด Promise.all() จะเริ่มดาวน์โหลดไลบรารีทั้งหมดพร้อมกันและจะแก้ไขทันทีที่ไลบรารีทั้งหมดพร้อมใช้งาน

นอกจากนี้ ฟังก์ชันยังโหลดไลบรารีได้โดยไม่ต้องประกาศตัวแปรสำหรับคลาสที่จำเป็น ซึ่งจะเป็นประโยชน์อย่างยิ่งหากคุณเพิ่มแผนที่โดยใช้องค์ประกอบ gmp-map หากไม่มีตัวแปร คุณต้องใช้เส้นทางที่สมบูรณ์ เช่น google.maps.Map

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await Promise.all([
    google.maps.importLibrary("maps"),
    google.maps.importLibrary("marker"),
  ]);

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

หรือจะโหลดไลบรารีใน HTML โดยตรงก็ได้ ดังที่แสดงที่นี่

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

ดูวิธีย้ายข้อมูลไปยัง Dynamic Library Loading API

พารามิเตอร์ที่จำเป็น

key: คีย์ API ของคุณ Maps JavaScript API จะไม่โหลดเว้นแต่จะมีการระบุคีย์ API ที่ถูกต้อง

พารามิเตอร์ที่ไม่บังคับ

v: เวอร์ชันของ Maps JavaScript API ที่จะโหลด หากคุณไม่ได้ระบุช่องทางหรือเวอร์ชันอย่างชัดเจน คุณจะได้รับช่องทางรายสัปดาห์โดยค่าเริ่มต้น หากคุณย้ายข้อมูลจากแพ็กเกจพรีเมียมและไม่ได้ระบุเวอร์ชันหรือช่องทางอย่างชัดเจน คุณจะได้รับช่องทางรายไตรมาสโดยค่าเริ่มต้น หากระบุเวอร์ชันที่ไม่ถูกต้อง คุณจะได้รับช่องเริ่มต้น ดูข้อมูลเพิ่มเติม
libraries: อาร์เรย์ของไลบรารี Maps JavaScript API เพิ่มเติมเพื่อเริ่มโหลดล่วงหน้า โดยทั่วไปเราไม่แนะนำให้ระบุชุดไลบรารีแบบคงที่ แต่มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการปรับแต่งลักษณะการทำงานของการแคชในเว็บไซต์อย่างละเอียด คุณยังคงต้องเรียกใช้ google.maps.importLibrary() สำหรับไลบรารีที่เลือกแต่ละรายการก่อนใช้งาน
language: ภาษาที่จะใช้ ซึ่งจะส่งผลต่อชื่อของตัวควบคุม การแจ้งเตือนลิขสิทธิ์ เส้นทางการขับขี่ และป้ายกำกับตัวควบคุม รวมถึงการตอบกลับคำขอบริการ ดูรายการภาษาที่รองรับ
region: รหัสภูมิภาคที่จะใช้ ซึ่งจะเปลี่ยนลักษณะการทำงานของ API ตามประเทศหรือเขตแดนที่ระบุ
authReferrerPolicy: ลูกค้า Maps JS สามารถกำหนดค่าการจำกัด URL ที่มาของ HTTP ใน Cloud Console เพื่อจำกัด URL ที่ได้รับอนุญาตให้ใช้คีย์ API หนึ่งๆ โดยค่าเริ่มต้น ข้อจำกัดเหล่านี้สามารถกำหนดค่าให้อนุญาตเฉพาะบางเส้นทางเท่านั้นที่ใช้คีย์ API ได้ หาก URL ใดก็ตามในโดเมนหรือต้นทางเดียวกันอาจใช้คีย์ API คุณสามารถตั้งค่า authReferrerPolicy: "origin" เพื่อจำกัดปริมาณข้อมูลที่ส่งเมื่อให้สิทธิ์คำขอจาก Maps JavaScript API เมื่อระบุพารามิเตอร์นี้และเปิดใช้ข้อจำกัด HTTP Referrer ใน Cloud Console แล้ว Maps JavaScript API จะโหลดได้ก็ต่อเมื่อมีข้อจำกัด HTTP Referrer ที่ตรงกับโดเมนของเว็บไซต์ปัจจุบันโดยไม่มีการระบุเส้นทาง
mapIds: อาร์เรย์ของรหัสแผนที่ ทำให้ระบบโหลดการกำหนดค่าสำหรับรหัสแผนที่ที่ระบุไว้ล่วงหน้า คุณไม่จำเป็นต้องระบุรหัสแผนที่ที่นี่เพื่อใช้รหัสแผนที่ แต่มีไว้สำหรับนักพัฒนาแอปที่ต้องการปรับแต่งประสิทธิภาพเครือข่ายอย่างละเอียด
channel: ดูการติดตามการใช้งานต่อช่องทาง

ใช้แท็กการโหลดสคริปต์โดยตรง

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

เพิ่มแท็กสคริปต์

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

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

พารามิเตอร์ของ URL สำหรับการโหลดสคริปต์โดยตรง

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

ตัวอย่าง URL ต่อไปนี้มีตัวยึดตำแหน่งสำหรับพารามิเตอร์ที่เป็นไปได้ทั้งหมด

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

URL ในแท็ก script ตัวอย่างต่อไปนี้จะโหลด Maps JavaScript API

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

พารามิเตอร์ที่จำเป็น (โดยตรง)

ต้องระบุพารามิเตอร์ต่อไปนี้เมื่อโหลด Maps JavaScript API

key: คีย์ API ของคุณ Maps JavaScript API จะไม่โหลดเว้นแต่จะมีการระบุคีย์ API ที่ถูกต้อง

พารามิเตอร์ที่ไม่บังคับ (โดยตรง)

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

loading: กลยุทธ์การโหลดโค้ดที่ Maps JavaScript API ใช้ได้ ตั้งค่าเป็น async เพื่อระบุว่า Maps JavaScript API ไม่ได้โหลดแบบซิงโครนัส และไม่มีโค้ด JavaScript ที่ทริกเกอร์โดยเหตุการณ์ load ของสคริปต์ เราขอแนะนำอย่างยิ่งให้ตั้งค่านี้เป็น async ทุกครั้งที่ทำได้ เพื่อประสิทธิภาพที่ดีขึ้น (ใช้พารามิเตอร์ callback แทนเพื่อดำเนินการเมื่อ Maps JavaScript API พร้อมใช้งาน) พร้อมใช้งานตั้งแต่เวอร์ชัน 3.55 เป็นต้นไป
callback: ชื่อของฟังก์ชันส่วนกลางที่จะเรียกใช้เมื่อ Maps JavaScript API โหลดเสร็จสมบูรณ์
v: เวอร์ชันของ Maps JavaScript API ที่จะใช้
libraries: รายการไลบรารี Maps JavaScript API เพิ่มเติมที่คั่นด้วยคอมมาที่จะโหลด
language: ภาษาที่จะใช้ ซึ่งจะส่งผลต่อชื่อของตัวควบคุม การแจ้งเตือนลิขสิทธิ์ เส้นทางการขับขี่ และป้ายกำกับตัวควบคุม รวมถึงการตอบกลับคำขอบริการ ดูรายการภาษาที่รองรับ
region: รหัสภูมิภาคที่จะใช้ ซึ่งจะเปลี่ยนลักษณะการทำงานของ API ตามประเทศหรือเขตแดนที่ระบุ
auth_referrer_policy: ลูกค้าสามารถกำหนดค่าการจำกัดผู้อ้างอิง HTTP ใน Cloud Console เพื่อจำกัด URL ที่ได้รับอนุญาตให้ใช้คีย์ API หนึ่งๆ โดยค่าเริ่มต้น คุณสามารถกำหนดค่าข้อจำกัดเหล่านี้เพื่ออนุญาตให้เฉพาะบางเส้นทางใช้คีย์ API ได้ หาก URL ใดๆ ในโดเมนหรือต้นทางเดียวกันอาจใช้คีย์ API คุณสามารถตั้งค่า auth_referrer_policy=origin เพื่อจำกัดปริมาณข้อมูลที่ส่งเมื่อให้สิทธิ์คำขอจาก Maps JavaScript API ซึ่งพร้อมใช้งานตั้งแต่เวอร์ชัน 3.46 เป็นต้นไป เมื่อระบุพารามิเตอร์นี้และเปิดใช้ข้อจำกัด HTTP Referrer ใน Cloud Console แล้ว Maps JavaScript API จะโหลดได้ก็ต่อเมื่อมีข้อจำกัด HTTP Referrer ที่ตรงกับโดเมนของเว็บไซต์ปัจจุบันโดยไม่มีการระบุเส้นทาง
map_ids: รายการรหัสแผนที่ที่คั่นด้วยคอมมา ทำให้ระบบโหลดการกำหนดค่าสำหรับรหัสแผนที่ที่ระบุไว้ล่วงหน้า การระบุรหัสแผนที่ที่นี่ไม่จำเป็นสำหรับการใช้รหัสแผนที่ แต่มีไว้สำหรับนักพัฒนาแอปที่ต้องการปรับแต่งประสิทธิภาพเครือข่ายอย่างละเอียด
channel: ดูการติดตามการใช้งานต่อช่องทาง

ใช้แพ็กเกจ js-api-loader ของ NPM

เคล็ดลับ: รุ่น v2.0.0 เป็นการเปลี่ยนโครงสร้างภายในโค้ดครั้งใหญ่ที่แทนที่คลาส Loader เดิมด้วย API ที่ประกอบด้วย 2 ฟังก์ชัน ได้แก่ setOptions() และ importLibrary() การเปลี่ยนแปลงนี้ช่วยให้คุณโหลดไลบรารี Maps API แต่ละรายการแบบไดนามิกได้ตามต้องการ โดยเลื่อนการดาวน์โหลดฟีเจอร์ออกไปเพื่อปรับปรุงประสิทธิภาพของหน้าเว็บในตอนแรก

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

npm install @googlemaps/js-api-loader

นำเข้าแพ็กเกจตามที่แสดงที่นี่

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';index.ts

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';index.js

ตัวโหลดใช้ Promises เพื่อทำให้ไลบรารีพร้อมใช้งาน โหลดไลบรารีโดยใช้เมธอด importLibrary() ตัวอย่างต่อไปนี้แสดงการใช้ Loader เพื่อโหลดแผนที่

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();index.ts

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map'), mapOptions);
}

void init();index.js

ดูโค้ดตัวอย่างที่สมบูรณ์

ย้ายข้อมูลไปยัง Dynamic Library Import API

ส่วนนี้จะอธิบายขั้นตอนที่จำเป็นในการย้ายข้อมูลการผสานรวมเพื่อใช้ Dynamic Library Import API

ขั้นตอนการย้ายโปรเจ็กต์

ก่อนอื่น ให้แทนที่แท็กการโหลดสคริปต์โดยตรงด้วยแท็กตัวโหลด Bootstrap ในบรรทัด

ก่อน

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

หลัง

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

ถัดไป ให้อัปเดตโค้ดของแอปพลิเคชันโดยทำดังนี้

เปลี่ยนฟังก์ชัน initMap() เป็นแบบอะซิงโครนัส
เรียกใช้ importLibrary() เพื่อโหลดและเข้าถึงไลบรารีที่ต้องการ

ก่อน

let map;

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

window.initMap = initMap;

หลัง

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();

โหลดไลบรารีหลายรายการ

หากต้องการโหลดไลบรารีมากกว่า 1 รายการ ให้ใช้ Promise.all() เพื่อขอไลบรารีพร้อมกันและแยกโครงสร้างคลาสที่แสดงผล ดังนี้

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

อย่าโหลดไลบรารีแบบอนุกรมโดยเชื่อมโยงคำสั่ง await แยกกัน ดังนี้

// Avoid loading libraries serially:
const { Place } = await google.maps.importLibrary('places');
const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

เมื่อคุณawaitการเรียก importLibrary() แต่ละครั้งต่อกัน คำขอไลบรารีที่ 2 จะไม่เริ่มจนกว่าไลบรารีแรกจะดาวน์โหลดและเริ่มต้นเสร็จสมบูรณ์ การใช้ Promise.all() จะเริ่มต้นคำขอไลบรารีทั้งหมดพร้อมกัน ซึ่งจะช่วยลดเวลาในการตอบสนองของเครือข่ายและเพิ่มความเร็วในการเริ่มต้น