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

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

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

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

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

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

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

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

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

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

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

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

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

بالإضافة إلى ذلك، يتم تشغيل مناولة لوحة المفاتيح على جميع الأجهزة افتراضيًا.

تعطيل واجهة المستخدم الافتراضية

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

عرض مثال

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

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io 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

عرض مثال

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

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io 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

عرض مثال

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

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

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

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

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

يتيح zoomControl تفعيل عنصر التحكّم في Zoom أو إيقافه. بشكل افتراضي، يكون عنصر التحكم هذا مرئيًا ويظهر بالقرب من الجانب السفلي الأيسر من الخريطة. يحدّد الحقل 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

عرض مثال

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

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io 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

عرض مثال

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

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io 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

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

عرض مثال

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

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell