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

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

استفاده از Dynamic Library Import

همانطور که در قطعه زیر نشان داده شده است، 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 استفاده کنید، همانطور که در مثال کد زیر نشان داده شده است:

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

جاوا اسکریپت

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

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

  • key : کلید API شما. Maps JavaScript API بارگیری نمی‌شود مگر اینکه یک کلید API معتبر مشخص شود.

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

  • v : نسخه Maps JavaScript API برای بارگیری.

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

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

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

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

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

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

بسته @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

جاوا اسکریپت

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

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

برچسب بارگیری اسکریپت قدیمی هنوز پشتیبانی می شود. این بخش برای پشتیبانی از ادغام با استفاده از برچسب بارگذاری اسکریپت قدیمی ارائه شده است. Google مهاجرت به API بارگیری کتابخانه پویا را تشویق می کند.

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

برای بارگیری Maps JavaScript API inline در یک فایل HTML، یک تگ script مانند شکل زیر اضافه کنید.

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

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

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

URL مثال زیر دارای متغیرهایی برای همه پارامترهای ممکن است:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"

URL موجود در تگ script مثال زیر، Maps JavaScript API را بارگیری می کند:

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

پارامترهای مورد نیاز (میراث)

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

  • key : کلید API شما. Maps JavaScript API بارگیری نمی‌شود مگر اینکه یک کلید API معتبر مشخص شود.

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

پارامترهای اختیاری (میراث)

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

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

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

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

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

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

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

به Dynamic Library Import API مهاجرت کنید

این بخش مراحل مورد نیاز برای انتقال ادغام شما برای استفاده از Dynamic Library Import API را پوشش می دهد.

مراحل مهاجرت

ابتدا تگ بارگذاری اسکریپت قدیمی را با تگ بارگذار بوت استرپ داخلی جایگزین کنید.

قبل از

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&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();