Places UI Kit: ไลบรารีที่พร้อมใช้งานซึ่งช่วยให้นักพัฒนาซอฟต์แวร์ปรับแต่งและควบคุมได้ ลองใช้ดู แล้วแชร์ความคิดเห็นเกี่ยวกับประสบการณ์การใช้ UI Kit

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

โหลด Maps JavaScript API

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

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

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

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

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

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

async function initMap() {
  await google.maps.importLibrary("maps");
  await 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 สามารถกำหนดค่าข้อจำกัดของผู้อ้างอิง HTTP ใน Cloud Console เพื่อจำกัด URL ที่ได้รับอนุญาตให้ใช้คีย์ API ที่เฉพาะเจาะจงได้ โดยค่าเริ่มต้น ข้อจำกัดเหล่านี้สามารถกำหนดค่าให้อนุญาตเฉพาะบางเส้นทางในการใช้คีย์ API ได้ หาก URL ใดก็ตามในโดเมนหรือต้นทางเดียวกันอาจใช้คีย์ API คุณสามารถตั้งค่า authReferrerPolicy: "origin" เพื่อจำกัดปริมาณข้อมูลที่ส่งเมื่อให้สิทธิ์คำขอจาก Maps JavaScript API ได้ เมื่อระบุพารามิเตอร์นี้และเปิดใช้ข้อจำกัดของผู้อ้างอิง HTTP ใน Cloud Console แล้ว Maps JavaScript API จะโหลดได้ก็ต่อเมื่อมีข้อจำกัดของผู้อ้างอิง HTTP ที่ตรงกับโดเมนของเว็บไซต์ปัจจุบันโดยไม่มีการระบุเส้นทาง
mapIds: อาร์เรย์ของรหัสแผนที่ ทำให้ระบบโหลดการกำหนดค่าสำหรับรหัสแผนที่ที่ระบุไว้ล่วงหน้า การระบุรหัสแผนที่ที่นี่ไม่จำเป็นสำหรับการใช้งานรหัสแผนที่ แต่มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการปรับแต่งประสิทธิภาพเครือข่ายอย่างละเอียด
channel: ดูการติดตามการใช้งานต่อช่อง

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

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

พารามิเตอร์ที่จำเป็น (โดยตรง) {:.hide-from-toc}

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

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

พารามิเตอร์ที่ไม่บังคับ (โดยตรง) {:.hide-from-toc}

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

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 ใน Cloud Console แล้ว Maps JavaScript API จะโหลดได้ก็ต่อเมื่อมีข้อจำกัดของผู้อ้างอิง HTTP ที่ตรงกับโดเมนของเว็บไซต์ปัจจุบันโดยไม่มีการระบุเส้นทาง
map_ids: รายการรหัสแผนที่โดยคั่นด้วยคอมมา ทำให้ระบบโหลดการกำหนดค่าสำหรับรหัสแผนที่ที่ระบุไว้ล่วงหน้า การระบุรหัสแผนที่ที่นี่ไม่จำเป็นสำหรับการใช้งานรหัสแผนที่ แต่มีไว้สำหรับนักพัฒนาแอปที่ต้องการปรับแต่งประสิทธิภาพเครือข่ายอย่างละเอียด
channel: ดูการติดตามการใช้งานต่อช่อง

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

เคล็ดลับ: การเปิดตัว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

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

TypeScript

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

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

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 = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

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