نظرة عامة

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

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

الجمهور

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

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

مرحبًا بكم

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

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. نحمّل واجهة برمجة تطبيقات جافا سكريبت للخرائط باستخدام برنامج تحميل التشغيل المبدئي.

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

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

برنامج تحميل التشغيل المبدئي هو الطريقة الموصى بها لتحميل واجهة برمجة تطبيقات جافا سكريبت للخرائط. يتم أيضًا توفير برنامج تحميل واجهة برمجة تطبيقات جافا سكريبت كبديل. وننصحك بمراجعة كلا الأسلوبَين، واختيار الأسلوب الأكثر ملاءمةً لطريقة تنظيم الرمز في مشروعك.

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

برنامج التحميل التشغيل المبدئي

حمِّل واجهة برمجة تطبيقات JavaScript للخرائط عن طريق إضافة برنامج تحميل مضمّن للتشغيل المبدئي إلى رمز التطبيق، كما هو موضّح في المقتطف التالي:

<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_HERE",
    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 لـ NPM

استخدم @googlemaps/js-api-loader لاستخدام أداة إدارة نقاط النهاية (NPM) لتحميل واجهة برمجة تطبيقات JavaScript للخرائط. ثبته من خلال 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(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 أيضًا ليحلّ بشكل رائع، ولكن المتصفّحات التي لا تفهم ذلك ستتجاهله وتستخدم "وضع المراوغة" لعرض المحتوى الخاص بها.

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