بار کردن Maps JavaScript API

این راهنما به شما نشان می‌دهد که چگونه Maps JavaScript API را بار کنید. سه راه برای انجام این کار وجود دارد:

• از وارد کردن کتابخانه پویا استفاده کنید
• از برچسب بار کردن مستقیم دستورگان استفاده کنید
• از بسته NPM js-api-loader استفاده کنید

استفاده از «وارد کردن کتابخانه پویا»

وارد کردن کتابخانه پویا امکان بار کردن کتابخانه‌ها را در زمان اجرا فراهم می‌کند. این به شما امکان می‌دهد کتابخانه‌های موردنیاز را در زمانی که به آن‌ها نیاز دارید درخواست کنید، نه همه را یک‌باره در زمان بار کردن. همچنین از بارگیری چندباره میانای برنامه‌سازی کاربردی جاوا اسکریپت «نقشه‌ها» در صفحه‌تان محافظت می‌کند.

با افزودن بارگذار خودراه‌انداز به‌خط به کد برنامه‌تان، 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>

همچنین می‌توانید کد بارگذار خودراه‌انداز را مستقیماً به کد جاوا اسکریپت خود اضافه کنید.

برای بار کردن کتابخانه‌ها در زمان اجرا، از اپراتور 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

وقتی برنامه‌تان به‌طور هم‌زمان به چند کتابخانه نیاز دارد، از Promise.all() برای درخواست موازی آن‌ها استفاده کنید:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

از تماس با await google.maps.importLibrary() در خطوط جداگانه به‌صورت متوالی خودداری کنید. بیانیه‌های متوالی await اجرای کد را تا زمانی‌که هر کتابخانه بارگیری و مقداردهی اولیه را تمام کند مسدود می‌کند، سپس کتابخانه بعدی را درخواست می‌کند و آبشاری از شبکه ایجاد می‌کند که زمان بار را افزایش می‌دهد. ‫Promise.all() همه بارگیری‌های کتابخانه را به‌طور هم‌زمان شروع می‌کند و به‌محض آماده شدن همه آن‌ها، حل می‌شود.

تابع شما همچنین می‌تواند کتابخانه‌ها را بدون اعلام متغیر برای کلاس‌های موردنیاز بارگیری کند، که به‌ویژه اگر نقشه‌ای را بااستفاده از عنصر gmp-map اضافه کرده باشید مفید است. بدون متغیر باید از مسیرهای واجدشرایط استفاده کنید، برای مثال google.maps.Map:

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

async function initMap() {
  await Promise.all([
    google.maps.importLibrary("maps"),
    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: کلید میانای برنامه‌سازی کاربردی شما. تا زمانی که کلید میانای برنامه‌سازی کاربردی معتبری مشخص نشود، Maps JavaScript API بار نخواهد شد.

پارامترهای اختیاری

• v: نسخه Maps JavaScript API برای بار کردن. اگر کانال یا نسخه‌ای را به‌طور صریح مشخص نکنید، به‌طور پیش‌فرض کانال هفتگی را دریافت خواهید کرد. اگر از طرح ممتاز منتقل شده‌اید و به‌طور صریح کانال یا نسخه‌ای را مشخص نکرده‌اید، به‌طور پیش‌فرض کانال فصلی را دریافت خواهید کرد. اگر نسخه نامعتبری را مشخص کنید، کانال پیش‌فرض خود را دریافت خواهید کرد. بیشتر بدانید.

• libraries: آرایه‌ای از Maps JavaScript API اضافی کتابخانه‌ها برای شروع پیش‌بارگیری. مشخص کردن مجموعه ثابتی از کتابخانه‌ها معمولاً توصیه نمی‌شود، اما برای توسعه‌دهندگانی که می‌خواهند رفتار ذخیره‌سازی نهان را در وب‌سایتشان به‌دقت تنظیم کنند دردسترس است. هنوز هم مهم است که قبل‌از استفاده، با google.maps.importLibrary() برای هر کتابخانه انتخاب‌شده تماس بگیرید.

• language: زبان مورد استفاده. این موضوع بر نام کنترل‌ها، اعلامیه‌های حق نشر، مسیرهای رانندگی، و برچسب‌های کنترل، و پاسخ به درخواست‌های سرویس تأثیر می‌گذارد. فهرست زبان‌های پشتیبانی‌شده را ببینید.

• region: کد منطقه برای استفاده. این کار رفتار میانای برنامه‌سازی کاربردی را براساس کشور یا قلمرو داده‌شده تغییر می‌دهد.

• authReferrerPolicy: مشتریان Maps JS می‌توانند «محدودیت‌های ارجاع‌دهنده HTTP» را در «کنسول Cloud» پیکربندی کنند تا نشانی‌های وبی را که مجاز به استفاده از «کلید میانای برنامه‌سازی کاربردی» خاصی هستند محدود کنند. به‌طور پیش‌فرض، این محدودیت‌ها را می‌توان به‌گونه‌ای پیکربندی کرد که فقط به مسیرهای خاصی اجازه استفاده از «کلید API» را بدهد. اگر هر نشانی وبی در همان دامنه یا مبدأ می‌تواند از «کلید میانای برنامه‌سازی کاربردی» استفاده کند، می‌توانید authReferrerPolicy: "origin" را تنظیم کنید تا مقدار داده‌های ارسال‌شده هنگام مجاز کردن درخواست‌ها از Maps JavaScript API را محدود کنید. وقتی این پارامتر مشخص شده باشد و «محدودیت‌های ارجاع‌دهنده HTTP» در Cloud Console فعال باشد، Maps JavaScript API فقط درصورتی می‌تواند بار شود که محدودیت ارجاع‌دهنده HTTP وجود داشته باشد که با دامنه وب‌سایت فعلی بدون مسیر مشخص‌شده مطابقت داشته باشد.

• ‫mapIds: آرایه‌ای از شناسه‌های نقشه. باعث می‌شود پیکربندی شناسه‌های نقشه مشخص‌شده پیش‌بارگیری شود. مشخص کردن شناسه‌های نقشه در اینجا برای استفاده از شناسه‌های نقشه الزامی نیست، اما برای توسعه‌دهندگانی که می‌خواهند عملکرد شبکه را به‌دقت تنظیم کنند دردسترس است.

• channel: پیگیری استفاده به ازای هر کانال را ببینید.

استفاده از برچسب بارگیری مستقیم دستورگان

این بخش نحوه استفاده از برچسب بار کردن مستقیم اسکریپت را نشان می‌دهد. ازآنجایی‌که اسکریپت مستقیم کتابخانه‌ها را هنگام بارگیری نقشه بارگیری می‌کند، می‌تواند نقشه‌های ایجادشده بااستفاده از عنصر gmp-map را با حذف نیاز به درخواست صریح کتابخانه‌ها در زمان اجرا ساده کند. ازآنجایی‌که برچسب بار کردن مستقیم اسکریپت همه کتابخانه‌های درخواستی را به‌محض بار شدن اسکریپت بار می‌کند، ممکن است عملکرد برخی‌از برنامه‌ها تحت تأثیر قرار گیرد. برچسب بار کردن مستقیم اسکریپت را فقط یک‌بار در هر بارگیری صفحه اضافه کنید.

توجه: پس‌از اینکه برچسب بارگیری مستقیم دستورگان بارگیری شد، می‌توانید با importLibrary تماس بگیرید.

افزودن برچسب دستورگان

برای بار کردن Maps JavaScript API به‌صورت درون‌خطی در فایل HTML، برچسب script را همان‌طور که در زیر نشان داده شده است اضافه کنید.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

پارامترهای نشانی وب بار کردن مستقیم دستورگان

این بخش همه پارامترهایی را که می‌توانید در رشته پُرسمان نشانی وب بارگیری اسکریپت هنگام بارگیری Maps JavaScript API مشخص کنید، مورد بحث قرار می‌دهد. برخی پارامترها الزامی هستند، درحالی‌که برخی دیگر اختیاری‌اند. همان‌طور که در نشانی‌های وب استاندارد است، همه پارامترها بااستفاده از نویسه امپرسند (&) از هم جدا می‌شوند.

نشانی وب نمونه زیر دارای جای‌بان‌هایی برای همه پارامترهای ممکن است:

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"

نشانی وب در برچسب 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 بار نمی‌شود.

پارامترهای اختیاری (مستقیم) {:.hide-from-toc}

از این پارامترها برای درخواست نسخه خاصی از Maps JavaScript API، بار کردن کتابخانه‌های اضافی، بومی‌سازی نقشه، یا مشخص کردن خط‌مشی بررسی ارجاع‌دهنده HTTP استفاده کنید

• loading: استراتژی بار کردن کد که Maps JavaScript API می‌تواند استفاده کند. روی async تنظیم کنید تا نشان دهد که Maps JavaScript API به‌صورت همگام بار نشده است و هیچ کد جاوا اسکریپتی توسط رویداد load دستورگان راه‌اندازی نشده است. اکیداً توصیه می‌شود که برای بهبود عملکرد، این مقدار را هر زمان که ممکن بود روی async تنظیم کنید. (به‌جای آن، از پارامتر callback برای انجام کنش‌ها هنگام دردسترس بودن میانای برنامه‌سازی کاربردی جاوا اسکریپت در Maps استفاده کنید.) از نسخه ۳.۵۵ دردسترس است.

• callback: نام تابع سراسری که باید پس‌از بار شدن کامل Maps JavaScript API فراخوانی شود.

• v: نسخه Maps JavaScript API برای استفاده.

• ‫libraries: فهرست جداشده با کاما از Maps JavaScript API کتابخانه‌های اضافی برای بار کردن.

• language: زبان موردنظر برای استفاده. این امر بر نام کنترل‌ها، اعلامیه‌های حق نشر، مسیرهای رانندگی، و برچسب‌های کنترل، و همچنین پاسخ به درخواست‌های سرویس تأثیر می‌گذارد. فهرست زبان‌های پشتیبانی‌شده را ببینید.

• region: کد منطقه برای استفاده. این کار رفتار میانای برنامه‌سازی کاربردی را براساس کشور یا قلمرو داده‌شده تغییر می‌دهد.

• auth_referrer_policy: مشتریان می‌توانند «محدودیت‌های ارجاع‌دهنده HTTP» را در «کنسول ابری» پیکربندی کنند تا نشانی‌های وبی را که مجاز به استفاده از «کلید API» خاصی هستند محدود کنند. به‌طور پیش‌فرض، این محدودیت‌ها را می‌توان به‌گونه‌ای پیکربندی کرد که فقط مسیرهای خاصی بتوانند از «کلید API» استفاده کنند. اگر هر نشانی وب در همان دامنه یا مبدأ می‌تواند از «کلید میانای برنامه‌سازی کاربردی» استفاده کند، می‌توانید auth_referrer_policy=origin را تنظیم کنید تا مقدار داده‌های ارسالی هنگام مجاز کردن درخواست‌های «میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» را محدود کند. این ویژگی از نسخه ۳.۴۶ دردسترس است. وقتی این پارامتر مشخص شده باشد و «محدودیت‌های ارجاع‌دهنده HTTP» در «کنسول Cloud» فعال باشد، «میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» فقط درصورتی می‌تواند بار شود که محدودیت ارجاع‌دهنده HTTP وجود داشته باشد که با دامنه وب‌سایت فعلی بدون مسیر مشخص‌شده مطابقت داشته باشد.

• map_ids: فهرست شناسه‌های نقشه که با کاما از هم جدا شده‌اند. باعث می‌شود پیکربندی شناسه‌های نقشه مشخص‌شده پیش‌بارگیری شود. مشخص کردن شناسه‌های نقشه در اینجا برای استفاده از شناسه‌های نقشه الزامی نیست، اما برای توسعه‌دهندگانی که می‌خواهند عملکرد شبکه را به‌طور دقیق تنظیم کنند دردسترس است.

• channel: ردیابی استفاده براساس کانال را ببینید.

استفاده از بسته NPM js-api-loader

نکته: نسخه v2.0.0 یک بازسازی کد عمده است که کلاس قدیمی Loader را با یک API متشکل از دو تابع 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

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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

بارکننده از «وعده‌ها» برای دردسترس قرار دادن کتابخانه‌ها استفاده می‌کند. کتابخانه‌ها را بااستفاده از روش importLibrary() بار کنید. مثال زیر نحوه استفاده از بارکننده برای بار کردن نقشه را نشان می‌دهد:

TypeScript

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

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

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

JavaScript

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

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 را پوشش می‌دهد.

مراحل انتقال

ابتدا برچسب بارگذاری مستقیم دستورگان را با برچسب بارگذار خودراه‌انداز درون‌خطی جایگزین کنید.

پیش‌از

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

بار کردن چند کتابخانه

برای بار کردن بیش‌از یک کتابخانه، از Promise.all() برای درخواست کتابخانه‌ها به‌صورت موازی و ساختارزدایی کلاس‌های برگردانده‌شده استفاده کنید:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

کتابخانه‌ها را به‌صورت سریالی با زنجیر کردن عبارت‌های await جداگانه بار نکنید:

// Avoid loading libraries serially:
const { Place } = await google.maps.importLibrary('places');
const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

وقتی await هر importLibrary() تماس را پشت سر هم انجام می‌دهید، درخواست دوم کتابخانه تا زمانی که کتابخانه اول به‌طور کامل بارگیری و مقداردهی اولیه نشده باشد، شروع نمی‌شود. استفاده از Promise.all() همه درخواست‌های کتابخانه را به‌طور هم‌زمان آغاز می‌کند و درنتیجه تأخیر شبکه کاهش می‌یابد و سرعت راه‌اندازی اولیه بهبود می‌یابد.