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

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

افزودن «نقشه Google» به صفحه وب

می‌توانید بااستفاده از کد HTML،‏ CSS، و جاوا اسکریپت، نقشه Google را به صفحه وب اضافه کنید. این صفحه نشان می‌دهد چگونه می‌توانید نقشه‌ای را به صفحه وب اضافه کنید و سپس به‌صورت برنامه‌نویسی‌شده به نمونه نقشه دسترسی پیدا کنید.

افزودن نقشه بااستفاده از عنصر gmp-map
افزودن نقشه بااستفاده از عنصر div و جاوا اسکریپت
تنظیم و دریافت ویژگی‌ها در نمونه نقشه

نمای کلی

برای بار کردن نقشه، صفحه وب شما باید کارهای زیر را انجام دهد:

بار کردن Maps JavaScript API بااستفاده از بارگذار خودراه‌انداز. اینجا جایی است که کلید میانای API شما ارسال می‌شود. می‌توان آن را به فایل‌های منبع HTML یا JavaScript اضافه کرد.
نقشه را به صفحه HTML اضافه کنید و سبک‌های CSS موردنیاز را اضافه کنید.
کتابخانه maps را بار کنید و نقشه را مقداردهی اولیه کنید.

افزودن نقشه بااستفاده از عنصر `gmp-map`

عنصر gmp-map روش ترجیحی برای افزودن Google Map به صفحه وب است. این یک عنصر HTML سفارشی است که بااستفاده از مؤلفه‌های وب ایجاد شده است. برای افزودن نقشه به صفحه وب بااستفاده از عنصر gmp-map، مراحل زیر را دنبال کنید.

عنصر script حاوی راه‌انداز را به صفحه HTML اضافه کنید، یا آن را بدون عنصر script به فایل منبع جاوا اسکریپت یا TypeScript اضافه کنید. راه‌انداز را با کلید میانای برنامه‌سازی کاربردی و هر گزینه دیگری پیکربندی کنید. می‌توانید وارد کردن کتابخانه پویا یا بار کردن مستقیم اسکریپت را انتخاب کنید. این مثال نشان می‌دهد چگونه بوت‌استرپ بارگیری اسکریپت پویا را به صفحه HTML اضافه کنید:

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

درباره بار کردن Google Maps JavaScript API بیشتر بدانید

در صفحه HTML، عنصر gmp-map را اضافه کنید. مختصات طول و عرض جغرافیایی را برای center (الزامی)، مقدار بزرگ‌نمایی را برای zoom (الزامی)، و درصورت نیاز map-id را (برای برخی‌از ویژگی‌ها مانند «نشانگرهای پیشرفته» الزامی است) مشخص کنید.

<gmp-map center="-34.397,150.644" zoom="8" map-id="DEMO_MAP_ID">
</gmp-map>index.html

کد نمونه کامل

TypeScript

async function init(): Promise<void> {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map')!;
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();index.ts

JavaScript

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();index.js

CSS

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>

    <body>
        <gmp-map center="-34.397,150.644" zoom="8" map-id="DEMO_MAP_ID">
        </gmp-map>
    </body>
</html>index.html

امتحان کردن نمونه

JSFiddle.net

نکته‌ای درباره بهینه‌سازی عملکرد داخلی:

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

افزودن نقشه بااستفاده از عنصر `div` و جاوا اسکریپت

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

عنصر script حاوی راه‌انداز را به صفحه HTML اضافه کنید، یا آن را بدون عنصر script به فایل منبع جاوا اسکریپت یا TypeScript اضافه کنید. راه‌انداز را با کلید میانای برنامه‌سازی کاربردی و هر گزینه دیگری پیکربندی کنید. می‌توانید وارد کردن کتابخانه پویا یا بار کردن مستقیم اسکریپت را انتخاب کنید. این مثال نشان می‌دهد که چگونه راه‌انداز پویا به صفحه HTML اضافه می‌شود:

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

درباره بار کردن Google Maps JavaScript API بیشتر بدانید

در صفحه HTML، عنصر div را برای گنجاندن نقشه اضافه کنید.
```
<div id="map"></div>
```
در CSS، ارتفاع html، body، و #map را روی 100% تنظیم کنید. ویژگی CSS height برای نمایان شدن نقشه لازم است زیرا عناصر div خالی به‌طور پیش‌فرض ارتفاع 0 دارند. ازآنجایی‌که ارتفاع‌های مبتنی بر درصد در حالت سخت‌گیرانه از عناصر ولی به‌صورت آبشاری پایین می‌آیند، تنظیم height: 100% روی html و body و همچنین #map زنجیره ناگسسته‌ای از وراثت ارتفاع را از ناحیه نمایش تا محفظه نقشه در همه مرورگرها تضمین می‌کند.
```
html,
body,
#map {
  height: 100%;
  margin: 0;
  padding: 0;
}
```
در فایل JS یا TS، تابعی برای بار کردن کتابخانه maps و مقداردهی اولیه نقشه ایجاد کنید. مختصات طول و عرض جغرافیایی را برای center و سطح بزرگ‌نمایی را برای استفاده در zoom مشخص کنید. درصورت نیاز، بااستفاده از ویژگی mapId، شناسه نقشه اضافه کنید. ازآنجایی‌که نقشه به‌طور پیش‌فرض شطرنجی خواهد بود، با مشخص کردن گزینه نقشه «VECTOR» (بُرداری)، نقشه بُرداری درخواست کنید؛ برای بهترین تجربه کاربری، نوع نقشه بُرداری توصیه می‌شود، زیرا وفاداری بصری بهبودیافته و همچنین توانایی کنترل شیب و جهت در نقشه را فراهم می‌کند.
TypeScript
```
let map: google.maps.Map;
async function init(): Promise<void> {
    // Import the needed libraries
    const { Map } = await google.maps.importLibrary('maps');

    // Create a new map from the div with id="map".
    map = new Map(document.getElementById('map')!, {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
        renderingType: 'VECTOR',
    });

    console.log(map);
}

void init();index.ts
```
توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.
JavaScript
```
let map;
async function init() {
    // Import the needed libraries
    const { Map } = await google.maps.importLibrary('maps');

    // Create a new map from the div with id="map".
    map = new Map(document.getElementById('map'), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
        renderingType: 'VECTOR',
    });

    console.log(map);
}

void init();index.js
```

مشاهده کد منبع نمونه کامل

TypeScript

let map: google.maps.Map;
async function init(): Promise<void> {
    // Import the needed libraries
    const { Map } = await google.maps.importLibrary('maps');

    // Create a new map from the div with id="map".
    map = new Map(document.getElementById('map')!, {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
        renderingType: 'VECTOR',
    });

    console.log(map);
}

void init();index.ts

JavaScript

let map;
async function init() {
    // Import the needed libraries
    const { Map } = await google.maps.importLibrary('maps');

    // Create a new map from the div with id="map".
    map = new Map(document.getElementById('map'), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
        renderingType: 'VECTOR',
    });

    console.log(map);
}

void init();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>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>

        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY" 
            });
        </script>
    </head>

    <body>
        <div id="map"></div>
    </body>
</html>index.html

امتحان کردن نمونه

JSFiddle.net

نکته‌ای درباره بهینه‌سازی عملکرد داخلی:

تنظیم و دریافت ویژگی‌ها در نمونه نقشه

برای تعامل با نمونه نقشه، عنصر حاوی آن را انتخاب کنید. کد انجام این کار بسته به اینکه از عنصر gmp-map یا عنصر div استفاده کرده باشید متفاوت خواهد بود.

دریافت نمونه نقشه از عنصر `gmp-map`

برای دریافت نمونه نقشه هنگام استفاده از عنصر gmp-map، از document.querySelector برای بازیابی نمونه mapElement استفاده کنید، همان‌طور که در اینجا نشان داده شده است.

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;

سپس ویژگی‌ها را در نمونه mapElement تنظیم کنید:

mapElement.zoom = 8;

کلاس MapElement از کلاس Map به‌صورت داخلی استفاده می‌کند؛ بااستفاده از ویژگی MapElement.innerMap به کلاس Map دسترسی پیدا کنید، همان‌طور که در اینجا نشان داده شده است:

mapElement.innerMap.setOptions({
    mapTypeControl: false,
});

دریافت نمونه نقشه از عنصر `div`

هنگام استفاده از عنصر div، نمونه نقشه را دریافت کنید و گزینه‌ها را در زمان مقداردهی اولیه تنظیم کنید:

map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
    mapTypeControl: false,
});

پس‌از مقداردهی اولیه، گزینه‌ها را در نمونه map همان‌طور که در اینجا نشان داده شده است تنظیم کنید:

map.setOptions({
    zoom: 8,
});

افزودن «نقشه Google» به صفحه وب با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

نمای کلی

افزودن نقشه بااستفاده از عنصر gmp-map

کد نمونه کامل

TypeScript

JavaScript

CSS

HTML

امتحان کردن نمونه

افزودن نقشه بااستفاده از عنصر div و جاوا اسکریپت

TypeScript

JavaScript

مشاهده کد منبع نمونه کامل

TypeScript

JavaScript

CSS

HTML

امتحان کردن نمونه

تنظیم و دریافت ویژگی‌ها در نمونه نقشه

دریافت نمونه نقشه از عنصر gmp-map

دریافت نمونه نقشه از عنصر div

افزودن «نقشه Google» به صفحه وب

افزودن نقشه بااستفاده از عنصر `gmp-map`

افزودن نقشه بااستفاده از عنصر `div` و جاوا اسکریپت

دریافت نمونه نقشه از عنصر `gmp-map`

دریافت نمونه نقشه از عنصر `div`