إشعار: ستتوفّر قريبًا ميزة جديدة لتصميم الخرائط الأساسية في "منصة خرائط Google". يتضمّن هذا التعديل على تصميم الخريطة لوحة ألوان تلقائية جديدة وعلامات جديدة وتحسينات على تجارب الخريطة وسهولة استخدامها. سيتم تعديل جميع أنماط الخرائط تلقائيًا في آذار (مارس) 2025. لمزيد من المعلومات عن مدى التوفّر وكيفية التفعيل في وقت سابق، يُرجى الاطّلاع على نمط خريطة جديد لـ "منصة خرائط Google".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

مقدمة

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

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

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

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

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

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

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

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

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

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

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

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>

    <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

يُرجى العِلم أنّ هذه صفحة أساسية جدًا تتضمّن عنوانًا من المستوى الثالث (h3) وعنصرًا واحدًا من النوع div. يمكنك إضافة أي محتوى تريده إلى صفحة الويب.

فهم الرمز

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

تمّت الإشارة إلى أنّ التطبيق مكتوب بلغة HTML5 باستخدام نموذج بيان !DOCTYPE html.
تم إنشاء عنصر div باسم "map" لعرض الخريطة.
تم تحميل واجهة برمجة تطبيقات JavaScript لخرائط Google باستخدام أداة تحميل Bootstrap.

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

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

<!DOCTYPE html>

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

يُرجى العلم أنّ بعض رموز CSS التي تعمل في وضع Quirks غير صالحة في وضع Standards. على وجه التحديد، يجب أن تكتسِب كل الأحجام المستندة إلى النسبة المئوية من عناصر الكتل الرئيسية، وإذا تعذّر على أيّ من هذه العناصر الأساسية تحديد حجم، يُفترض أنّ حجمها 0 × 0 بكسل. لهذا السبب، ندرج بيان style التالي:

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

إنشاء عنصر div

لكي تظهر الخريطة على صفحة ويب، يجب حجز مساحة لها. وعادةً ما ننفّذ ذلك من خلال إنشاء عنصر div مُعنوَن والحصول على إشارة إلى هذا العنصر في نموذج تمثيل المستندات (DOM) للمتصفّح.

يحدّد الرمز أدناه منطقة من الصفحة لخريطة Google.

<!--The div element for the map -->
<div id="map"></div>

في هذه المرحلة من البرنامج التعليمي، يظهر div ككتلة رمادية فقط، لأنّه لم تتم إضافة خريطة بعد. يوضّح الرمز البرمجي أدناه صفحات الأنماط المتتالية (CSS) التي تحدّد حجم الرمز div ولونه.

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

في الرمز أعلاه، يحدّد العنصر style حجم div لخريطتك. اضبط div العرض والارتفاع على قيمة أكبر من 0 بكسل لكي تكون الخريطة مرئية. في هذا الحالة، تم ضبط div على ارتفاع 400 بكسل وعرض ‎100% لعرضه على مستوى عرض صفحة الويب. يُرجى العِلم أنّ عناصر div تأخذ عادةً عرضها من العنصر الذي تحتوي عليه، ويكون ارتفاع عناصر div الفارغة عادةً 0. لهذا السبب، يجب دائمًا ضبط ارتفاع div صراحةً.

تحميل Maps JavaScript API

يُعدّ أداة تحميل التمهيد واجهة برمجة التطبيقات JavaScript لخرائط Google للتحميل (لا يتم تحميل أي مكتبات إلى أن يتم استدعاء 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: الحصول على مفتاح واجهة برمجة التطبيقات للحصول على تعليمات حول كيفية الحصول على مفتاح واجهة برمجة التطبيقات الخاص بك.

الخطوة 3: إضافة خريطة تتضمّن علامة

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

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();index.js

في الرمز البرمجي أعلاه، يتم تحميل مكتبتَي Map وAdvancedMarkerElement عند استدعاء الدالة initMap().

فهم الرمز

في هذه المرحلة من البرنامج التعليمي، لدينا:

تحديد دالة JavaScript لإنشاء خريطة في div
تم إنشاء AdvancedMarkerElement لإضافة علامة إلى الخريطة.

إضافة خريطة

ينشئ الرمز البرمجي أدناه عنصرًا جديدًا في "خرائط Google"، ويضيف خصائص إلى الخريطة، بما في ذلك المركز ومستوى التكبير/التصغير. راجِع المستندات للاطّلاع على خيارات المواقع الأخرى.

TypeScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

// The map, centered at Uluru
map = new Map(
  document.getElementById('map') as HTMLElement,
  {
    zoom: 4,
    center: position,
    mapId: 'DEMO_MAP_ID',
  }
);index.ts

JavaScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };
// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

// The map, centered at Uluru
map = new Map(document.getElementById("map"), {
  zoom: 4,
  center: position,
  mapId: "DEMO_MAP_ID",
});
index.js

هناك خياران مطلوبان لكل خريطة: center وzoom. في الرمز المبرمَج أعلاه، تنشئ new Map() عنصرًا جديدًا في "خرائط Google". يُحدِّد حقل center لواجهة برمجة التطبيقات مكان توسيع الخريطة.

تحدِّد السمة zoom مستوى التكبير/التصغير للخريطة. التصغير: يشير الرقم 0 إلى أدنى مستوى للتصغير، ويعرض الكرة الأرضية بأكملها. اضبط قيمة التصغير على قيمة أعلى لتكبير سطح الأرض بدرجات دقة أعلى.

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

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

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

إضافة علامة

تضع التعليمة البرمجية أدناه علامة على الخريطة. تضبط السمة position موقع العلامة.

TypeScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: 'Uluru'
});index.ts

JavaScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: "Uluru",
});index.js

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

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

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();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>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>

    <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>index.html

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

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

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