Maps JavaScript API را بارگیری کنید

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

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

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

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

API جاوا اسکریپت 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>

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

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

بیاموزید که چگونه به API بارگذاری کتابخانه پویا مهاجرت کنید .

پارامترهای مورد نیاز

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

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

• v : نسخه API جاوا اسکریپت Maps که باید بارگذاری شود.

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

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

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

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

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

• channel : به ردیابی میزان مصرف در هر کانال مراجعه کنید.

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

از تگ بارگذاری مستقیم اسکریپت استفاده کنید

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

اضافه کردن تگ اسکریپت

برای بارگذاری API جاوا اسکریپت Maps به صورت درون‌خطی در یک فایل HTML، یک تگ script مانند زیر اضافه کنید.

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

پارامترهای URL بارگذاری مستقیم اسکریپت

این بخش به بررسی تمام پارامترهایی می‌پردازد که می‌توانید در رشته‌ی جستجوی URL بارگذاری اسکریپت هنگام بارگذاری API جاوا اسکریپت Maps مشخص کنید. برخی پارامترها الزامی و برخی دیگر اختیاری هستند. طبق استاندارد 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 مثال زیر، API جاوا اسکریپت Maps را بارگذاری می‌کند:

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

پارامترهای مورد نیاز (مستقیم) {:.hide-from-toc}

پارامترهای زیر هنگام بارگذاری API جاوا اسکریپت Maps مورد نیاز هستند.

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

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

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

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

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

• v : نسخه API جاوا اسکریپت Maps که قرار است استفاده شود.

• libraries : فهرستی از کتابخانه‌های API جاوااسکریپت Maps اضافی که باید بارگذاری شوند و با ویرگول از هم جدا شده‌اند.

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

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

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

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

• channel : به ردیابی میزان مصرف در هر کانال مراجعه کنید.

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

از بسته‌ی NPM js-api-loader استفاده کنید

بسته @googlemaps/js-api-loader برای بارگیری با استفاده از مدیر بسته NPM در دسترس است. آن را با استفاده از دستور زیر نصب کنید:

npm install @googlemaps/js-api-loader

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

import { setOptions, importLibrary } from "@googlemaps/js-api-loader"

لودر از Promises برای در دسترس قرار دادن کتابخانه‌ها استفاده می‌کند. کتابخانه‌ها با متد importLibrary() بارگذاری می‌شوند. مثال زیر کلاس Map را بارگذاری می‌کند:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader";

setOptions({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
});

importLibrary("maps").then(({ Map }) => {
  new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}).catch(e => {
  // do something
});

همچنین می‌توانید async / await در یک تابع async استفاده کنید. این مثال کتابخانه‌های اضافی را بارگذاری می‌کند:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader";

setOptions({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
});

const { Map } = await importLibrary("maps");
const { AdvancedMarkerElement } = await importLibrary("marker");
const map = new Map(document.getElementById("map"), {
  center: { lat: -34.397, lng: 150.644 },
  zoom: 8,
});
const marker = new AdvancedMarkerElement({
  map,
  position: { lat: -34.397, lng: 150.644 },
});
const { PlaceAutocompleteElement } = await importLibrary("places");
await google.maps.importLibrary("places");
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
document.body.append(placeAutocomplete);

نمونه‌ای از js-api-loader را ببینید.

مهاجرت به کتابخانه پویا (Dynamic Library Import API)

این بخش مراحل مورد نیاز برای انتقال یکپارچه‌سازی شما به منظور استفاده از 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();