الحصول على مفتاح Maps Demo Key: يمكنك تجربة ميزات محدّدة من Maps JavaScript API و"حزمة أدوات خرائط Google الجاهزة للأماكن" بدون أي تكلفة باستخدام مفتاح Maps Demo Key، وبدون الحاجة إلى إدخال معلومات الفوترة.

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

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

مقدمة

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

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

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

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

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

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

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

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

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

انتقِل إلى وحدة تحكّم Google Cloud.
إنشاء مشروع أو اختياره
انقر على متابعة لتفعيل واجهة برمجة التطبيقات وأي خدمات ذات صلة.
في صفحة بيانات الاعتماد، احصل على مفتاح واجهة برمجة التطبيقات (واضبط قيود مفتاح واجهة برمجة التطبيقات). ملاحظة: إذا كان لديك مفتاح واجهة برمجة تطبيقات حالي غير مقيّد أو مفتاح مقيّد بالمتصفّح، يمكنك استخدام هذا المفتاح.
لمنع سرقة الحصة وتأمين مفتاح واجهة برمجة التطبيقات، يُرجى الاطّلاع على استخدام مفاتيح واجهة برمجة التطبيقات.
فعِّل الفوترة. لمزيد من المعلومات، يُرجى الاطّلاع على الاستخدام والفوترة.

بعد الحصول على مفتاح واجهة برمجة التطبيقات، أضِفه إلى المقتطف التالي من خلال النقر على "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" وMaps JavaScript API إلى "مربّعات" خريطة و"مستويات تكبير". عند مستويات التكبير المنخفضة، تغطي مجموعة صغيرة من مربّعات الخريطة مساحة واسعة، وعند مستويات التكبير الأعلى، تكون المربّعات ذات دقة أعلى وتغطي مساحة أصغر. تعرض القائمة التالية المستوى التقريبي للتفاصيل التي يمكنك توقع رؤيتها في كل مستوى تكبير:

‫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 ليتم عرضه على كامل عرض صفحة الويب. يُنصح دائمًا بضبط أنماط الارتفاع والعرض بشكل صريح.

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

يمكنك استخدام ميزة "تحديد مواضع عناصر التحكم" لإضافة عناصر تحكّم في نماذج 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

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!");
});

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

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

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

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

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

تجربة عيّنة

JSFiddle.net

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

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

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

إضافة "خريطة Google" تتضمّن علامة باستخدام JavaScript تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

مقدمة

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

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

الخطوة 2: إنشاء صفحة HTML

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

تعريف تطبيقك على أنّه HTML5

تحميل Maps JavaScript API

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

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

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

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

TypeScript

JavaScript

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

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

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

TypeScript

JavaScript

CSS

HTML

تجربة عيّنة

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

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

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

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