نقدّم لك مجموعة أدوات واجهة المستخدم الخاصة بـ Places: هي مكتبة مكوّنات جاهزة للاستخدام ومنخفضة التكلفة تتيح لك إضافة واجهة مستخدم Places المألوفة من "خرائط Google" إلى أي خريطة تختارها. ننصحك بتجربتها و مشاركة ملاحظاتك للمساعدة في رسم مستقبل "منصة 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" لاحتواء الخريطة.
تم تحميل Maps JavaScript API باستخدام أداة تحميل bootstrap.

تحديد تطبيقك على أنّه HTML5

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

<!DOCTYPE html>

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

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

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

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

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

مقدمة

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

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

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

فهم الرمز

تحديد تطبيقك على أنّه HTML5

إنشاء عنصر div

تحميل Maps JavaScript API

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

TypeScript

JavaScript

فهم الرمز

إضافة خريطة

TypeScript

JavaScript

إضافة علامة

TypeScript

JavaScript

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

TypeScript

JavaScript

CSS

HTML

تجربة عيّنة

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

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

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