بار کردن Maps JavaScript API

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

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

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

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

«میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» را با افزودن بارکننده راه‌اندازی به‌خط به کد برنامه‌تان بار کنید، همان‌طور که در تکه‌کد زیر نشان داده شده است:

<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

تابع شما همچنین می‌تواند کتابخانه‌ها را بدون تعریف متغیر برای کلاس‌های موردنیاز بار کند، که به‌ویژه اگر نقشه را بااستفاده از عنصر 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 بار نخواهد شد.

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

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

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

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

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

• authReferrerPolicy: مشتریان Maps JS می‌توانند «محدودیت‌های ارجاع‌دهنده HTTP» را در «کنسول Cloud» پیکربندی کنند تا نشانی‌های وبی را که مجاز به استفاده از «کلید میانای برنامه‌سازی کاربردی» خاصی هستند محدود کنند. به‌طور پیش‌فرض، این محدودیت‌ها را می‌توان به‌گونه‌ای پیکربندی کرد که فقط مسیرهای خاصی بتوانند از «کلید API» استفاده کنند. اگر هر نشانی وب در همان دامنه یا مبدأ می‌تواند از «کلید میانای برنامه‌سازی کاربردی» استفاده کند، می‌توانید authReferrerPolicy: "origin" را تنظیم کنید تا مقدار داده‌های ارسالی هنگام مجاز کردن درخواست‌ها از «میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» محدود شود. وقتی این پارامتر مشخص شده باشد و «محدودیت‌های ارجاع‌دهنده 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» مشخص کنید بحث می‌کند. برخی‌از پارامترها الزامی هستند و برخی دیگر اختیاری هستند. همان‌طور که در نشانی‌های وب استاندارد است، همه پارامترها بااستفاده از نویسه امپرسند (&) از هم جدا می‌شوند.

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

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»، پارامترهای زیر الزامی است.

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

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

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

• loading: استراتژی بار کردن کد که Maps JavaScript API می‌تواند استفاده کند. روی async تنظیم کنید تا نشان دهید که «میانای برنامه‌سازی کاربردی جاوا اسکریپت در Maps» به‌صورت هم‌زمان بار نشده است و هیچ کد جاوا اسکریپتی توسط رویداد 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 را با یک «میانای برنامه‌سازی کاربردی» متشکل از دو تابع، 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

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

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

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

مراحل انتقال

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

پیش‌از

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