ประกาศด้านความปลอดภัย: เราตระหนักถึงปัญหาด้านความปลอดภัยที่อาจส่งผลกระทบต่อเว็บไซต์ที่ใช้ไลบรารีของบุคคลที่สามบางรายการ (รวมถึง polyfill.io) บางครั้งปัญหานี้อาจเปลี่ยนเส้นทางผู้เข้าชมออกจากเว็บไซต์ที่ตั้งใจไว้โดยที่เจ้าของเว็บไซต์ไม่ทราบหรือไม่อนุญาต ก่อนหน้านี้ตัวอย่าง JavaScript จำนวนมากของเรามีการประกาศสคริปต์ polyfill.io เราได้นำสิ่งนี้ออกจากตัวอย่างของเราแล้ว หากคุณใช้ตัวอย่าง JavaScript ที่มีการประกาศนี้ เราขอแนะนำให้นำการประกาศออก

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

โหลด 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 Loader ลงในโค้ด JavaScript โดยตรงได้ด้วย

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

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  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,
  });
}

initMap();index.ts

JavaScript

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 ดังนี้

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

หรือคุณสามารถโหลดไลบรารีโดยตรงใน HTML ตามที่แสดงที่นี่

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

ดูวิธีย้ายข้อมูลไปยัง API การโหลดไลบรารีแบบไดนามิก

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

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

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

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