افزودن «نقشه 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، مراحل زیر را دنبال کنید.

1. عنصر 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 بیشتر بدانید

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

<gmp-map center="-34.397,150.644" zoom="8" mapId="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

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

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" mapId="DEMO_MAP_ID">
        </gmp-map>
    </body>
</html>
index.html

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

برای بهبود سرعت بار کردن صفحه، «میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» ممکن است بار کردن محتوای تعاملی را به‌طور داخلی تا زمانی‌که عنصر یا ظرف به درگاه دید نزدیک شود به‌تعویق بیندازد. این بهینه‌سازی‌های داخلی ممکن است در هر زمانی بدون اطلاع قبلی تغییر کنند. این ویژگی‌ها برای بهبود عملکرد طراحی شده‌اند و نباید به‌عنوان مکانیزمی برای مدیریت صورت‌حساب استفاده شوند. برای اطمینان از اینکه تا زمانی که عنصر قابل‌مشاهده نباشد، صورت‌حساب ایجاد نمی‌شود، ایجاد آن را در کد برنامه خود به تعویق بیندازید.

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

توجه: اگرچه این رویکرد همچنان کاملاً پشتیبانی می‌شود و برخی‌از توسعه‌دهندگان آن را ترجیح می‌دهند، توصیه می‌کنیم برای پروژه‌های جدید و ادغام‌های مدرن، مؤلفه وب اعلانی gmp-map را درنظر بگیرید.

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

1. عنصر script حاوی bootstrap را به صفحه HTML اضافه کنید، یا آن را به فایل منبع JavaScript یا TypeScript بدون عنصر script اضافه کنید. راه‌انداز را با کلید میانای برنامه‌سازی کاربردی و هر گزینه دیگری پیکربندی کنید. می‌توانید وارد کردن کتابخانه پویا یا بار کردن مستقیم اسکریپت را انتخاب کنید. این مثال نشان می‌دهد که چگونه راه‌انداز پویا به صفحه 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 بیشتر بدانید

2. در صفحه HTML، عنصر div را برای گنجاندن نقشه اضافه کنید.

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

3. در CSS، ارتفاع html، body، و #map را روی 100% تنظیم کنید. ویژگی CSS height برای نمایان بودن نقشه لازم است زیرا عناصر خالی div به‌طور پیش‌فرض ارتفاع 0 دارند. ازآنجایی‌که ارتفاع‌های درصدی در حالت سخت‌گیرانه از عناصر ولی به‌صورت آبشاری پایین می‌آیند، تنظیم height: 100% روی html و body و همچنین #map زنجیره ناگسسته‌ای از وراثت ارتفاع را از ناحیه نمایش تا محفظه نقشه در همه مرورگرها تضمین می‌کند.

   html,
   body,
   #map {
     height: 100%;
     margin: 0;
     padding: 0;
   }

4. در فایل 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

توجه: راهنمای استفاده از 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

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

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

برای بهبود سرعت بار کردن صفحه، «میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» ممکن است بار کردن محتوای تعاملی را به‌طور داخلی تا زمانی‌که عنصر یا ظرف به درگاه دید نزدیک شود به‌تعویق بیندازد. این بهینه‌سازی‌های داخلی ممکن است در هر زمانی بدون اطلاع قبلی تغییر کنند. این ویژگی‌ها برای بهبود عملکرد طراحی شده‌اند و نباید به‌عنوان مکانیزمی برای مدیریت صورت‌حساب استفاده شوند. برای اطمینان از اینکه تا زمانی که عنصر قابل‌مشاهده نباشد، صورت‌حساب ایجاد نمی‌شود، ایجاد آن را در کد برنامه خود به تعویق بیندازید.

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

برای تعامل با نمونه نقشه، عنصر حاوی آن را انتخاب کنید. کد انجام این کار بسته به اینکه از عنصر 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,
});