تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

عرض مثال

تجربة النموذج

JSFiddle.net Google Cloud Shell

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

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

تظهر بعض عناصر التحكّم على الخريطة تلقائيًا بينما لا تظهر عناصر أخرى ما لم تطلبها على وجه التحديد. يتم تحديد إضافة عناصر التحكّم أو إزالتها من الخريطة في حقول عنصر 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;index.ts

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

عرض مثال

تجربة النموذج

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

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

عرض مثال

تجربة النموذج

JSFiddle.net Google Cloud Shell

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

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

عرض مثال

تجربة النموذج

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

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

عرض مثال

تجربة النموذج

JSFiddle.net Google Cloud Shell

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

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

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

عرض مثال

تجربة النموذج

JSFiddle.net Google Cloud Shell