نظرة عامة

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

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

الجمهور

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

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

مرحبًا بالجميع

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

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

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;
}

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>

    <!-- 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>
الاطّلاع على مثال

تجربة العينة

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

  1. نُعلن عن التطبيق على أنّه HTML5 باستخدام تعريف <!DOCTYPE html>.
  2. ننشئ عنصر div باسم "خريطة" للاحتفاظ بالخريطة.
  3. نحدّد دالة JavaScript لإنشاء خريطة في div.
  4. نحمّل Maps JavaScript API باستخدام برنامج الإقلاع.

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

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

وبرنامج الإقلاع هو الطريقة الموصى بها لتحميل Maps JavaScript API. يتم توفير أداة تحميل واجهة برمجة تطبيقات JavaScript كبديل. وننصحك بمراجعة المنهجَين واختيار الأسلوب الأنسب لبنية الرمز البرمجي في مشروعك.

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

جرّة صغيرة

يمكنك تحميل Maps JavaScript API من خلال إضافة برنامج الإقلاع المضمّن إلى رمز التطبيق، كما هو موضّح في المقتطف التالي:

<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>

لتحميل المكتبات أثناء وقت التشغيل، استخدِم عامل التشغيل await لاستدعاء importLibrary() من داخل دالة غير متزامنة، كما هو موضّح هنا:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

حزمة أداة تحميل js-api-loader لنظام التشغيل NPM

استخدِم @googlemaps/js-api-loader لاستخدام NPM لتحميل واجهة برمجة تطبيقات JavaScript للخرائط. ثبِّت الأداة من خلال NPM باستخدام الأمر التالي:

npm install @googlemaps/js-api-loader

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

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

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

TypeScript

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

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

JavaScript

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

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

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

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

<!DOCTYPE html>

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

تجدر الإشارة إلى أنّ بعض خدمات CSS التي تعمل ضمن وضع Quirks غير صالحة في وضع المعايير. وعلى وجه التحديد، يجب أن تكتسب جميع الأحجام التي تستند إلى النسبة المئوية من عناصر الكتلة الرئيسية، وإذا فشل أي من هذه الكيانات الأصلية في تحديد حجم، يُفترض أن يكون حجمها 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 منفصل. نوصي بمراجعة كلا الأسلوبين، واختيار الأسلوب الأنسب لكيفية هيكلة التعليمات البرمجية في مشروعك.

تحميل مضمّن

لتحميل Maps JavaScript API بشكل مضمّن في ملف HTML، أضِف علامة script كما هو موضّح أدناه.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&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"

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

TypeScript

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

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

JavaScript

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

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

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

لاحظ في الأمثلة أعلاه أنه تم ضبط عدة سمات على العلامة script، والتي ننصح بها. فيما يلي شرح لكل سمة.

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

المكتبات

عند تحميل واجهة برمجة تطبيقات JavaScript للخرائط من خلال عنوان URL، يمكنك اختياريًا تحميل مكتبات إضافية باستخدام عامل التشغيل await لاستدعاء importLibrary() من داخل دالة غير متزامنة. والمكتبات هي وحدات من رموز برمجية توفر وظائف إضافية لواجهة برمجة تطبيقات JavaScript للخرائط الرئيسية ولكن لا يتم تحميلها إلا إذا طلبتها على وجه التحديد. لمزيد من المعلومات، يمكنك الاطّلاع على المكتبات في واجهة برمجة تطبيقات JavaScript للخرائط.

ربط عناصر DOM

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

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

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

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

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

map = new 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 Map(document.getElementById("map"), {...});

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

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

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

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

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

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

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

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

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

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