عناصر التحكم

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

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

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

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

في اتجاه عقارب الساعة من أعلى اليمين: نوع الخريطة، ملء الشاشة، الكاميرا، "التجوّل الافتراضي"، اختصارات لوحة المفاتيح

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

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

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

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

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

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

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

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

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

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

يؤدي الرمز التالي إلى إيقاف أزرار واجهة المستخدم:

TypeScript

innerMap.setOptions({
    // Disable the default UI.
    disableDefaultUI: true,
});
index.ts

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

JavaScript

innerMap.setOptions({
    // Disable the default UI.
    disableDefaultUI: true,
});
index.js

ملحوظة: يتم تجميع كود جافا سكريبت من جزء من كود تايب سكريبت.

عرض المثال

جرب العينة

JSFiddle.net

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

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

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

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

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

حجم الخريطة	cameraControl	مرئي؟
أي	false	لا
أي	true	نعم
≥ 200×200 بكسل	undefined	نعم
< 200x200 بكسل	undefined	لا

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

TypeScript

innerMap.setOptions({
    cameraControl: false,
    scaleControl: true,
});
index.ts

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

JavaScript

innerMap.setOptions({
    cameraControl: false,
    scaleControl: true,
});
index.js

ملحوظة: يتم تجميع كود جافا سكريبت من جزء من كود تايب سكريبت.

عرض المثال

جرب العينة

JSFiddle.net

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

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

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

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

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

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

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

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

TypeScript

innerMap.setOptions({
    mapTypeControl: true,
    mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: [
            google.maps.MapTypeId.ROADMAP,
            google.maps.MapTypeId.TERRAIN,
        ],
        position: google.maps.ControlPosition.TOP_CENTER,
    },
});
index.ts

ملحوظة: اقرأمرشد حول استخدام TypeScript وخرائط جوجل.

JavaScript

innerMap.setOptions({
    mapTypeControl: true,
    mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: [
            google.maps.MapTypeId.ROADMAP,
            google.maps.MapTypeId.TERRAIN,
        ],
        position: google.maps.ControlPosition.TOP_CENTER,
    },
});
index.js

ملحوظة: يتم تجميع كود جافا سكريبت من جزء من كود تايب سكريبت.

عرض المثال

جرب العينة

JSFiddle.net

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

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

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

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

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

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

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

هناك نوعان من مواضع عنصر التحكّم: قديم ومنطقي. يُنصح باستخدام القيم المنطقية لتتمكّن من توفير الدعم تلقائيًا لكل من سياقات التنسيق من اليمين إلى اليسار (RTL) ومن اليسار إلى اليمين (LTR). الاطّلاع على دليل المراجع

تعرض الجداول التالية مواضع عناصر التحكّم المتوافقة في سياقات من اليمين إلى اليسار ومن اليسار إلى اليمين.

وظائف العلاقات طويلة الأمد

الوضع (في سياق اتجاه الانعكاس)	الثابت المنطقي (موصى به)	ثابت الإرث
أعلى اليسار	BLOCK_START_INLINE_START	TOP_LEFT
أعلى المنتصف	BLOCK_START_INLINE_CENTER	TOP_CENTER
أعلى اليمين	BLOCK_START_INLINE_END	TOP_RIGHT
الأعلى الأيسر	INLINE_START_BLOCK_START	LEFT_TOP
الوسط الأيسر	INLINE_START_BLOCK_CENTER	LEFT_CENTER
الأسفل الأيسر	INLINE_START_BLOCK_END	LEFT_BOTTOM
أعلى اليمين	INLINE_END_BLOCK_START	RIGHT_TOP
المركز الأيمن	INLINE_END_BLOCK_CENTER	RIGHT_CENTER
الأسفل الأيمن	INLINE_END_BLOCK_END	RIGHT_BOTTOM
أسفل اليسار	BLOCK_END_INLINE_START	BOTTOM_LEFT
المركز السفلي	BLOCK_END_INLINE_CENTER	BOTTOM_CENTER
أسفل اليمين	BLOCK_END_INLINE_END	BOTTOM_RIGHT

مواقع RTL

الموضع (سياق الكتابة من اليمين إلى اليسار)	الثابت المنطقي (موصى به)	ثابت الإرث
أعلى اليمين	BLOCK_START_INLINE_START	TOP_RIGHT
أعلى المنتصف	BLOCK_START_INLINE_CENTER	TOP_CENTER
أعلى اليسار	BLOCK_START_INLINE_END	TOP_LEFT
أعلى اليمين	INLINE_START_BLOCK_START	RIGHT_TOP
المركز الأيمن	INLINE_START_BLOCK_CENTER	RIGHT_CENTER
الأسفل الأيمن	INLINE_START_BLOCK_END	RIGHT_BOTTOM
الأعلى الأيسر	INLINE_END_BLOCK_START	LEFT_TOP
الوسط الأيسر	INLINE_END_BLOCK_CENTER	LEFT_CENTER
الأسفل الأيسر	INLINE_END_BLOCK_END	LEFT_BOTTOM
أسفل اليمين	BLOCK_END_INLINE_START	BOTTOM_RIGHT
المركز السفلي	BLOCK_END_INLINE_CENTER	BOTTOM_CENTER
أسفل اليسار	BLOCK_END_INLINE_END	BOTTOM_LEFT

انقر على التصنيفات للتبديل بين وضعَي الخريطة من اليسار إلى اليمين ومن اليمين إلى اليسار.

يُرجى العِلم أنّ هذه المواضع قد تتزامن مع مواضع عناصر واجهة المستخدم التي لا يمكنك تعديل مواضعها (مثل حقوق الطبع والنشر وشعار 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. توضح أمثلة التعليمات البرمجية التالية كيفية إضافة عنصر تحكم مخصص باستخدام كل من لغة HTML التصريحية والأساليب البرمجية.

CSS التصريحي

توفر أنماط CSS التالية مظهرًا متسقًا مع عناصر التحكم الافتراضية. استخدم هذه الأنماط مع كلا المثالين أدناه:

.streetview-toggle-button {
  align-items: center;
  background: white;
  border: none;
  border-radius: 2px;
  box-shadow: 0 1px 4px -1px rgba(0, 0, 0, 0.3);
  color: rgb(86, 86, 86);
  cursor: pointer;
  display: flex;
  font-family: Roboto, Arial, sans-serif;
  font-size: 18px;
  font-weight: 400;
  height: 40px;
  justify-content: center;
  margin: 10px 0;
  padding: 0 17px;
}

.streetview-toggle-button:hover {
  background: #f4f4f4;
  color: #000;
}

لغة HTML التصريحية

توضح مقتطفات التعليمات البرمجية هذه كيفية إنشاء عنصر تحكم مخصص بشكل تصريحي. في لغة HTML، يُستخدم عنصر DIV ذو المعرّف container لتحديد موضع عنصر التحكم؛ وهو مُضمّن داخل العنصر gmp-map، ويُضاف الزر إلى عنصر DIV. يتم ضبط السمة slot على control-inline-start-block-start لوضع عنصر التحكم في الزاوية العلوية اليسرى من الخريطة.

<gmp-map
  center="41.027748173921374, -92.41852445367961"
  zoom="13"
  map-id="DEMO_MAP_ID">
  <div id="container" slot="control-inline-start-block-start">
    <input type="button"
    id="streetview-toggle-button"
    class="button"
    value="Click this button" />
  </div>
</gmp-map>

في لغة جافا سكريبت، يتم استخدام getElementById() للعثور على DIV والزر، ويتم إضافة مستمع حدث إلى الزر، ويتم إلحاق الزر بـ DIV.

// Create a DIV to attach the control UI to the Map.
const container = document.getElementById("container");

// Get the control button from the HTML page.
const controlButton = document.getElementById("streetview-toggle-button");

// Add a click event listener.
controlButton.addEventListener("click", () => {
  window.alert("You clicked the button!");
});

// Add the control to the DIV.
container.append(controlButton);

برنامج جافا سكريبت

توضح هذه الشفرة البرمجية كيفية إنشاء عنصر تحكم زر برمجيًا. تم تعريف أنماط CSS أعلاه.

// Create a DIV to attach the control UI to the Map.
const container = document.getElementById("container");

// Position the control in the top left corner of the map.
container.slot = "control-block-start-inline-start";

// Create the control.
const controlButton = document.createElement("button");
controlButton.classList.add("streetview-toggle-button");
controlButton.textContent = "Click this button";
controlButton.type = "button";

// Add a click event listener.
controlButton.addEventListener("click", () => {
  window.alert("You clicked the button!");
});

// Add the control to the DIV.
container.append(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 عند الحاجة لتقديم معلومات حول أحد عناصر واجهة المستخدم.

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

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

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

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

// 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);

// Push the control to the BLOCK_START_INLINE_END position.
innerMap.controls[google.maps.ControlPosition.BLOCK_START_INLINE_END].push(centerControlDiv);

لضبط موضع عنصر تحكّم مخصّص بشكل تعريفي، اضبط السمة slot في HTML:

<gmp-map center="30.72851568848909, -81.54675994068873" zoom="12">
  <div slot="control-block-start-inline-end">
    <!-- Control HTML -->
  </div>
</gmp-map>

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

عنصر التحكّم التالي بسيط (مع أنّه ليس مفيدًا بشكل خاص) ويجمع بين الأنماط الموضّحة أعلاه. يستجيب عنصر التحكّم هذا لأحداث 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_ ضمن عنصر التحكّم لتخزين هذه الحالة وتوفير دوال getter وsetter لهذه الحالة.

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