عناصر التحكم

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

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

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

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

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

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

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

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

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

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

يكون سلوك عناصر التحكّم ومظهرها متطابقًا على الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي، باستثناء عنصر التحكّم في ملء الشاشة (اطّلِع على السلوك описанًا في قائمة عناصر التحكّم).

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

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

قد تحتاج إلى إيقاف أزرار واجهة المستخدم التلقائية لواجهة برمجة التطبيقات بالكامل. لإجراء ذلك، اضبط سمة disableDefaultUI للخريطة (ضمن العنصر MapOptions) على true. تعمل هذه السمة على إيقاف أي أزرار تحكّم في واجهة المستخدم من واجهة برمجة التطبيقات JavaScript لخرائط Google. ومع ذلك، لا يؤثّر ذلك في إيماءات الماوس أو اختصارات لوحة المفاتيح على القاعدة الخريطة، والتي يتم التحكّم فيها من خلال السمتَين 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;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

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

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

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

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

{
  zoomControl: boolean,
  cameraControl: 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;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

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;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

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

يتم تعديل عناصر التحكّم هذه من خلال تغيير حقول خيارات التحكّم المناسبة ضمن عنصر 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;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

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;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

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

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

• zoomControl تفعِّل/توقِف عنصر التحكّم في التكبير/التصغير. بشكلٍ تلقائي، يكون هذا الزر مرئيًا ويظهر بالقرب من أسفل يسار الخريطة. يحدِّد الحقل zoomControlOptions بالإضافة إلى ذلك ZoomControlOptions الذي سيتم استخدامه مع عنصر التحكّم هذا.
• cameraControl تفعِّل/توقِف ميزة التحكّم في الكاميرا. يظهر هذا العنصر التحكّمي تلقائيًا على الخرائط باستخدام قناة الإصدار التجريبي. يحدِّد الحقل cameraControlOptions أيضًا CameraControlOptions المراد استخدامه مع عنصر التحكّم هذا.
• mapTypeControl تفعّل/توقِف عنصر التحكّم في "نوع الخريطة" الذي يتيح للمستخدم التبديل بين أنواع الخرائط (مثل الخريطة والمشاهدة من الأقمار الصناعية). يظهر هذا العنصر بشكل تلقائي في أعلى يمين الخريطة. يحدِّد حقل mapTypeControlOptions بالإضافة إلى ذلك MapTypeControlOptions المراد استخدامه مع عنصر التحكّم هذا.
• streetViewControl تفعِّل/توقِف عنصر التحكّم في Pegman الذي يتيح للمستخدم تفعيل صورة بانورامية في "التجوّل الافتراضي". تكون أداة التحكّم هذه مرئية تلقائيًا وتظهر بالقرب من أسفل يسار الخريطة. يحدِّد حقل 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;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

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;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

بالإضافة إلى تعديل نمط عناصر التحكّم الحالية لواجهة برمجة التطبيقات وموقعها، يمكنك إنشاء عناصر التحكّم الخاصة بك للتعامل مع التفاعل مع المستخدم. عناصر التحكّم هي تطبيقات مصغّرة ثابتة تطفو فوق الخريطة في مواضع مطلقة، على عكس التراكبات التي تتحرك مع الخريطة الأساسية. بشكلٍ أساسي، عنصر التحكّم هو عنصر <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;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

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;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

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

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;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

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;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell