البدء

اتبع هذه الخطوات لإضافة مكتبة السياقات المحلية إلى مشروعك وتهيئة وعرض خريطة الخريطة المحلية.

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

لاستخدام مكتبة السياقات المحلية، يجب تمكين واجهة برمجة تطبيقات JavaScript للخرائط وواجهة برمجة تطبيقات الأماكن. لتنفيذ ذلك، اتبع التعليمات لتمكين واجهة برمجة تطبيقات واحدة أو أكثر أو حزم SDK. تجدر الإشارة إلى أنّه يجب تفعيل كلّ من واجهة برمجة التطبيقات في المشروع نفسه في Google Cloud Console.

تحميل مكتبة السياقات المحلية

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

• libraries=localContext يحمّل مكتبة السياقات المحلية.
• v=beta مطلوب لاستخدام هذا الإصدار.
• يحتوي key على مفتاح واجهة برمجة التطبيقات.
• ينفِّذ callback الدالة initMap().

يعرض المثال التالي علامة نص برمجي تتضمن جميع الخيارات المذكورة أعلاه:

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

إنشاء عرض خريطة سياق محلي جديد

لإضافة مكتبة السياقات المحلية إلى صفحة ويب، عليك أولاً إنشاء مثيل LocalContextMapView وضبط الخصائص المطلوبة:

• element - العنصر div الذي يجب عرض الخريطة فيه (ويُطلق عليه في هذه الحالة اسم "الخريطة").
• placeTypePreferences - أنواع الأماكن التي يجب أن تعرضها مكتبة السياقات المحلية (ما يصل إلى 10 أماكن).
• maxPlaceCount - أقصى عدد للأماكن المراد عرضها (1 - 24).
• locationRestriction (اختياري) - لتقييد البحث عن الأماكن على موقع جغرافي معيّن. إعداد افتراضي على إطار عرض الخريطة.

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

let map: google.maps.Map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map!;

  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

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

let map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map;
  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

window.initMap = initMap;
index.js

تأجيل تحميل بيانات السياقات المحلية

يمكنك تأجيل تحميل بيانات السياقات المحلية عند بدء الإعداد من خلال ضبط خيار LocalContextMapView maxPlaceCount على 0. ويكون هذا مفيدًا في المواقف التي ترغب في الانتظار فيها حتى يكون المستخدمون مستعدين لرؤية البيانات. عندما تكون مستعدًا لتحميل بيانات السياقات المحلية، اضبط maxPlaceCount على قيمة واحدة أو أكثر. يوضح المثال التالي تهيئة الخريطة بدون تحميل بيانات السياق المحلية، ثم تعيين maxPlaceCount لتحميل البيانات:

// Initialize without Local Context data.
const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.querySelector('#map'),
    placeTypePreferences: ['restaurant'],
    maxPlaceCount: 0, // Avoids an automatic call to load places during initialization.
  });

//...

// Show places now.
localContextMapView.maxPlaceCount = 12;

تبديل عرض واجهة مستخدم السياقات المحلية

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

تعيين الحد الأدنى لأبعاد الخريطة

تعمل مكتبة السياقات المحلية على تغيير العرض بسرعة استنادًا إلى حجم العرض لـ LocalContextMapView. في ما يلي الحد الأدنى للأبعاد المتوافقة في LocalContextMapView:

• 300 بكسل × 480 بكسل (عمودي)
• 480 بكسل × 380 بكسل (أفقي)

عندما ينخفض العنصر المتضمِّن في LocalContextMapView إلى أقل من الحد الأدنى المسموح به من الأبعاد، لا تظهر عناصر "مكتبة السياقات المحلية"، بما في ذلك منتقي الأماكن ونقاط الاهتمام. يؤثر مستوى تكبير/تصغير المتصفح في الحد الأدنى للأبعاد المدعومة؛ على سبيل المثال، في حالة تكبير نافذة المتصفح إلى 200%، يكون الحد الأدنى للأبعاد المدعومة 600 × 960 (عمودي) و960 × 760 (أفقي).

مقترحات CSS

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

• لا تستخدم فئات CSS لمكتبة السياقات المحلية، فقد تتغير بدون إشعار.
• لا تصمِّم نمطًا أو عدِّل أو اختَر عناصر داخل DOM لمكتبة السياقات المحلية.

إذا كنت تستخدم إطار عمل CSS لإجراء مثل هذه التعديلات، فقد تتمكن من العمل على حل أنماط التعارض.

على سبيل المثال، إذا كنت تريد تغيير الصفحة الكلية box-sizing إلى border-box:

• يمكنك استخدام عمليات التجاوز box-sizing التي تُعيِّن العنصر <html> على border-box.
• استخدم box-sizing: initial للعنصر الذي يحتوي على عرض خريطة مكتبة السياقات المحلية.
• استخدم box-sizing: inherit لجميع العناصر الأخرى.

ويضمن ذلك إعادة ضبط عنصر DOM لمكتبة السياقات المحلية box-sizing على الإعداد التلقائي العادي باستخدام محدِّد منخفض الدقة.

في ما يلي الشكل الذي يظهر به ذلك في الشفرة:

html {
  box-sizing: border-box;
}
*, *::before, *::after {
  box-sizing: inherit;
}

.container-for-google-maps {
  box-sizing: initial;
}