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

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

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

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

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

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

از بسته 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
});

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

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

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

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

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

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

مراحل مهاجرت

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

قبل از

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