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

โหลด Maps JavaScript API

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

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

ใช้การนําเข้าคลังแบบไดนามิก

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

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

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

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

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

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

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

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

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

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

ก่อน

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