إضافة "خريطة Google" تتضمّن علامة باستخدام JavaScript

مقدمة

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

في ما يلي الخريطة التي ستنشئها باستخدام هذا البرنامج التعليمي. تم وضع العلامة في أولورو (المعروف أيضًا باسم صخرة آيرز) في منتزه أولورو كاتا تجوتا الوطني.

الخطوات الأولى

هناك ثلاث خطوات لإنشاء خريطة Google مع علامة على صفحة الويب الخاصة بك:

1. الحصول على مفتاح واجهة برمجة التطبيقات
2. إنشاء صفحة HTML
3. إضافة خريطة مع علامة

يجب استخدام متصفّح ويب. اختَر متصفّحًا معروفًا، مثل Google Chrome (الخيار المقترَح) أو Firefox أو Safari أو Edge، استنادًا إلى نظامك الأساسي من قائمة المتصفّحات المتوافقة.

الخطوة 1: الحصول على مفتاح واجهة برمجة التطبيقات

يوضّح هذا القسم كيفية مصادقة تطبيقك في Maps JavaScript API باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك.

اتّبِع الخطوات التالية للحصول على مفتاح واجهة برمجة التطبيقات:

1. انتقِل إلى وحدة تحكّم Google Cloud.

2. إنشاء مشروع أو اختياره

3. انقر على متابعة لتفعيل واجهة برمجة التطبيقات وأي خدمات ذات صلة.

4. في صفحة بيانات الاعتماد، احصل على مفتاح واجهة برمجة التطبيقات (واضبط القيود المفروضة على مفتاح واجهة برمجة التطبيقات). ملاحظة: إذا كان لديك مفتاح واجهة برمجة تطبيقات حالي غير مقيّد أو مفتاح يتضمّن قيودًا على المتصفّح، يمكنك استخدام هذا المفتاح.

5. لمنع سرقة الحصة وتأمين مفتاح واجهة برمجة التطبيقات، يُرجى الاطّلاع على استخدام مفاتيح واجهة برمجة التطبيقات.

6. فعِّل الفوترة. لمزيد من المعلومات، يُرجى الاطّلاع على الاستخدام والفوترة.

7. بعد الحصول على مفتاح واجهة برمجة التطبيقات، أضِفه إلى المقتطف التالي من خلال النقر على "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 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

<html>
  <head>
    <title>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

هذه صفحة HTML أساسية جدًا تستخدم عنصر gmp-map لعرض خريطة على الصفحة. ستكون الخريطة فارغة لأنّنا لم نُضِف أي رمز JavaScript بعد.

فهم الرمز البرمجي

في هذه المرحلة من المثال، لدينا:

• تم الإعلان عن التطبيق على أنّه HTML5 باستخدام بيان !DOCTYPE html.
• تم تحميل Maps JavaScript API باستخدام عامل التحميل التمهيدي.
• تم إنشاء عنصر gmp-map لحفظ الخريطة.

الإعلان عن تطبيقك على أنّه HTML5

ننصحك بتحديد قيمة صحيحة للسمة DOCTYPE في تطبيق الويب. في الأمثلة الواردة هنا، أعلنّا عن تطبيقاتنا على أنّها HTML5 باستخدام السمة DOCTYPE في HTML5 كما هو موضّح أدناه:

<!DOCTYPE html>

ستعرض معظم المتصفحات الحالية المحتوى الذي تم تعريفه باستخدام DOCTYPE في "وضع المعايير"، ما يعني أن تطبيقك يجب أن يكون أكثر توافقًا مع المتصفحات المختلفة. تم تصميم DOCTYPE أيضًا ليتراجع تدريجيًا، فالمتصفحات التي لا تفهمه ستتجاهله وتستخدم "وضع Quirks" لعرض محتواها.

يُرجى العِلم أنّ بعض أوراق الأنماط المتتالية (CSS) التي تعمل ضمن وضع Quirks لا تكون صالحة في وضع المعايير. على وجه التحديد، يجب أن تكتسب جميع الأحجام المستندة إلى النسبة المئوية من عناصر الكتلة الأصلية، وإذا فشل أي من هؤلاء الأسلاف في تحديد الحجم، فمن المفترض أن يتم تحديد حجمها عند 0 × 0 بكسل. لهذا السبب، نُدرج بيان style التالي:

<style>
  gmp-map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

تحميل 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: الحصول على مفتاح واجهة برمجة التطبيقات للحصول على تعليمات حول كيفية الحصول على مفتاح واجهة برمجة التطبيقات الخاص بك.

في هذه المرحلة من البرنامج التعليمي، تظهر نافذة فارغة، تعرض فقط نص التسمية غير المنسق. ويرجع ذلك إلى أنّنا لم نُضِف أي رمز JavaScript بعد.

إنشاء عنصر gmp-map

لعرض الخريطة على صفحة ويب، يجب حجز مكان لها. عادةً ما نقوم بذلك عن طريق إنشاء عنصر gmp-map والحصول على مرجع لهذا العنصر في نموذج كائن المستند (DOM) الخاص بالمتصفح. يمكنك أيضًا استخدام عنصر div لإجراء ذلك (مزيد من المعلومات)، ولكن ننصحك باستخدام العنصر gmp-map.

يحدّد الرمز أدناه العنصر gmp-map ويضبط المَعلمات center وzoom وmap-id.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

يجب دائمًا استخدام الخيارَين center وzoom. في الرمز أعلاه، تخبر السمة center واجهة برمجة التطبيقات بالمكان الذي يجب أن تتوسط فيه الخريطة، وتحدد السمة zoom مستوى التكبير للخريطة. التكبير/التصغير: 0 هو أدنى مستوى تكبير، ويعرض الأرض بأكملها. اضبط قيمة التكبير على مستوى أعلى لتكبير الأرض بدقة أعلى.

مستويات التكبير والتصغير

إنّ تقديم خريطة لكوكب الأرض بأكمله كصورة واحدة يتطلّب إما خريطة ضخمة أو خريطة صغيرة بدقة منخفضة جدًا. نتيجةً لذلك، يتم تقسيم صور الخرائط ضمن "خرائط Google" وواجهة برمجة تطبيقات JavaScript للخرائط إلى "مربّعات" و"مستويات تكبير" للخريطة. عند مستويات التكبير المنخفضة، تغطي مجموعة صغيرة من مربّعات الخريطة مساحة واسعة، وعند مستويات التكبير الأعلى، تكون المربّعات ذات دقة أعلى وتغطي مساحة أصغر. تعرض القائمة التالية المستوى التقريبي للتفاصيل التي يمكنك توقُّع رؤيتها في كل مستوى تكبير:

• ‫1: عالمي
• ‫5: كتلة أرضية أو قارة
• ‫10: المدينة
• ‫15: الشوارع
• ‫20: المباني

تعرض الصور الثلاث التالية الموقع الجغرافي نفسه في طوكيو بمستويات التكبير 0 و7 و18.

يصف الرمز أدناه CSS الذي يحدّد حجم العنصر gmp-map.

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

في الرمز أعلاه، يحدّد العنصر style حجم gmp-map. اضبط العرض والارتفاع على قيمة أكبر من 0 بكسل لتظهر الخريطة. في هذه الحالة، يتم ضبط ارتفاع gmp-map على 400 بكسل، وعرضه على% 100 ليتم عرضه على كامل عرض صفحة الويب. ننصحك دائمًا بضبط أنماط الارتفاع والعرض بشكل صريح.

ملاحظة: بالنسبة إلى الخرائط النقطية، الحدّ الأقصى للأبعاد هو 6144 × 6144 بكسل.

تحديد مواضع عناصر التحكم

يمكنك استخدام ميزة "تخصيص موضع عناصر التحكّم" لإضافة عناصر تحكّم في نماذج HTML إلى خريطتك. الخانة هي موضع محدّد مسبقًا على الخريطة. استخدِم السمة slot لضبط الموضع المطلوب لعنصر معيّن، وأدرِج العناصر ضمن العنصر gmp-map. يوضّح المقتطف التالي كيفية إضافة تصنيف HTML إلى أعلى يمين الخريطة.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

الخطوة 3: إضافة رمز JavaScript

يوضّح لك هذا القسم كيفية تحميل Maps JavaScript API في صفحة ويب، وكيفية كتابة رمز JavaScript الخاص بك الذي يستخدم واجهة برمجة التطبيقات لإضافة خريطة مع علامة عليها.

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

ملاحظة: يُرجى قراءة الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

ينفّذ الرمز أعلاه الإجراءات التالية عند استدعاء initMap():

• يتم تحميل مكتبتَي maps وmarker.
• يحصل على عنصر الخريطة من نموذج DOM.
• تحدّد خيارات الخريطة الإضافية على الخريطة الداخلية.
• تضيف هذه الطريقة علامة إلى الخريطة.

الحصول على عنصر الخريطة وضبط الخيارات

يمثّل innerMap مثيلاً من فئة الخريطة. لضبط خيارات الخريطة، احصل على مثيل innerMap من عنصر الخريطة واستدعِ setOptions. يوضّح المقتطف التالي كيفية الحصول على مثيل innerMap من DOM، ثم استدعاء setOptions:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

انتظِر حتى يتم تحميل الخريطة

عند استخدام العنصر gmp-map، يتم تحميل الخريطة بشكل غير متزامن. ويمكن أن يؤدي ذلك إلى حدوث حالة سباق في حال تقديم طلبات أخرى في وقت الإعداد (على سبيل المثال، طلب تحديد الموقع الجغرافي أو طلب تفاصيل المكان). لضمان تشغيل الرمز البرمجي فقط بعد تحميل الخريطة بالكامل، استخدِم معالج أحداث addListenerOnce غير نشط في دالة الإعداد، كما هو موضّح هنا:

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

يضمن ذلك تشغيل الرمز البرمجي بعد تحميل الخريطة فقط، ويتم تشغيل المعالج مرة واحدة فقط خلال مراحل نشاط التطبيق.

ملاحظة حول تحسين الأداء الداخلي:

لتحسين سرعات تحميل الصفحات، قد تؤجّل Maps JavaScript API داخليًا تحميل المحتوى التفاعلي إلى أن يقترب العنصر أو الحاوية من إطار العرض. وتخضع هذه التحسينات الداخلية للتغيير في أي وقت بدون إشعار. تم تصميمها لتحسين الأداء، ولا ينبغي استخدامها كآلية لإدارة الفوترة. لضمان عدم تحصيل رسوم الفوترة إلى أن يصبح العنصر مرئيًا، يمكنك تأجيل إنشائه في الرمز البرمجي للتطبيق.

مثال على الرمز الكامل

يمكنك الاطّلاع على الرمز البرمجي الكامل للمثال هنا:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

ملاحظة: يُرجى قراءة الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-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 a 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>
        <!-- The map, centered at Uluru, Australia. -->
        <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
            <div id="controls" slot="control-inline-start-block-start">
                <h3>My Google Maps Demo</h3>
            </div>
        </gmp-map>
    </body>
</html>
index.html

مزيد من المعلومات حول العلامات:

• تسهيل الوصول إلى علامة
• علامات برموز رسومية
• صور العلامات المتحركة

نصائح وتحديد المشاكل وحلّها

• مزيد من المعلومات حول الحصول على إحداثيات خطوط العرض/الطول أو تحويل عنوان إلى إحداثيات جغرافية
• يمكنك تعديل خيارات مثل النمط والخصائص لتخصيص الخريطة. لمزيد من المعلومات حول تخصيص الخرائط، يُرجى الاطّلاع على دليلَي التصميم والرسم على الخريطة.
• استخدِم وحدة تحكّم أدوات المطوّرين في متصفّح الويب لاختبار الرمز البرمجي وتشغيله وقراءة تقارير الأخطاء وحلّ المشاكل في الرمز البرمجي.
• استخدِم اختصارات لوحة المفاتيح التالية لفتح وحدة التحكّم في Chrome:
  ‫Command+Option+J (على أجهزة Mac) أو Control+Shift+J (على أجهزة Windows).

• اتّبِع الخطوات التالية للحصول على إحداثيات خط العرض وخط الطول لموقع جغرافي على "خرائط Google".

  1. افتح "خرائط Google" في متصفّح.
  2. انقر بزر الماوس الأيمن على الموقع الجغرافي المحدّد على الخريطة الذي تريد الحصول على إحداثياته.
  3. اختَر إحداثيات خطوط العرض والطول من القائمة.

• يمكنك تحويل عنوان إلى إحداثيات خطوط العرض والطول باستخدام خدمة الترميز الجغرافي. تقدّم أدلة المطوّرين معلومات مفصّلة حول بدء استخدام خدمة الترميز الجغرافي.