إضافة "خرائط Google" إلى صفحة ويب

يمكنك إضافة خريطة Google إلى صفحة ويب باستخدام رموز HTML وCSS وJavaScript. توضّح هذه الصفحة كيفية إضافة خريطة إلى صفحة ويب، ثم الوصول إلى مثيل الخريطة آليًا.

• إضافة خريطة باستخدام عنصر gmp-map
• إضافة خريطة باستخدام عنصر div وJavaScript
• ضبط الخصائص والحصول عليها في مثيل الخريطة

نظرة عامة

لتحميل خريطة، يجب أن تنفّذ صفحة الويب ما يلي:

• حمِّل Maps JavaScript API باستخدام عامل تحميل تمهيدي. هذا هو المكان الذي يتم فيه تمرير مفتاح واجهة برمجة التطبيقات. ويمكن إضافتها إلى ملفات مصدر HTML أو JavaScript.
• أضِف الخريطة إلى صفحة HTML، وأضِف أنماط CSS المطلوبة.
• حمِّل مكتبة maps وابدأ الخريطة.

إضافة خريطة باستخدام عنصر gmp-map

يُعدّ العنصر gmp-map الطريقة المفضّلة لإضافة خريطة Google إلى صفحة ويب. وهو عنصر HTML مخصّص تم إنشاؤه باستخدام مكوّنات الويب. لإضافة خريطة إلى صفحة ويب باستخدام عنصر gmp-map، اتّبِع الخطوات التالية.

1. أضِف عنصر script يحتوي على عملية الإعداد إلى صفحة 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، أضِف عنصر gmp-map. حدِّد إحداثيات خطوط العرض والطول للسمة center (مطلوبة)، وقيمة التكبير/التصغير للسمة zoom (مطلوبة)، وmap-id إذا لزم الأمر (مطلوبة لبعض الميزات مثل "العلامات المتقدّمة").

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

مثال على الرمز البرمجي الكامل

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

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

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

<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

إضافة خريطة باستخدام عنصر div وJavaScript

لإضافة خريطة إلى صفحة ويب باستخدام عنصر div، اتّبِع الخطوات التالية.

1. أضِف عنصر script يحتوي على عملية الإعداد إلى صفحة 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%. يجب استخدام السمة height في CSS لكي تظهر الخريطة، لأنّ عناصر 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

   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

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

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

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

ضبط السمات والحصول عليها في مثيل الخريطة

للتفاعل مع مثيل الخريطة، اختَر العنصر الذي يحتوي عليها. سيختلف الرمز الذي يجب استخدامه لإجراء ذلك بناءً على ما إذا كنت قد استخدمت العنصر 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 داخليًا، ويمكنك الوصول إلى الفئة Map باستخدام السمة MapElement.innerMap، كما هو موضّح في ما يلي:

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