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

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

با استفاده از جاوا اسکریپت، نقشه گوگل را با نشانگر اضافه کنید

مقدمه

این آموزش به شما نشان می دهد که چگونه یک نقشه ساده گوگل را با یک نشانگر به یک صفحه وب اضافه کنید. این برای افرادی مناسب است که دانش مبتدی یا متوسطی از HTML و CSS دارند و دانش کمی از جاوا اسکریپت دارند.

در زیر نقشه ای است که با استفاده از این آموزش ایجاد خواهید کرد. نشانگر در اولورو (همچنین به عنوان صخره آیرز شناخته می شود) در پارک ملی اولورو-کاتا توتا قرار دارد.

شروع کردن

سه مرحله برای ایجاد نقشه گوگل با نشانگر در صفحه وب شما وجود دارد:

یک کلید API دریافت کنید
یک صفحه HTML ایجاد کنید
یک نقشه با نشانگر اضافه کنید

شما به یک مرورگر وب نیاز دارید. بر اساس پلتفرم خود از لیست مرورگرهای پشتیبانی شده ، یکی از شناخته شده‌ها مانند Google Chrome (توصیه‌شده)، فایرفاکس، سافاری یا Edge را انتخاب کنید.

مرحله 1: یک کلید API دریافت کنید

این بخش نحوه احراز هویت برنامه خود را در Maps JavaScript API با استفاده از کلید API خود توضیح می دهد.

برای دریافت کلید API مراحل زیر را دنبال کنید:

به Google Cloud Console بروید.
ایجاد یا انتخاب یک پروژه
برای فعال کردن API و هر سرویس مرتبط، روی Continue کلیک کنید.
در صفحه اعتبارنامه ، یک کلید API دریافت کنید (و محدودیت های کلید API را تنظیم کنید). توجه: اگر یک کلید API نامحدود یا کلیدی با محدودیت های مرورگر دارید، می توانید از آن کلید استفاده کنید.
برای جلوگیری از سرقت سهمیه و ایمن کردن کلید API خود، به استفاده از کلیدهای API مراجعه کنید.
فعال کردن صورتحساب برای اطلاعات بیشتر به استفاده و صورتحساب مراجعه کنید.

هنگامی که یک کلید API دریافت کردید، آن را با کلیک کردن روی "YOUR_API_KEY" به قطعه زیر اضافه کنید. تگ اسکریپت بوت لودر را کپی و جایگذاری کنید تا در صفحه وب خود استفاده کنید.

<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>

مرحله 2: یک صفحه HTML ایجاد کنید

در اینجا کد یک صفحه وب پایه HTML آمده است:

<!doctype html>
<!--
 @license
 Copyright 2019 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->
<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <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

توجه داشته باشید که این یک صفحه بسیار ابتدایی با عنوان سطح سه ( h3 ) و یک عنصر div است. می توانید هر محتوایی را که دوست دارید به صفحه وب اضافه کنید.

کد را درک کنید

در این مرحله از مثال، داریم:

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

برنامه خود را 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>

یک عنصر div ایجاد کنید

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

کد زیر ناحیه ای از صفحه را برای نقشه گوگل شما تعریف می کند.

<!--The div element for the map -->
<div id="map"></div>

در این مرحله از آموزش، div فقط به عنوان یک بلوک خاکستری ظاهر می شود، زیرا شما هنوز نقشه ای اضافه نکرده اید. کد زیر CSS را توصیف می کند که اندازه و رنگ div را تعیین می کند.

/* Set the size of the div element that contains the map */
#map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

در کد بالا، عنصر style اندازه div را برای نقشه شما تعیین می کند. عرض و ارتفاع div را بیشتر از 0px تنظیم کنید تا نقشه قابل مشاهده باشد. در این حالت، div روی ارتفاع 400 پیکسل و عرض 100 درصد تنظیم می شود تا عرض صفحه وب شما نمایش داده شود. توجه داشته باشید که div ها معمولاً عرض خود را از عنصر حاوی خود می گیرند و div های خالی معمولاً 0 ارتفاع دارند. به همین دلیل، همیشه باید یک ارتفاع را به طور واضح روی div تنظیم کنید.

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

بارگذار بوت استرپ Maps JavaScript API را برای بارگیری آماده می کند (تا زمانی که importLibrary() فراخوانی نشود هیچ کتابخانه ای بارگذاری نمی شود.

<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>

به مرحله 3 مراجعه کنید: یک کلید API برای دستورالعمل های دریافت کلید API خود دریافت کنید .

مرحله 3: یک نقشه با یک نشانگر اضافه کنید

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

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();index.ts

جاوا اسکریپت

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();index.js

در کد بالا، کتابخانه های Map و AdvancedMarkerElement با فراخوانی تابع initMap() بارگذاری می شوند.

کد را درک کنید

در این مرحله از آموزش، ما داریم:

یک تابع جاوا اسکریپت را تعریف کرد که یک نقشه در div ایجاد می کند.
یک AdvancedMarkerElement برای اضافه کردن یک نشانگر به نقشه ایجاد کرد.

یک نقشه اضافه کنید

کد زیر یک شی جدید نقشه گوگل را می سازد و ویژگی هایی از جمله مرکز و سطح زوم را به نقشه اضافه می کند. برای سایر گزینه های ملک به اسناد مراجعه کنید.

TypeScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

// The map, centered at Uluru
map = new Map(
  document.getElementById('map') as HTMLElement,
  {
    zoom: 4,
    center: position,
    mapId: 'DEMO_MAP_ID',
  }
);index.ts

جاوا اسکریپت

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };
// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

// The map, centered at Uluru
map = new Map(document.getElementById("map"), {
  zoom: 4,
  center: position,
  mapId: "DEMO_MAP_ID",
});
index.js

دو گزینه لازم برای هر نقشه وجود دارد: center و zoom . در کد بالا، new Map() یک شیء جدید نقشه گوگل ایجاد می کند. ویژگی center به API می گوید که نقشه را در کجا قرار دهد.

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

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

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

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

یک نشانگر اضافه کنید

کد زیر یک نشانگر روی نقشه قرار می دهد. ویژگی position موقعیت نشانگر را تعیین می کند.

TypeScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: 'Uluru'
});index.ts

جاوا اسکریپت

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: "Uluru",
});index.js

کد نمونه کامل

کد نمونه کامل را اینجا ببینید:

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();index.ts

جاوا اسکریپت

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

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>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <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 را امتحان کنید

JSFiddle.net Google Cloud Shell

درباره نشانگرها بیشتر بدانید:

نکات و عیب یابی

درباره دریافت مختصات طول و عرض جغرافیایی یا تبدیل آدرس به مختصات جغرافیایی بیشتر بیاموزید.
می‌توانید گزینه‌هایی مانند سبک و ویژگی‌ها را برای سفارشی کردن نقشه تغییر دهید. برای اطلاعات بیشتر در مورد سفارشی کردن نقشه‌ها، راهنمای طراحی و طراحی روی نقشه را بخوانید.
از Developer Tools Console در مرورگر وب خود برای آزمایش و اجرای کد، خواندن گزارش های خطا و حل مشکلات کد خود استفاده کنید.
برای باز کردن کنسول در کروم از میانبرهای صفحه کلید زیر استفاده کنید:
Command+Option+J (در مک)، یا Control+Shift+J (در ویندوز).
مراحل زیر را برای دریافت مختصات طول و عرض جغرافیایی برای یک مکان در Google Maps دنبال کنید.
1. Google Maps را در مرورگر باز کنید.
2. روی مکان دقیقی که برای آن مختصات لازم دارید روی نقشه کلیک راست کنید.
3. از منوی زمینه ای که ظاهر می شود ، What's here را انتخاب کنید. نقشه یک کارت را در پایین صفحه نمایش می دهد. مختصات طول و عرض جغرافیایی را در ردیف آخر کارت بیابید.
با استفاده از سرویس Geocoding می توانید یک آدرس را به مختصات طول و عرض جغرافیایی تبدیل کنید. راهنماهای توسعه دهنده اطلاعات دقیقی را در مورد شروع به کار با سرویس Geocoding ارائه می دهند.