بار کردن 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>

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

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

پارامترهای الزامی (مستقیم)

پارامترهای زیر هنگام بار کردن Maps JavaScript API لازم است.

• key: کلید میانای برنامه‌سازی کاربردی شما. تا زمانی که کلید میانای برنامه‌سازی کاربردی معتبری مشخص نشده باشد، «میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» بار نمی‌شود.

پارامترهای اختیاری (مستقیم)

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

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

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

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

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

بارکننده از Promises برای دردسترس قرار دادن کتابخانه‌ها استفاده می‌کند. کتابخانه‌ها را بااستفاده از روش 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

کد نمونه کامل را ببینید.

انتقال به «میانای برنامه‌سازی کاربردی وارد کردن کتابخانه پویا»

این بخش مراحل لازم برای انتقال یکپارچه‌سازی شما به استفاده از «میانای برنامه‌سازی کاربردی وارد کردن کتابخانه پویا» را پوشش می‌دهد.

مراحل انتقال

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

پیش‌از

<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() همه درخواست‌های کتابخانه را به‌طور هم‌زمان آغاز می‌کند و درنتیجه تأخیر شبکه کاهش می‌یابد و سرعت راه‌اندازی اولیه بهبود می‌یابد.