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

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

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

نمای کلی

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

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

بااستفاده از عنصر gmp-map، نقشه اضافه کنید

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

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

   #map {
     height: 100%;
   }

4. در فایل JS یا TS، تابعی برای بار کردن کتابخانه maps و مقداردهی اولیه نقشه ایجاد کنید. مختصات طول و عرض جغرافیایی را برای center، و سطح بزرگ‌نمایی را برای استفاده در zoom مشخص کنید. درصورت نیاز، بااستفاده از mapId دارایی، شناسه نقشه اضافه کنید. ازآنجایی‌که نقشه به‌طور پیش‌فرض شطرنجی خواهد بود، با مشخص کردن گزینه نقشه «بُرداری»، نقشه بُرداری درخواست کنید؛ نوع نقشه بُرداری برای بهترین تجربه کاربری توصیه می‌شود، زیرا وفاداری دیداری بهبودیافته و همچنین امکان کنترل کردن شیب و جهت در نقشه را فراهم می‌کند.

   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,
});