หน้านี้ได้รับการแปลโดย Cloud Translation API

โหลด Maps JavaScript API

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

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

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

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

โหลด Maps JavaScript API โดยการเพิ่มโปรแกรมโหลดการเริ่มต้นแบบอินไลน์ ลงในโค้ดของแอปพลิเคชัน ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

<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) ได้ ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้

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();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 เพิ่มเติมที่จะโหลด โดยทั่วไปเราไม่แนะนำให้ระบุชุดไลบรารีที่แน่นอน แต่ก็มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการปรับแต่งลักษณะการทำงานของการแคชในเว็บไซต์อย่างละเอียด
language: ภาษาที่จะใช้ ซึ่งจะส่งผลต่อชื่อของตัวควบคุม ประกาศเกี่ยวกับลิขสิทธิ์ เส้นทางการขับรถ และป้ายกำกับตัวควบคุม รวมถึงการตอบกลับคำขอบริการ ดูรายการภาษาที่รองรับ
region: รหัสภูมิภาค ที่จะใช้ ซึ่งจะเปลี่ยนลักษณะการทำงานของ API ตามประเทศหรือ เขตแดนที่ระบุ
authReferrerPolicy: ลูกค้า Maps JS สามารถกำหนดค่าข้อจำกัดของ HTTP Referrer ใน Cloud Console เพื่อจำกัด URL ที่ได้รับอนุญาตให้ใช้คีย์ API ที่เฉพาะเจาะจง โดยค่าเริ่มต้น คุณสามารถกำหนดค่าข้อจำกัดเหล่านี้เพื่ออนุญาตให้ใช้คีย์ API เฉพาะเส้นทางบางเส้นทางเท่านั้น หาก URL ใดก็ตามในโดเมนหรือต้นทางเดียวกัน อาจใช้คีย์ API คุณสามารถตั้งค่า authReferrerPolicy: "origin" เพื่อจำกัด ปริมาณข้อมูลที่ส่งเมื่อให้สิทธิ์คำขอจาก Maps JavaScript API เมื่อระบุพารามิเตอร์นี้และเปิดใช้ข้อจํากัดของ HTTP Referrer ใน Cloud Console แล้ว Maps JavaScript API จะโหลดได้ก็ต่อเมื่อมีข้อจํากัดของ HTTP Referrer ที่ตรงกับโดเมนของเว็บไซต์ปัจจุบันโดยไม่ได้ระบุเส้นทาง
mapIds: อาร์เรย์ของรหัสแผนที่ ทำให้ระบบโหลดการกำหนดค่าสำหรับรหัสแผนที่ที่ระบุไว้ล่วงหน้า คุณไม่จำเป็นต้องระบุรหัสแผนที่ที่นี่เพื่อใช้รหัสแผนที่ แต่มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการปรับแต่งประสิทธิภาพเครือข่าย อย่างละเอียด
channel: ดูการติดตามการใช้งานต่อช่อง
solutionChannel: Google Maps Platform มีโค้ดตัวอย่างหลายประเภท ที่จะช่วยให้คุณเริ่มต้นใช้งานได้อย่างรวดเร็ว Google จะรวมพารามิเตอร์การค้นหา solutionChannel ไว้ในการเรียก API ในโค้ดตัวอย่างของเราเพื่อติดตามการนำโค้ดตัวอย่างที่ซับซ้อนมากขึ้นไปใช้และปรับปรุงคุณภาพของโซลูชัน

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

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

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

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

หมายเหตุ: พารามิเตอร์การค้นหานี้มีไว้ให้ Google ใช้ ดูข้อมูลเพิ่มเติมได้ที่พารามิเตอร์โซลูชัน Google Maps Platform

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

แพ็กเกจ @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,
  });
});index.ts

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,
  });
});
index.js

ดูตัวอย่างที่ใช้ js-api-loader

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

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

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

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

ขั้นตอนการย้ายข้อมูล

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

ก่อน

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