إشعار الأمان: نما إلى علمنا بمشكلة أمنية قد تؤثر في المواقع الإلكترونية التي تستخدم مكتبات معيّنة تابعة لجهات خارجية (بما في ذلك polyfill.io). وقد تؤدي هذه المشكلة في بعض الأحيان إلى إعادة توجيه الزائرين بعيدًا عن الموقع الإلكتروني المقصود بدون معرفة مالك الموقع أو إذنه. وفي السابق، كان يتضمّن العديد من نماذج JavaScript تعريف النص البرمجي polyfill.io. تمت إزالة هذا المحتوى من نماذجنا. إذا كنت قد استخدمت نماذج JavaScript التي تحتوي على هذا التعريف، ننصحك بإزالة التعريف.

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

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

مقدمة

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

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

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

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

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

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

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

يشرح هذا القسم كيفية مصادقة تطبيقك مع واجهة برمجة تطبيقات JavaScript للخرائط باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك.

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

الانتقال إلى 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 للخرائط باستخدام برنامج الإقلاع.

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

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. انقر على ما هو معروض هنا من قائمة السياقات التي تظهر. تعرض الخريطة بطاقة في أسفل الشاشة. ابحث عن إحداثيات خط العرض وخط الطول في الصف الأخير من البطاقة.
يمكنك تحويل عنوان إلى إحداثيات خط العرض وخط الطول باستخدام خدمة ترميز المواقع الجغرافية. توفِّر أدلة المطوّرين معلومات تفصيلية حول بدء استخدام خدمة الترميز الجغرافي.