بررسی اجمالی

پلتفرم را انتخاب کنید: Android iOS JavaScript

Maps JavaScript API به شما امکان می دهد نقشه ها را با محتوا و تصاویر خود برای نمایش در صفحات وب و دستگاه های تلفن همراه سفارشی کنید. Maps JavaScript API دارای چهار نوع نقشه اصلی (نقشه راه، ماهواره، ترکیبی و زمین) است که می‌توانید با استفاده از لایه‌ها و سبک‌ها، کنترل‌ها و رویدادها و خدمات و کتابخانه‌های مختلف آن‌ها را تغییر دهید.

حضار

این مستندات برای افرادی که با برنامه نویسی جاوا اسکریپت و مفاهیم برنامه نویسی شی گرا آشنا هستند طراحی شده است. همچنین باید از دیدگاه کاربر با Maps آشنا باشید. بسیاری از آموزش های جاوا اسکریپت در وب وجود دارد.

این مستندات مفهومی به گونه ای طراحی شده است که به شما امکان می دهد به سرعت کاوش و توسعه برنامه ها را با Maps JavaScript API شروع کنید. ما همچنین Maps JavaScript API Reference را منتشر می کنیم.

سلام دنیا

ساده ترین راه برای شروع یادگیری در مورد Maps JavaScript API دیدن یک مثال ساده است. مثال زیر نقشه ای را با مرکز سیدنی، نیو ساوت ولز، استرالیا نشان می دهد.

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

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

style.css

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html
مشاهده نمونه

Sample را امتحان کنید

حتی در این مثال ساده، چند نکته قابل توجه است:

  1. ما برنامه را با استفاده از اعلان <!DOCTYPE html> به عنوان HTML5 اعلام می کنیم.
  2. ما یک عنصر div به نام "map" برای نگه داشتن نقشه ایجاد می کنیم.
  3. ما یک تابع جاوا اسکریپت تعریف می کنیم که یک نقشه در div ایجاد می کند.
  4. ما Maps JavaScript API را با استفاده از bootstrap loader بارگذاری می کنیم.

این مراحل در زیر توضیح داده شده است.

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

بوت استرپ لودر روش توصیه شده برای بارگیری Maps JavaScript API است. بارگذار JS API نیز به عنوان جایگزین ارائه شده است. توصیه می کنیم هر دو روش را بررسی کنید و مناسب ترین روش را برای ساختار کد پروژه خود انتخاب کنید.

برای جزئیات بیشتر، به بارگیری 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 استفاده کنید، همانطور که در اینجا نشان داده شده است:

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

بسته NPM js-api-loader

از @googlemaps/js-api-loader برای استفاده از NPM برای بارگیری Maps JavaScript API استفاده کنید. با استفاده از دستور زیر آن را از طریق 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

برنامه خود را HTML5 اعلام کنید

توصیه می کنیم یک DOCTYPE واقعی را در برنامه وب خود اعلام کنید. در مثال‌های اینجا، ما برنامه‌های خود را با استفاده از HTML5 DOCTYPE ساده مانند زیر به عنوان HTML5 اعلام کرده‌ایم:

<!DOCTYPE html>

اکثر مرورگرهای فعلی محتوایی را که با این DOCTYPE اعلام شده است در "حالت استاندارد" ارائه می‌کنند که به این معنی است که برنامه شما باید با مرورگرهای متقابل سازگارتر باشد. DOCTYPE همچنین به گونه‌ای طراحی شده است که به‌طور دلپذیری کاهش یابد. مرورگرهایی که آن را درک نمی کنند، آن را نادیده می گیرند و از "حالت quirks" برای نمایش محتوای خود استفاده می کنند.

توجه داشته باشید که برخی از CSSهایی که در حالت quirks کار می کنند در حالت استاندارد معتبر نیستند. به طور خاص، همه اندازه‌های مبتنی بر درصد باید از عناصر بلوک والد به ارث بروند، و اگر هر یک از این اجداد نتوانند اندازه‌ای را تعیین کنند، اندازه‌گیری آن‌ها در 0×0 پیکسل در نظر گرفته می‌شود. به همین دلیل، اعلان <style> زیر را اضافه می کنیم:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

این اعلان CSS نشان می دهد که محفظه نقشه <div> (با id map ) باید 100% ارتفاع بدنه HTML را اشغال کند. توجه داشته باشید که ما باید به طور خاص آن درصدها را برای <body> و <html> نیز اعلام کنیم.

در حال بارگیری Maps JavaScript API

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

در حال بارگذاری درون خطی

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

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

بارگذاری دینامیک

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

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

بارگذاری دینامیک

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

ویژگی های برچسب اسکریپت

در مثال های بالا توجه کنید که چندین ویژگی روی تگ script تنظیم شده است که توصیه می شود. در ادامه هر یک از ویژگی ها توضیح داده شده است.

  • src : نشانی اینترنتی که Maps JavaScript API از آنجا بارگیری می‌شود، شامل تمام نمادها و تعاریفی که برای استفاده از Maps JavaScript API نیاز دارید. URL در این مثال دارای دو پارامتر است: key ، جایی که کلید API خود را ارائه می‌دهید، و callback ، که در آن نام یک تابع سراسری را مشخص می‌کنید که پس از بارگیری کامل Maps JavaScript API فراخوانی شود. درباره پارامترهای URL بیشتر بخوانید.
  • async : از مرورگر می خواهد که اسکریپت را به صورت ناهمزمان دانلود و اجرا کند. هنگامی که اسکریپت اجرا می شود، تابع مشخص شده را با استفاده از پارامتر callback فراخوانی می کند.

کتابخانه ها

هنگام بارگیری Maps JavaScript API از طریق URL، می‌توانید کتابخانه‌های بیشتری را با استفاده از عملگر await برای فراخوانی importLibrary() از داخل یک تابع async بارگیری کنید. کتابخانه‌ها ماژول‌هایی از کد هستند که عملکردهای اضافی را برای API اصلی Maps JavaScript ارائه می‌کنند، اما بارگیری نمی‌شوند مگر اینکه شما به‌طور خاص آنها را درخواست کنید. برای اطلاعات بیشتر، کتابخانه ها در Maps JavaScript API را ببینید.

نقشه عناصر DOM

<div id="map"></div>

برای اینکه نقشه در یک صفحه وب نمایش داده شود، باید جایی برای آن رزرو کنیم. معمولاً این کار را با ایجاد یک عنصر div با نام و به دست آوردن ارجاع به این عنصر در مدل شی سند مرورگر (DOM) انجام می دهیم.

در مثال بالا، ما از CSS برای تنظیم ارتفاع div نقشه روی "100٪" استفاده کردیم. این برای متناسب با اندازه در دستگاه های تلفن همراه گسترش می یابد. ممکن است لازم باشد که مقادیر عرض و ارتفاع را بر اساس اندازه صفحه و صفحه مرورگر تنظیم کنید. توجه داشته باشید که div ها معمولاً عرض خود را از عنصر حاوی خود می گیرند و div های خالی معمولاً 0 ارتفاع دارند. به همین دلیل، همیشه باید یک ارتفاع را در <div> به طور واضح تنظیم کنید.

گزینه های نقشه

دو گزینه لازم برای هر نقشه وجود دارد: center و zoom .

map = new Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

سطوح بزرگنمایی

وضوح اولیه برای نمایش نقشه توسط ویژگی zoom تنظیم می شود، که در آن زوم 0 مربوط به نقشه ای از زمین است که به طور کامل کوچک شده است، و سطوح بزرگنمایی بزرگتر با وضوح بالاتر زوم می شوند.

zoom: 8

ارائه یک نقشه از کل زمین به عنوان یک تصویر واحد یا به یک نقشه عظیم یا یک نقشه کوچک با وضوح بسیار پایین نیاز دارد. در نتیجه، تصاویر نقشه در Google Maps و Maps JavaScript API به «کاشی‌ها» و «سطوح زوم» تقسیم می‌شوند. در سطوح زوم کم، مجموعه کوچکی از کاشی های نقشه یک منطقه وسیع را پوشش می دهد. در سطوح زوم بالاتر، کاشی‌ها وضوح بالاتری دارند و ناحیه کوچک‌تری را پوشش می‌دهند. لیست زیر سطح تقریبی جزئیاتی را که می‌توانید انتظار داشته باشید در هر سطح بزرگ‌نمایی ببینید را نشان می‌دهد:

  • 1: جهان
  • 5: خشکی / قاره
  • 10: شهر
  • 15: خیابان ها
  • 20: ساختمان ها

سه تصویر زیر همان مکان توکیو را در سطوح زوم 0، 7 و 18 منعکس می کند.

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

شی نقشه

map = new Map(document.getElementById("map"), {...});

کلاس جاوا اسکریپت که یک نقشه را نشان می دهد، کلاس Map است. اشیاء این کلاس یک نقشه واحد را در یک صفحه تعریف می کنند. (شما می توانید بیش از یک نمونه از این کلاس ایجاد کنید - هر شی یک نقشه جداگانه در صفحه تعریف می کند.) ما یک نمونه جدید از این کلاس را با استفاده از عملگر new جاوا اسکریپت ایجاد می کنیم.

هنگامی که یک نمونه نقشه جدید ایجاد می کنید، یک عنصر HTML <div> را در صفحه به عنوان ظرفی برای نقشه مشخص می کنید. گره های HTML فرزندان شی document جاوا اسکریپت هستند و ما از طریق متد document.getElementById() به این عنصر ارجاع می دهیم.

این کد یک متغیر ( map با نام) را تعریف می کند و آن متغیر را به یک شی Map جدید اختصاص می دهد. تابع Map() به عنوان سازنده شناخته می شود و تعریف آن در زیر نشان داده شده است:

سازنده شرح
Map(mapDiv:Node, opts?: MapOptions ) با استفاده از هر پارامتر (اختیاری) ارسال شده، یک نقشه جدید در داخل ظرف HTML داده شده ایجاد می کند - که معمولاً یک عنصر DIV است.

عیب یابی

کلید API و خطاهای صورت‌حساب

تحت شرایط خاص، ممکن است یک نقشه تاریک یا تصویر "منفی" نمای خیابان، با متن "فقط برای اهداف توسعه" نشان داده شود. این رفتار معمولاً مشکلات مربوط به کلید API یا صورت‌حساب را نشان می‌دهد. برای استفاده از محصولات Google Maps Platform، صورت‌حساب باید در حساب شما فعال باشد و همه درخواست‌ها باید دارای یک کلید API معتبر باشند. جریان زیر به رفع مشکل کمک می کند:

اگر کد شما کار نمی کند:

برندان کنی و مانو مارکس برای کمک به شما در راه‌اندازی کد نقشه‌های خود، در این ویدیو به برخی از اشتباهات رایج و نحوه رفع آنها اشاره می‌کنند.

  • به دنبال اشتباهات تایپی باشید به یاد داشته باشید که جاوا اسکریپت یک زبان حساس به حروف بزرگ و کوچک است.
  • اصول اولیه را بررسی کنید - برخی از رایج ترین مشکلات با ایجاد نقشه اولیه رخ می دهد. مانند:
    • تأیید کنید که ویژگی های zoom و center را در گزینه های نقشه خود مشخص کرده اید.
    • اطمینان حاصل کنید که یک عنصر div را اعلام کرده اید که در آن نقشه روی صفحه ظاهر می شود.
    • اطمینان حاصل کنید که عنصر div برای نقشه دارای ارتفاع است. به طور پیش فرض، عناصر div با ارتفاع 0 ایجاد می شوند و بنابراین نامرئی هستند.
    برای اجرای مرجع به مثال های ما مراجعه کنید.
  • از یک اشکال‌زدای جاوا اسکریپت برای کمک به شناسایی مشکلات استفاده کنید، مانند آنچه در ابزارهای برنامه‌نویس Chrome موجود است. با جستجوی خطا در کنسول جاوا اسکریپت شروع کنید.
  • سوالات را به Stack Overflow ارسال کنید. دستورالعمل‌هایی درباره نحوه ارسال سؤالات عالی در صفحه پشتیبانی موجود است.