نظرة عامة

اختيار نظام أساسي: Android iOS JavaScript

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

الجمهور

صُمِّم هذا المستند للأشخاص المألوفين لبرمجة JavaScript ومفاهيم البرمجة المُوجَّهة إلى العناصر. ومن الضروري أيضًا أن تكون على دراية بخدمة خرائط Google من وجهة نظر المستخدم. يتوفّر العديد من البرامج التعليمية للغة JavaScript على الويب.

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

مرحبًا بكم

تتمثل أسهل طريقة لبدء التعرّف على واجهة برمجة تطبيقات JavaScript JavaScript في الاطّلاع على مثال بسيط. يعرض المثال التالي خريطة تتمركز على سيدني، نيو ساوث ويلز، أستراليا.

TypeScript

let map: google.maps.Map;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = 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>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises
      with https://www.npmjs.com/package/@googlemaps/js-api-loader.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html
عرض مثال

تجربة النموذج

حتى في هذا المثال البسيط، هناك بعض الأمور التي يجب ملاحظتها:

  1. نعلن التطبيق كـ HTML5 باستخدام التعريف <!DOCTYPE html>.
  2. ننشئ عنصر div باسم "الخريطة" للاحتفاظ بالخريطة.
  3. نحدّد دالة JavaScript التي تنشئ خريطة في div.
  4. يتم تحميل واجهة برمجة تطبيقات JavaScript للخرائط باستخدام علامة script.

نوضح في ما يلي هاتين الخطوتين.

الإعلان عن تطبيقك باعتباره HTML5

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

<!DOCTYPE html>

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

لاحظ أن بعض CSS التي تعمل في وضع المراوغة غير صالحة في وضع المعايير. وعلى وجه التحديد، يجب أن تكتسب جميع الأحجام التي تستند إلى النسبة المئوية من عناصر القالب الأصلي، وإذا أخفق أي من هذه الأجناس في تحديد حجم، فمن المفترض أن يتم تحديد حجمها على 0 × 0 بكسل. ولهذا السبب، نُدرج بيان <style> التالي:

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

يشير بيان خدمة مقارنة الأسعار (CSS) هذا إلى أن حاوية الخريطة <div> (التي تحتوي على المعرّف map) يجب أن تشغل 100% من ارتفاع نص HTML. يُرجى العِلم أنّنا يجب تحديد هذه النِسب المئوية للخاصية <body> و<html> أيضًا.

تحميل واجهة برمجة تطبيقات JavaScript للخرائط

يتم تحميل واجهة برمجة تطبيقات JavaScript للخرائط باستخدام علامة script التي يمكن إضافتها مضمّنة في ملف HTML أو ديناميكيًا باستخدام ملف JavaScript منفصل. ونحن نوصي بمراجعة كلا الأسلوبين، واختيار الأسلوب الأنسب لطريقة تنظيم الشفرة في مشروعك.

التحميل المضمن

لتحميل واجهة برمجة تطبيقات JavaScript JavaScript للخرائط في ملف HTML، أضِف علامة script كما هو موضّح أدناه.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

التحميل الديناميكي

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

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

التحميل الديناميكي

تتوفر حزمة @googlemaps/js-api-loader لتسهيل تجربة التحميل الديناميكي. ويمكن تثبيته من خلال NPM مع ما يلي:

npm install @googlemaps/js-api-loader

يمكن استيراد هذه الحزمة إلى التطبيق باستخدام:

import { Loader } from "@googlemaps/js-api-loader"

يعرض برنامج التحميل واجهة الوعد ومعاودة الاتصال. في ما يلي شرح لاستخدام طريقة الوعد التلقائي load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

سمات علامة النص البرمجي

يُرجى العِلم أنّه في الأمثلة أعلاه، تمّ ضبط سمات متعدّدة على العلامة script، ويُنصَح باستخدامها. في ما يلي شرح لكل سمة.

  • src: عنوان URL الذي يتم تحميل واجهة برمجة تطبيقات JavaScript للخرائط منه، بما في ذلك جميع الرموز والتعريفات التي تحتاجها لاستخدام واجهة برمجة تطبيقات JavaScript للخرائط يحتوي عنوان URL في هذا المثال على معلمتين: key، حيث يمكنك تقديم مفتاح واجهة برمجة التطبيقات، وcallback، حيث يمكنك تحديد اسم دالة عمومية ليتم استدعاؤها بعد تحميل واجهة برمجة تطبيقات JavaScript للخرائط. مزيد من المعلومات عن معلمات عناوين URL.
  • async: يطلب من المتصفح تنزيل النص البرمجي وتنفيذه بشكل غير متزامن. عند تنفيذ النص البرمجي، سيستدعي الدالة المحددة باستخدام المَعلمة callback.

المكتبات

عند تحميل واجهة برمجة تطبيقات JavaScript للخرائط عبر عنوان URL، يمكنك اختياريًا تحميل مكتبات إضافية من خلال استخدام معلّمة عنوان URL libraries. المكتبات هي وحدات من الرموز توفر وظائف إضافية لواجهة برمجة تطبيقات JavaScript للخرائط الرئيسية، ولكن لا يتم تحميلها ما لم تطلبها تحديدًا. لمزيد من المعلومات، اطّلع على المكتبات في واجهة برمجة تطبيقات JavaScript للخرائط.

تحميل واجهة برمجة التطبيقات بشكل متزامن

في العلامة script التي تحمّل واجهة برمجة تطبيقات JavaScript للخرائط، من الممكن حذف السمة defer والمعلمة callback. سيؤدي ذلك إلى حظر تحميل واجهة برمجة التطبيقات إلى أن يتم تنزيل واجهة برمجة التطبيقات.

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

تعيين عناصر DOM للخريطة

<div id="map"></div>

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

في المثال أعلاه، استخدمنا CSS لضبط ارتفاع عنصر div للخريطة على "100%". سيؤدي هذا إلى التوسيع ليتناسب مع الحجم على أجهزة الجوّال. قد تحتاج إلى ضبط قيمتَي العرض والارتفاع استنادًا إلى حجم شاشة المتصفّح والمساحة المتروكة. ملاحظة: غالبًا ما يأخذ عنصر div العرض من العنصر المتضمّن له، وعادة ما تكون قيمة عنصر div فارغًا. لهذا السبب، يجب دائمًا ضبط ارتفاع على <div> بشكل صريح.

خيارات الخريطة

هناك خياران مطلوبان لكل خريطة: center وzoom.

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

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

يتم ضبط درجة الدقة الأولية التي يتم عرض الخريطة بها باستخدام السمة zoom، حيث يتوافق التكبير أو التصغير 0 مع خريطة للأرض تم تصغيرها بالكامل، ويتم تكبير مستويات التكبير بدرجة دقة أعلى.

zoom: 8

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

  • 1: العالم
  • 5: مساحة اليابسة/القارة
  • 10: مدينة
  • 15: الشوارع
  • 20: المباني

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

للحصول على معلومات حول كيفية تحميل واجهة برمجة تطبيقات JavaScript للخرائط في أقسام بناءً على مستوى التكبير أو التصغير الحالي، يمكنك الاطّلاع على دليل إحداثيات الخريطة والمربع.

كائن الخريطة

map = new google.maps.Map(document.getElementById("map"), {...});

إن فئة JavaScript التي تمثل الخريطة هي فئة Map. تحدد كائنات هذه الفئة خريطة واحدة في الصفحة. (يمكنك إنشاء أكثر من مثيل واحد من هذه الفئة، إذ سيحدّد كل عنصر خريطة منفصلة على الصفحة). ننشئ نسخة جديدة من هذه الفئة باستخدام عامل تشغيل JavaScript new.

عند إنشاء مثيل خريطة جديد، عليك تحديد عنصر HTML <div> في الصفحة كحاوية للخريطة. عُقد HTML هي عناصر فرعية للعنصر document من JavaScript، ونحصل على مرجع لهذا العنصر عبر طريقة document.getElementById().

يحدّد هذا الرمز متغيّرًا (باسم map) ويحدّد هذا المتغير كائن Map جديدًا. تُعرف الدالة Map() باسم constructor ويتم توضيح تعريفها أدناه:

الشركة المصنِّعة الوصف
Map(mapDiv:Node, opts?:MapOptions ) لإنشاء خريطة جديدة داخل حاوية HTML المحددة — والتي تكون عادة عنصر DIV — باستخدام أي معلمات (اختياري) تم تمريرها.

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

مفتاح واجهة برمجة التطبيقات وأخطاء الفوترة

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

إذا لم يعمل الرمز:

لمساعدتك في إعداد ترميز خرائطك وتشغيلها، يشير بريندان كيني ومانو ماركس إلى بعض الأخطاء الشائعة وكيفية إصلاحها في هذا الفيديو.

  • ابحث عن الأخطاء الإملائية. تذكّر أنّ JavaScript هي لغة حسّاسة لحالة الأحرف.
  • تحقق من الأساسيات - وتحدث بعض المشاكل الأكثر شيوعًا عند إنشاء الخريطة الأولية. مثلاً:
    • تأكّد من تحديد الخاصيتين zoom وcenter في خيارات الخريطة.
    • تأكد من أنك حددت عنصر div ستظهر فيه الخريطة على الشاشة.
    • تأكد من ارتفاع عنصر div للخريطة. بشكل تلقائي، يتم إنشاء عناصر div بارتفاع 0، وبالتالي تكون غير مرئية.
    يمكنك الرجوع إلى أمثلتنا عن تنفيذ المرجع.
  • استخدِم برنامج تصحيح جافا سكريبت للمساعدة في تحديد المشاكل، مثل المشكلة المتوفّرة في أدوات مطوّري برامج Chrome. ابدأ بالبحث في وحدة تحكم JavaScript عن الأخطاء.
  • انشر الأسئلة على تجاوز حزمة الفلاتر. تتوفر إرشادات حول كيفية نشر أسئلة رائعة في صفحة الدعم.