اعلامیه: سبک نقشه پایه جدید به زودی به پلتفرم نقشه های گوگل می آید. این به‌روزرسانی برای استایل نقشه شامل یک پالت رنگی پیش‌فرض جدید، پین‌های مدرن شده و بهبودهایی در تجربه‌ها و قابلیت استفاده از نقشه است. همه سبک‌های نقشه به‌طور خودکار در مارس 2025 به‌روزرسانی می‌شوند. برای اطلاعات بیشتر در مورد در دسترس بودن و نحوه انتخاب زودتر، به سبک نقشه جدید برای پلتفرم Google Maps مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

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

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

تابع شما همچنین می‌تواند کتابخانه‌ها را بدون اعلام متغیری برای کلاس‌های مورد نیاز بارگیری کند، که مخصوصاً اگر نقشه‌ای را با استفاده از عنصر gmp-map اضافه کنید مفید است:

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

از طرف دیگر، می‌توانید کتابخانه‌ها را مستقیماً در HTML بارگذاری کنید، همانطور که در اینجا نشان داده شده است:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

نحوه انتقال به API بارگیری کتابخانه پویا را بیاموزید.

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

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

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

v : نسخه Maps JavaScript API برای بارگیری.
libraries : فهرستی از کتابخانه‌های اضافی Maps JavaScript API جدا شده با کاما برای بارگیری. تعیین مجموعه ثابتی از کتابخانه ها به طور کلی توصیه نمی شود، اما برای توسعه دهندگانی که می خواهند رفتار حافظه پنهان را در وب سایت خود به خوبی تنظیم کنند، در دسترس است.
language : زبان مورد استفاده. این روی نام کنترل‌ها، اعلامیه‌های حق نسخه‌برداری، مسیرهای رانندگی، و برچسب‌های کنترلی و پاسخ‌ها به درخواست‌های خدمات تأثیر می‌گذارد. لیست زبان های پشتیبانی شده را ببینید.
region : کد منطقه ای برای استفاده. این رفتار نقشه را بر اساس یک کشور یا قلمرو مشخص تغییر می دهد.
authReferrerPolicy : مشتریان Maps JS می توانند محدودیت های ارجاع دهنده HTTP را در کنسول Cloud پیکربندی کنند تا URL ها مجاز به استفاده از یک کلید API خاص را محدود کنند. به‌طور پیش‌فرض، این محدودیت‌ها را می‌توان به گونه‌ای پیکربندی کرد که فقط به مسیرهای خاصی اجازه استفاده از کلید API را بدهد. اگر هر URL در همان دامنه یا مبدأ ممکن است از کلید API استفاده کند، می‌توانید authReferrerPolicy: "origin" را برای محدود کردن مقدار داده‌های ارسالی هنگام تأیید درخواست‌ها از Maps JavaScript API تنظیم کنید. وقتی این پارامتر مشخص شود و محدودیت‌های ارجاع‌دهنده HTTP در کنسول Cloud فعال باشد، Maps JavaScript API تنها در صورتی می‌تواند بارگیری شود که محدودیت ارجاع‌دهنده HTTP وجود داشته باشد که با دامنه وب‌سایت فعلی بدون مسیر مشخص مطابقت داشته باشد.
mapIds : آرایه ای از شناسه های نقشه. باعث می شود پیکربندی شناسه های نقشه مشخص شده از قبل بارگیری شود.
channel : به ردیابی استفاده در هر کانال مراجعه کنید.
solutionChannel : پلتفرم نقشه های گوگل انواع مختلفی از کدهای نمونه را برای کمک به شما در راه اندازی و اجرای سریع ارائه می دهد. برای پیگیری پذیرش نمونه‌های کد پیچیده‌تر ما و بهبود کیفیت راه‌حل، Google پارامتر query solutionChannel را در فراخوانی‌های API در کد نمونه ما قرار می‌دهد.

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

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

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

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

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

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

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

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

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

loading : استراتژی بارگذاری کد که Maps JavaScript API می تواند استفاده کند. برای نشان دادن اینکه Maps JavaScript API به طور همزمان بارگیری نشده است و هیچ کد جاوا اسکریپتی توسط رویداد load اسکریپت فعال نمی شود، روی async تنظیم کنید. برای بهبود عملکرد، توصیه می شود هر زمان که ممکن است، این را به async تنظیم کنید. (به جای آن از پارامتر callback برای انجام اقدامات زمانی که Maps JavaScript API در دسترس است استفاده کنید.) از نسخه 3.55 در دسترس است.
callback : نام یک تابع سراسری که پس از بارگیری کامل Maps JavaScript API فراخوانی می شود.
v : نسخه Maps JavaScript API برای استفاده.
libraries : فهرستی از کتابخانه‌های اضافی Maps JavaScript API جدا شده با کاما برای بارگیری.
language : زبان مورد استفاده. این روی نام کنترل‌ها، اعلامیه‌های حق نسخه‌برداری، مسیرهای رانندگی و برچسب‌های کنترلی و همچنین پاسخ‌ها به درخواست‌های خدمات تأثیر می‌گذارد. لیست زبان های پشتیبانی شده را ببینید.
region : کد منطقه ای برای استفاده. این رفتار نقشه را بر اساس یک کشور یا قلمرو مشخص تغییر می دهد.
auth_referrer_policy : مشتریان می توانند محدودیت های ارجاع دهنده HTTP را در کنسول Cloud پیکربندی کنند تا URL ها مجاز به استفاده از یک کلید API خاص را محدود کنند. به‌طور پیش‌فرض، این محدودیت‌ها را می‌توان به گونه‌ای پیکربندی کرد که فقط به مسیرهای خاصی اجازه استفاده از کلید API را بدهد. اگر هر URL در همان دامنه یا مبدأ ممکن است از کلید API استفاده کند، می‌توانید auth_referrer_policy=origin را برای محدود کردن مقدار داده‌های ارسال شده هنگام تأیید درخواست‌ها از Maps JavaScript API تنظیم کنید. این از نسخه 3.46 در دسترس است. وقتی این پارامتر مشخص شود و محدودیت‌های ارجاع‌دهنده HTTP در کنسول Cloud فعال باشد، Maps JavaScript API تنها در صورتی می‌تواند بارگیری شود که محدودیت ارجاع‌دهنده HTTP وجود داشته باشد که با دامنه وب‌سایت فعلی بدون مسیر مشخص مطابقت داشته باشد.
mapIds : فهرستی از شناسه نقشه جدا شده با کاما. باعث می شود پیکربندی شناسه های نقشه مشخص شده از قبل بارگیری شود.
channel : به ردیابی استفاده در هر کانال مراجعه کنید.
solution_channel : پلتفرم نقشه های گوگل انواع مختلفی از کدهای نمونه را برای کمک به شما در راه اندازی و اجرای سریع ارائه می دهد. برای پیگیری پذیرش نمونه‌های کد پیچیده‌تر ما و بهبود کیفیت راه‌حل، Google پارامتر query solution_channel را در فراخوانی‌های API در کد نمونه ما قرار می‌دهد.
توجه: این پارامتر پرس و جو برای استفاده توسط Google است. برای اطلاعات بیشتر به پارامتر راه حل های پلتفرم نقشه های گوگل مراجعه کنید.

از بسته 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 را ببینید.

مثال زیر استفاده از loader.importLibrary() را برای بارگیری کتابخانه ها نشان می دهد:

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

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

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