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

โหลด 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 initMap() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');
    // Create the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;
}
initMap();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: ดูการติดตามการใช้งานตามช่อง

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

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

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: ดูการติดตามการใช้งานตาม ช่อง.
internal_usage_attribution_ids: รายการรหัสการระบุแหล่งที่มาของการใช้งานที่คั่นด้วยคอมมา ซึ่งช่วยให้ Google เข้าใจว่าไลบรารีและตัวอย่างใดมีประโยชน์ต่อนักพัฒนาซอฟต์แวร์ เช่น การใช้งานไลบรารีการจัดกลุ่มเครื่องหมาย หากต้องการไม่ส่งรหัสการระบุแหล่งที่มาของการใช้งาน คุณสามารถลบพร็อพเพอร์ตี้นี้หรือแทนที่ค่าด้วยสตริงว่างได้อย่างปลอดภัย ระบบจะส่งเฉพาะค่าที่ไม่ซ้ำกัน ดูข้อมูลเพิ่มเติมได้ที่ พารามิเตอร์โซลูชัน Google Maps Platform

หมายเหตุ: พารามิเตอร์ solution_channel ยังคงใช้ได้ แต่เราไม่แนะนำให้ใช้ ให้ใช้ internal_usage_attribution_ids แทน

ใช้แพ็กเกจ 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

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

TypeScript

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

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

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

    // 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.
    const map = new Map(
        document.getElementById('map') as HTMLElement,
        mapOptions
    );
}

initMap();index.ts

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';
async function initMap() {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });
    // 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.
    const map = new Map(document.getElementById('map'), mapOptions);
}
initMap();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();