عناصر التحكّم

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

نظرة عامة على عناصر التحكّم

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

تعرض الخريطة التالية المجموعة التلقائية من عناصر التحكّم التي تعرضها واجهة برمجة تطبيقات JavaScript للخرائط:

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

  • يعرض عنصر التحكم في التكبير/التصغير الزرين "+" و "-" لتغيير مستوى تكبير/تصغير الخريطة. يظهر عنصر التحكّم هذا تلقائيًا في أسفل يسار الخريطة.
  • يتوفر عنصر التحكم في نوع الخريطة في نمط قائمة منسدلة أو نمط شريط أفقي للأزرار، مما يتيح للمستخدم اختيار نوع الخريطة (ROADMAP أو SATELLITE أو HYBRID أو TERRAIN). يظهر عنصر التحكم هذا تلقائيًا في الزاوية العلوية اليمنى من الخريطة.
  • يحتوي عنصر التحكم في "التجوّل الافتراضي" على رمز الدليل الذي يمكن سحبه إلى الخريطة لتفعيل "التجوّل الافتراضي". يظهر عنصر التحكّم هذا بشكل تلقائي بالقرب من أسفل يسار الخريطة.
  • يوفر عنصر التحكم في التدوير مزيجًا من خيارات الإمالة والتدوير للخرائط التي تحتوي على صور مائلة. يظهر عنصر التحكّم هذا تلقائيًا بالقرب من أسفل يسار الخريطة. اطّلِع على صور 45 درجة للحصول على مزيد من المعلومات.
  • يعرض عنصر التحكّم في المقياس عنصر مقياس خريطة. يتم إيقاف عنصر التحكّم هذا تلقائيًا.
  • يوفر خيار التحكم بملء الشاشة خيار فتح الخريطة في وضع ملء الشاشة. يكون عنصر التحكّم هذا مفعَّلاً بشكل تلقائي على أجهزة الكمبيوتر المكتبي والأجهزة الجوّالة. ملاحظة: لا يدعم نظام iOS ميزة ملء الشاشة. وبالتالي، لن يظهر عنصر التحكّم في وضع ملء الشاشة على أجهزة iOS.
  • يعرض عنصر التحكم في اختصارات لوحة المفاتيح قائمة باختصارات لوحة المفاتيح للتفاعل مع الخريطة.

ولا يمكنك الوصول إلى عناصر التحكم في الخريطة هذه أو تعديلها مباشرةً. بدلاً من ذلك، يمكنك تعديل حقول MapOptions على الخريطة، ما يؤثر في إمكانية رؤية عناصر التحكّم وطريقة عرضها. يمكنك ضبط عرض التحكم التقديمي عند إنشاء مثيل لخريطتك (باستخدام MapOptions المناسب) أو تعديل الخريطة ديناميكيًا من خلال طلب setOptions() لتغيير خيارات الخريطة.

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

واجهة المستخدم التلقائية

تختفي جميع عناصر التحكم تلقائيًا إذا كانت الخريطة صغيرة جدًا (200 × 200 بكسل). يمكنك إلغاء هذا السلوك من خلال ضبط عنصر التحكّم بوضوح لكي يكون مرئيًا. راجِع إضافة عناصر تحكّم إلى الخريطة.

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

بالإضافة إلى ذلك، يتم تفعيل التعامل مع لوحة المفاتيح تلقائيًا على جميع الأجهزة.

إيقاف واجهة المستخدم التلقائية

قد ترغب في إيقاف تشغيل أزرار واجهة برمجة التطبيقات الافتراضية بشكل كامل. ولإجراء ذلك، اضبط السمة disableDefaultUI للخريطة (داخل عنصر MapOptions) على true. وتعمل هذه الخاصية على إيقاف أي أزرار تحكّم في واجهة المستخدم من Maps JavaScript API. ومع ذلك، لا يؤثر ذلك في إيماءات الماوس أو اختصارات لوحة المفاتيح على الخريطة الأساسية التي يتم التحكّم فيها من خلال السمتَين gestureHandling وkeyboardShortcuts على التوالي.

يعطل الرمز التالي أزرار واجهة المستخدم:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -33, lng: 151 },
      disableDefaultUI: true,
    }
  );
}

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

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -33, lng: 151 },
    disableDefaultUI: true,
  });
}

window.initMap = initMap;
الاطّلاع على مثال

تجربة العينة

إضافة عناصر التحكم إلى الخريطة

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

تظهر بعض عناصر التحكّم على الخريطة تلقائيًا بينما لن تظهر عناصر أخرى ما لم تطلبها على وجه التحديد. يتم تحديد إضافة عناصر التحكّم أو إزالتها من الخريطة في حقول عناصر MapOptions التالية، والتي تم ضبطها على true لإظهارها أو ضبطها على false لإخفائها:

{
  zoomControl: boolean,
  mapTypeControl: boolean,
  scaleControl: boolean,
  streetViewControl: boolean,
  rotateControl: boolean,
  fullscreenControl: boolean
}

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

حجم الخريطة zoomControl هل أنت مرئي؟
كل النتائج false لا
كل النتائج true نعم
>= 200×200 بكسل undefined نعم
< 200×200 بكسل undefined لا

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

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -33, lng: 151 },
      zoomControl: false,
      scaleControl: true,
    }
  );
}

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

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -33, lng: 151 },
    zoomControl: false,
    scaleControl: true,
  });
}

window.initMap = initMap;
الاطّلاع على مثال

تجربة العينة

خيارات التحكّم

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

يتم تعديل عناصر التحكّم هذه من خلال تغيير حقول خيارات التحكّم المناسبة في العنصر MapOptions عند إنشاء الخريطة.

على سبيل المثال، تتم الإشارة إلى خيارات تغيير عنصر التحكّم في نوع الخريطة في الحقل mapTypeControlOptions. قد يظهر عنصر التحكّم "نوع الخريطة" في أحد خيارات style التالية:

  • تعرض google.maps.MapTypeControlStyle.HORIZONTAL_BAR مجموعة عناصر التحكّم على شكل أزرار في شريط أفقي كما هو موضّح في "خرائط Google".
  • يعرض google.maps.MapTypeControlStyle.DROPDOWN_MENU عنصر تحكم واحدًا يتيح لك اختيار نوع الخريطة من خلال قائمة منسدلة.
  • تعرض علامة google.maps.MapTypeControlStyle.DEFAULT السلوك التلقائي الذي يعتمد على حجم الشاشة وقد يتغيّر في الإصدارات المستقبلية من واجهة برمجة التطبيقات.

يُرجى العِلم أنّه في حال تعديل أي خيارات تحكّم، يجب تفعيل عنصر التحكّم بشكل صريح أيضًا من خلال ضبط قيمة MapOptions المناسبة على true. على سبيل المثال، لضبط عنصر تحكّم لنوع الخريطة لعرض النمط DROPDOWN_MENU، استخدِم الرمز التالي داخل الكائن MapOptions:

  ...
  mapTypeControl: true,
  mapTypeControlOptions: {
    style: google.maps.MapTypeControlStyle.DROPDOWN_MENU
  }
  ...

يوضح المثال التالي كيفية تغيير الوضع التلقائي ونمط عناصر التحكّم.

TypeScript

// You can set control options to change the default position or style of many
// of the map controls.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -33, lng: 151 },
      mapTypeControl: true,
      mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: ["roadmap", "terrain"],
      },
    }
  );
}

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

JavaScript

// You can set control options to change the default position or style of many
// of the map controls.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -33, lng: 151 },
    mapTypeControl: true,
    mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.DROPDOWN_MENU,
      mapTypeIds: ["roadmap", "terrain"],
    },
  });
}

window.initMap = initMap;
الاطّلاع على مثال

تجربة العينة

يتم ضبط عناصر التحكّم عادةً عند إنشاء الخريطة. ومع ذلك، يمكنك تغيير طريقة عرض عناصر التحكّم ديناميكيًا من خلال استدعاء طريقة setOptions() في Map، وتمرير خيارات تحكّم جديدة لها.

تعديل عناصر التحكّم

يمكنك تحديد عرض تقديمي لعنصر تحكّم عند إنشاء الخريطة من خلال حقول داخل كائن MapOptions للخريطة. وتكون هذه الحقول موضّحة أدناه:

  • يفعِّل "zoomControl" عنصر التحكّم في التكبير/التصغير أو يوقفه. يكون عنصر التحكّم هذا مرئيًا بشكل تلقائي ويظهر بالقرب من أسفل يسار الخريطة. بالإضافة إلى ذلك، يحدِّد الحقل zoomControlOptions ZoomControlOptions للاستخدام في عنصر التحكّم هذا.
  • يفعّل/يوقف mapTypeControl عنصر التحكم في نوع الخريطة الذي يتيح للمستخدم التبديل بين أنواع الخرائط (مثل الخريطة والقمر الصناعي). يكون عنصر التحكّم هذا مرئيًا بشكل تلقائي ويظهر في أعلى يمين الخريطة. ويحدّد الحقل mapTypeControlOptions أيضًا العنصر MapTypeControlOptions المطلوب استخدامه لعنصر التحكّم هذا.
  • ويعمل streetViewControl على تفعيل/إيقاف عنصر تحكّم الدليل الذي يتيح للمستخدم تفعيل بانوراما في "التجوّل الافتراضي". يكون عنصر التحكّم هذا مرئيًا بشكل تلقائي ويظهر بالقرب من أسفل يسار الخريطة. ويحدّد الحقل streetViewControlOptions أيضًا العنصر StreetViewControlOptions المطلوب استخدامه لعنصر التحكّم هذا.
  • ويعمل rotateControl على تفعيل/إيقاف ظهور عنصر التحكم في التدوير للتحكم في اتجاه الصور بزاوية 45 درجة. يتم تحديد توفُّر عنصر التحكم تلقائيًا من خلال توفُّر أو عدم توفّر صور بزاوية 45 درجة لنوع الخريطة المحدّد في عمليتَي التكبير أو التصغير الحاليَين وفي الموقع الجغرافي الحالي. يمكنك تغيير سلوك عنصر التحكّم من خلال ضبط rotateControlOptions على الخريطة لتحديد RotateControlOptions لاستخدامها. ولا يمكنك إظهار عنصر التحكم إذا لم تتوفر صور بزاوية 45 درجة حاليًا.
  • ويعمل scaleControl على تفعيل/إيقاف عنصر التحكّم في "المقياس" الذي يقدّم مقياس خريطة بسيطًا. بشكل تلقائي، لا يكون عنصر التحكّم هذا مرئيًا. عند التفعيل، ستظهر دائمًا في أسفل الجانب الأيسر من الخريطة. وتحدّد السمة scaleControlOptions بالإضافة إلى ذلك ScaleControlOptions التي سيتم استخدامها في عنصر التحكّم هذا.
  • يعمل fullscreenControl على تفعيل/إيقاف عنصر التحكّم الذي يفتح الخريطة في وضع ملء الشاشة. يتم تلقائيًا تفعيل عنصر التحكّم هذا على أجهزة الكمبيوتر المكتبي وأجهزة Android. عند التفعيل، يظهر عنصر التحكم بالقرب من أعلى يسار الخريطة. وتحدّد السمة fullscreenControlOptions بالإضافة إلى ذلك FullscreenControlOptions التي سيتم استخدامها في عنصر التحكّم هذا.

تجدر الإشارة إلى أنّه يمكنك تحديد خيارات عناصر التحكّم التي أوقفتها في البداية.

التحكم في الموضع

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

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

تتوفّر مواضع التحكّم التالية:

  • تشير السمة TOP_CENTER إلى أنه يجب وضع عنصر التحكّم في أعلى منتصف الخريطة.
  • تشير السمة TOP_LEFT إلى أنّه يجب وضع عنصر التحكّم على الجانب العلوي الأيسر من الخريطة مع وضع أي عناصر فرعية من عنصر التحكّم "متدفق" باتجاه الجزء العلوي الأوسط.
  • تشير السمة TOP_RIGHT إلى أنّه يجب وضع عنصر التحكّم على طول الجزء العلوي الأيمن من الخريطة، مع وضع أي عناصر فرعية من عنصر التحكّم "متدفق" باتجاه الجزء العلوي الأوسط.
  • تشير السمة LEFT_TOP إلى أنّه يجب وضع عنصر التحكّم على طول الجزء العلوي الأيسر من الخريطة، ولكن أسفل أيّ من عناصر TOP_LEFT.
  • تشير السمة RIGHT_TOP إلى أنّه يجب وضع عنصر التحكّم على طول الجزء العلوي الأيسر من الخريطة، ولكن تحت جميع عناصر TOP_RIGHT.
  • تشير السمة LEFT_CENTER إلى أنّه يجب وضع عنصر التحكّم على الجانب الأيسر من الخريطة في وسطه بين موضعَي TOP_LEFT وBOTTOM_LEFT.
  • تشير السمة RIGHT_CENTER إلى أنّه يجب وضع عنصر التحكّم على الجانب الأيمن من الخريطة، وأن يتم توسيطه بين موضعَي TOP_RIGHT وBOTTOM_RIGHT.
  • تشير السمة LEFT_BOTTOM إلى أنّه يجب وضع عنصر التحكّم أسفل يمين الخريطة، ولكن فوق أيّ من عناصر BOTTOM_LEFT.
  • تشير السمة RIGHT_BOTTOM إلى أنّه يجب وضع عنصر التحكّم أسفل يسار الخريطة، ولكن فوق أيّ من عناصر BOTTOM_RIGHT.
  • تشير السمة BOTTOM_CENTER إلى أنّه يجب وضع عنصر التحكّم على طول منتصف الجزء السفلي من الخريطة.
  • تشير السمة BOTTOM_LEFT إلى أنّه يجب وضع عنصر التحكّم على طول الجزء السفلي الأيسر من الخريطة، مع وضع أي عناصر فرعية من عنصر التحكّم "متدفق" باتجاه وسط الجزء السفلي.
  • تشير السمة BOTTOM_RIGHT إلى أنّه يجب وضع عنصر التحكّم أسفل يمين الخريطة، مع وضع أي عناصر فرعية من عنصر التحكّم "متدفق" باتجاه وسط الجزء السفلي.

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

يعرض المثال التالي خريطة بسيطة تم تفعيل جميع عناصر التحكّم بها في مواضع مختلفة.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 12,
      center: { lat: -28.643387, lng: 153.612224 },
      mapTypeControl: true,
      mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
        position: google.maps.ControlPosition.TOP_CENTER,
      },
      zoomControl: true,
      zoomControlOptions: {
        position: google.maps.ControlPosition.LEFT_CENTER,
      },
      scaleControl: true,
      streetViewControl: true,
      streetViewControlOptions: {
        position: google.maps.ControlPosition.LEFT_TOP,
      },
      fullscreenControl: true,
    }
  );
}

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

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: -28.643387, lng: 153.612224 },
    mapTypeControl: true,
    mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
      position: google.maps.ControlPosition.TOP_CENTER,
    },
    zoomControl: true,
    zoomControlOptions: {
      position: google.maps.ControlPosition.LEFT_CENTER,
    },
    scaleControl: true,
    streetViewControl: true,
    streetViewControlOptions: {
      position: google.maps.ControlPosition.LEFT_TOP,
    },
    fullscreenControl: true,
  });
}

window.initMap = initMap;
الاطّلاع على مثال

تجربة العينة

عناصر التحكّم المخصَّصة

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

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

  • تحديد CSS المناسب لعناصر التحكم المراد عرضها.
  • معالجة التفاعل مع المستخدم أو الخريطة من خلال معالِجات الأحداث لتغييرات سمات الخريطة أو أحداث المستخدم (على سبيل المثال، أحداث 'click').
  • أنشِئ عنصر <div> للاحتفاظ بعنصر التحكّم وإضافة هذا العنصر إلى السمة controls في Map.

تمت مناقشة كل من هذه الاستفسارات في ما يلي.

رسم عناصر التحكم المخصصة

إن كيفية رسم عناصر التحكم أمر متروك لك. وبشكلٍ عام، ننصحك بوضع كل عروض التحكّم الخاصة بك ضمن عنصر <div> واحد حتى تتمكّن من التحكّم في عنصر التحكّم كوحدة واحدة. سنستخدم نمط التصميم هذا في النماذج الموضحة أدناه.

يتطلب تصميم عناصر تحكُّم جذابة بعض المعرفة ببنية CSS وDOM. يُظهر الرمز التالي دالة لإنشاء عنصر زر يحرّك الخريطة لتحديد مركزها على مدينة شيكاغو.

function createCenterControl(map) {
  const controlButton = document.createElement("button");

  // Set CSS for the control.
  controlButton.style.backgroundColor = "#fff";
  controlButton.style.border = "2px solid #fff";
  controlButton.style.borderRadius = "3px";
  controlButton.style.boxShadow = "0 2px 6px rgba(0,0,0,.3)";
  controlButton.style.color = "rgb(25,25,25)";
  controlButton.style.cursor = "pointer";
  controlButton.style.fontFamily = "Roboto,Arial,sans-serif";
  controlButton.style.fontSize = "16px";
  controlButton.style.lineHeight = "38px";
  controlButton.style.margin = "8px 0 22px";
  controlButton.style.padding = "0 5px";
  controlButton.style.textAlign = "center";

  controlButton.textContent = "Center Map";
  controlButton.title = "Click to recenter the map";
  controlButton.type = "button";

  // Setup the click event listeners: simply set the map to Chicago.
  controlButton.addEventListener("click", () => {
    map.setCenter(chicago);
  });

  return controlButton;
}

التعامل مع الأحداث من عناصر التحكم المخصصة

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

للاستجابة للبيانات التي أدخلها المستخدم، يمكنك استخدام addEventListener()، الذي يعالج أحداث DOM. يضيف مقتطف الرمز التالي أداة معالجة لحدث 'click' في المتصفِّح. تجدر الإشارة إلى أنّه يتم تلقّي هذا الحدث من نموذج العناصر في المستند (DOM)، وليس من الخريطة.

// Setup the click event listener: set the map to center on Chicago
var chicago = {lat: 41.850, lng: -87.650};

controlButton.addEventListener('click', () => {
  map.setCenter(chicago);
});

إتاحة الوصول إلى عناصر التحكّم المخصَّصة

لضمان تلقّي عناصر التحكّم لأحداث لوحة المفاتيح وظهورها بشكل صحيح لبرامج قراءة الشاشة، عليك إجراء ما يلي:

  • استخدم دائمًا عناصر HTML الأصلية للأزرار وعناصر النموذج والتسميات. لا تستخدم عنصر DIV إلا كحاوية للاحتفاظ بعناصر التحكم الأصلية، ولا تستخدم أبدًا عنصر DIV كعنصر واجهة مستخدم تفاعلي.
  • يمكنك استخدام العنصر label أو السمة title أو السمة aria-label متى كان ذلك مناسبًا لتقديم معلومات حول عنصر في واجهة المستخدم.

وضع عناصر التحكم المخصصة في المكان

يتم وضع عناصر التحكّم المخصّصة على الخريطة من خلال وضعها في مواضع مناسبة ضمن السمة controls الخاصة بالكائن Map. تحتوي هذه السمة على مصفوفة من google.maps.ControlPosition. يمكنك إضافة عنصر تحكّم مخصّص إلى الخريطة عن طريق إضافة Node (عادةً <div>) إلى ControlPosition مناسب. (للحصول على معلومات عن هذه المناصب، يُرجى مراجعة تحديد الموضع أعلاه.)

يخزِّن كل ControlPosition عنصر MVCArray من عناصر التحكّم المعروضة في هذا الموضع. ونتيجةً لذلك، عند إضافة عناصر التحكّم أو إزالتها من موضعها، ستعدِّل واجهة برمجة التطبيقات عناصر التحكّم وفقًا لذلك.

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

يعمل الرمز التالي على إنشاء عنصر تحكّم مخصّص جديد (لا يتم عرض أداة الإنشاء الخاصة به) ويضيفه إلى الخريطة في الموضع TOP_RIGHT.

var map = new google.maps.Map(document.getElementById('map'), mapOptions);

// Create a DIV to attach the control UI to the Map.
const centerControlDiv = document.createElement("div");

// Create the control. This code calls a function that
// creates a new instance of a button control.
const centerControl = createCenterControl(map);

// Append the control to the DIV.
centerControlDiv.appendChild(centerControl);

// Add the control to the map at a designated control position
// by pushing it on the position's array. This code will
// implicitly add the control to the DOM, through the Map
// object. You should not attach the control manually.
map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);

مثال على عنصر تحكّم مخصّص

إنّ عنصر التحكّم التالي بسيط (ولكنه ليس مفيدًا بشكل خاص) ويجمع بين الأنماط المتوفّرة أعلاه. يستجيب عنصر التحكّم هذا لأحداث DOM 'click' من خلال توسيط الخريطة في موقع تلقائي معيّن:

TypeScript

let map: google.maps.Map;

const chicago = { lat: 41.85, lng: -87.65 };

/**
 * Creates a control that recenters the map on Chicago.
 */
 function createCenterControl(map) {
  const controlButton = document.createElement('button');

  // Set CSS for the control.
  controlButton.style.backgroundColor = '#fff';
  controlButton.style.border = '2px solid #fff';
  controlButton.style.borderRadius = '3px';
  controlButton.style.boxShadow = '0 2px 6px rgba(0,0,0,.3)';
  controlButton.style.color = 'rgb(25,25,25)';
  controlButton.style.cursor = 'pointer';
  controlButton.style.fontFamily = 'Roboto,Arial,sans-serif';
  controlButton.style.fontSize = '16px';
  controlButton.style.lineHeight = '38px';
  controlButton.style.margin = '8px 0 22px';
  controlButton.style.padding = '0 5px';
  controlButton.style.textAlign = 'center';

  controlButton.textContent = 'Center Map';
  controlButton.title = 'Click to recenter the map';
  controlButton.type = 'button';

  // Setup the click event listeners: simply set the map to Chicago.
  controlButton.addEventListener('click', () => {
    map.setCenter(chicago);
  });

  return controlButton;
}

function initMap() {
  map = new google.maps.Map(document.getElementById('map') as HTMLElement, {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control.
  const centerControlDiv = document.createElement('div');
  // Create the control.
  const centerControl = createCenterControl(map);
  // Append the control to the DIV.
  centerControlDiv.appendChild(centerControl);

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

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

JavaScript

let map;
const chicago = { lat: 41.85, lng: -87.65 };

/**
 * Creates a control that recenters the map on Chicago.
 */
function createCenterControl(map) {
  const controlButton = document.createElement("button");

  // Set CSS for the control.
  controlButton.style.backgroundColor = "#fff";
  controlButton.style.border = "2px solid #fff";
  controlButton.style.borderRadius = "3px";
  controlButton.style.boxShadow = "0 2px 6px rgba(0,0,0,.3)";
  controlButton.style.color = "rgb(25,25,25)";
  controlButton.style.cursor = "pointer";
  controlButton.style.fontFamily = "Roboto,Arial,sans-serif";
  controlButton.style.fontSize = "16px";
  controlButton.style.lineHeight = "38px";
  controlButton.style.margin = "8px 0 22px";
  controlButton.style.padding = "0 5px";
  controlButton.style.textAlign = "center";
  controlButton.textContent = "Center Map";
  controlButton.title = "Click to recenter the map";
  controlButton.type = "button";
  // Setup the click event listeners: simply set the map to Chicago.
  controlButton.addEventListener("click", () => {
    map.setCenter(chicago);
  });
  return controlButton;
}

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control.
  const centerControlDiv = document.createElement("div");
  // Create the control.
  const centerControl = createCenterControl(map);

  // Append the control to the DIV.
  centerControlDiv.appendChild(centerControl);
  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

window.initMap = initMap;
الاطّلاع على مثال

تجربة العينة

إضافة حالة إلى عناصر التحكّم

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

TypeScript

let map: google.maps.Map;

const chicago: google.maps.LatLngLiteral = { lat: 41.85, lng: -87.65 };

/**
 * The CenterControl adds a control to the map that recenters the map on
 * Chicago.
 */
class CenterControl {
  private map_: google.maps.Map;
  private center_: google.maps.LatLng;
  constructor(
    controlDiv: HTMLElement,
    map: google.maps.Map,
    center: google.maps.LatLngLiteral
  ) {
    this.map_ = map;
    // Set the center property upon construction
    this.center_ = new google.maps.LatLng(center);
    controlDiv.style.clear = "both";

    // Set CSS for the control border
    const goCenterUI = document.createElement("button");

    goCenterUI.id = "goCenterUI";
    goCenterUI.title = "Click to recenter the map";
    controlDiv.appendChild(goCenterUI);

    // Set CSS for the control interior
    const goCenterText = document.createElement("div");

    goCenterText.id = "goCenterText";
    goCenterText.innerHTML = "Center Map";
    goCenterUI.appendChild(goCenterText);

    // Set CSS for the setCenter control border
    const setCenterUI = document.createElement("button");

    setCenterUI.id = "setCenterUI";
    setCenterUI.title = "Click to change the center of the map";
    controlDiv.appendChild(setCenterUI);

    // Set CSS for the control interior
    const setCenterText = document.createElement("div");

    setCenterText.id = "setCenterText";
    setCenterText.innerHTML = "Set Center";
    setCenterUI.appendChild(setCenterText);

    // Set up the click event listener for 'Center Map': Set the center of
    // the map
    // to the current center of the control.
    goCenterUI.addEventListener("click", () => {
      const currentCenter = this.center_;

      this.map_.setCenter(currentCenter);
    });

    // Set up the click event listener for 'Set Center': Set the center of
    // the control to the current center of the map.
    setCenterUI.addEventListener("click", () => {
      const newCenter = this.map_.getCenter()!;

      if (newCenter) {
        this.center_ = newCenter;
      }
    });
  }
}

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control and call the CenterControl()
  // constructor passing in this DIV.
  const centerControlDiv = document.createElement("div");
  const control = new CenterControl(centerControlDiv, map, chicago);

  // @ts-ignore
  centerControlDiv.index = 1;
  centerControlDiv.style.paddingTop = "10px";
  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

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

JavaScript

let map;
const chicago = { lat: 41.85, lng: -87.65 };

/**
 * The CenterControl adds a control to the map that recenters the map on
 * Chicago.
 */
class CenterControl {
  map_;
  center_;
  constructor(controlDiv, map, center) {
    this.map_ = map;
    // Set the center property upon construction
    this.center_ = new google.maps.LatLng(center);
    controlDiv.style.clear = "both";

    // Set CSS for the control border
    const goCenterUI = document.createElement("button");

    goCenterUI.id = "goCenterUI";
    goCenterUI.title = "Click to recenter the map";
    controlDiv.appendChild(goCenterUI);

    // Set CSS for the control interior
    const goCenterText = document.createElement("div");

    goCenterText.id = "goCenterText";
    goCenterText.innerHTML = "Center Map";
    goCenterUI.appendChild(goCenterText);

    // Set CSS for the setCenter control border
    const setCenterUI = document.createElement("button");

    setCenterUI.id = "setCenterUI";
    setCenterUI.title = "Click to change the center of the map";
    controlDiv.appendChild(setCenterUI);

    // Set CSS for the control interior
    const setCenterText = document.createElement("div");

    setCenterText.id = "setCenterText";
    setCenterText.innerHTML = "Set Center";
    setCenterUI.appendChild(setCenterText);
    // Set up the click event listener for 'Center Map': Set the center of
    // the map
    // to the current center of the control.
    goCenterUI.addEventListener("click", () => {
      const currentCenter = this.center_;

      this.map_.setCenter(currentCenter);
    });
    // Set up the click event listener for 'Set Center': Set the center of
    // the control to the current center of the map.
    setCenterUI.addEventListener("click", () => {
      const newCenter = this.map_.getCenter();

      if (newCenter) {
        this.center_ = newCenter;
      }
    });
  }
}

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control and call the CenterControl()
  // constructor passing in this DIV.
  const centerControlDiv = document.createElement("div");
  const control = new CenterControl(centerControlDiv, map, chicago);

  // @ts-ignore
  centerControlDiv.index = 1;
  centerControlDiv.style.paddingTop = "10px";
  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

window.initMap = initMap;
الاطّلاع على مثال

تجربة العينة