نظرة عامة على عناصر التحكم
تحتوي الخرائط المعروضة من خلال واجهة برمجة تطبيقات 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;
JavaScript
function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 4, center: { lat: -33, lng: 151 }, disableDefaultUI: true, }); } window.initMap = initMap;
تجربة النموذج
إضافة عناصر التحكم إلى الخريطة
وقد ترغب في تخصيص الواجهة عن طريق إزالة سلوك أو عناصر التحكم في واجهة المستخدم أو إضافتها أو تعديلها والتأكد من عدم إجراء تحديثات مستقبلية لهذا السلوك. وإذا كنت تريد إضافة سلوك حالي أو تعديله فقط، عليك التأكّد من إضافة عنصر التحكّم بشكل صريح إلى تطبيقك.
تظهر بعض عناصر التحكم على الخريطة بشكل افتراضي بينما لا تظهر عناصر أخرى
ما لم تطلبها على وجه التحديد. تم تحديد إضافة عناصر التحكم أو إزالتها من الخريطة في حقول الكائن MapOptions
التالية، والتي تم ضبطها على true
لجعلها مرئية أو تم ضبطها على false
لإخفائها:
{ zoomControl: boolean, mapTypeControl: boolean, scaleControl: boolean, streetViewControl: boolean, rotateControl: boolean, fullscreenControl: boolean }
وتختفي جميع عناصر التحكم افتراضيًا إذا كانت الخريطة أصغر من 200 × 200 بكسل.
ويمكنك إلغاء هذا السلوك من خلال ضبط عنصر التحكم ليكون مرئيًا بشكل صريح. على سبيل المثال، يوضّح الجدول التالي ما إذا كان عنصر التحكّم في التكبير أو التصغير مرئيًا أم لا، استنادًا إلى حجم الخريطة وإعداد الحقل zoomControl
:
حجم الخريطة | zoomControl |
مرئي؟ |
---|---|---|
أي | false |
لا |
أي | true |
نعم |
>= 200 × 200 بكسل | undefined |
نعم |
< 200×200 بكسل | undefined |
لا |
يوضّح المثال التالي الخريطة لإخفاء عنصر التحكّم في التكبير والتصغير وعرض عنصر التحكّم في الحجم. يُرجى العِلم بأننا لا نوقِف واجهة المستخدم التلقائية بشكل صريح، لذا تتم إضافة هذه التعديلات إلى السلوك التلقائي لواجهة المستخدم.
TypeScript
function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 4, center: { lat: -33, lng: 151 }, zoomControl: false, scaleControl: true, } ); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 4, center: { lat: -33, lng: 151 }, zoomControl: false, scaleControl: true, }); } window.initMap = initMap;
تجربة النموذج
خيارات التحكم
هناك عناصر تحكم متعددة قابلة للتهيئة، مما يتيح لك تغيير سلوكها أو تغيير مظهرها. على سبيل المثال، قد يظهر عنصر التحكّم في نوع الخريطة كشريط أفقي أو قائمة منسدلة.
يتم تعديل عناصر التحكم هذه عن طريق تغيير حقول خيارات عنصر التحكم المناسبة في الكائن MapOptions
عند إنشاء الخريطة.
على سبيل المثال، تتم الإشارة إلى خيارات تغيير عنصر التحكم في نوع الخريطة في الحقل mapTypeControlOptions
. قد يظهر عنصر التحكم في نوع الخريطة في أحد خيارات style
التالية:
- تعرض
google.maps.MapTypeControlStyle.HORIZONTAL_BAR
مصفوفة عناصر التحكم كأزرار في شريط أفقي كما هو موضّح في "خرائط Google". - يعرض
google.maps.MapTypeControlStyle.DROPDOWN_MENU
عنصر تحكم واحدًا في الزر يتيح لك اختيار نوع الخريطة من خلال قائمة منسدلة. - ويعرض
google.maps.MapTypeControlStyle.DEFAULT
السلوك التلقائي، الذي يعتمد على حجم الشاشة وقد يتغيّر في الإصدارات المستقبلية من واجهة برمجة التطبيقات.
ملاحظة: إذا عدّلت أي من خيارات التحكّم، عليك تفعيل عنصر التحكّم بشكل صريح أيضًا من خلال ضبط قيمة MapOptions
المناسبة على true
. على سبيل المثال، لضبط عنصر تحكّم في نوع الخريطة لعرض النمط DROPDOWN_MENU
، استخدِم الرمز التالي داخل الكائن MapOptions
:
... mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.DROPDOWN_MENU } ...
يوضح المثال التالي كيفية تغيير الموضع الافتراضي ونمط عناصر التحكم.
TypeScript
// You can set control options to change the default position or style of many // of the map controls. function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 4, center: { lat: -33, lng: 151 }, mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.DROPDOWN_MENU, mapTypeIds: ["roadmap", "terrain"], }, } ); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// You can set control options to change the default position or style of many // of the map controls. function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 4, center: { lat: -33, lng: 151 }, mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.DROPDOWN_MENU, mapTypeIds: ["roadmap", "terrain"], }, }); } window.initMap = initMap;
تجربة النموذج
عادةً ما يتم تكوين عناصر التحكم عند إنشاء الخريطة. ويمكنك
تعديل طريقة العرض لعناصر التحكّم ديناميكيًا من خلال
استدعاء طريقة setOptions()
في Map
وتمرير خيارات التحكّم الجديدة هذه.
تعديل عناصر التحكم
يمكنك تحديد العرض التقديمي لعنصر التحكم عند إنشاء الخريطة من خلال حقول داخل كائن MapOptions
في الخريطة. ويتم توضيح هذه الحقول أدناه:
- يتيح
zoomControl
تفعيل عنصر التحكّم في 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;
JavaScript
function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 12, center: { lat: -28.643387, lng: 153.612224 }, mapTypeControl: true, mapTypeControlOptions: { style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR, position: google.maps.ControlPosition.TOP_CENTER, }, zoomControl: true, zoomControlOptions: { position: google.maps.ControlPosition.LEFT_CENTER, }, scaleControl: true, streetViewControl: true, streetViewControlOptions: { position: google.maps.ControlPosition.LEFT_TOP, }, fullscreenControl: true, }); } window.initMap = initMap;
تجربة النموذج
عناصر التحكم المخصصة
بالإضافة إلى تعديل نمط وموضع عناصر التحكم الحالية في واجهة برمجة التطبيقات، يمكنك
إنشاء عناصر تحكّم بنفسك للتعامل مع المستخدم. عناصر التحكم هي أدوات ثابتة تطفو على الخريطة في مواضع مطلقة، على عكس التراكبات التي تتحرك مع الخريطة الأساسية. بشكل أساسي، عنصر التحكم هو العنصر <div>
الذي له موضع مطلق على الخريطة، ويعرض بعض واجهات المستخدم، ويتعامل مع المستخدم أو الخريطة من خلال معالج الحدث عادة.
لإنشاء عنصر تحكُّم مخصَّص، عليك اتّباع بعض القواعد. ويمكن أن تكون الإرشادات التالية من أفضل الممارسات:
- حدد CSS المناسب لعرض عناصر التحكم.
- يمكنك معالجة التفاعل مع المستخدم أو الخريطة من خلال معالجات الأحداث إما لتغييرات خصائص الموقع أو أحداث المستخدم (مثل أحداث
'click'
). - يمكنك إنشاء عنصر
<div>
للإبقاء على عنصر التحكّم وإضافة هذا العنصر إلى السمةcontrols
فيMap
.
وسنناقش في ما يلي كلٍّ من هذه المشاكل.
عناصر التحكم المخصصة في الرسم
والأمر متروك لك في كيفية رسم التحكم. وننصحك بشكل عام بوضع كل العرض التقديمي للتحكّم ضمن عنصر <div>
واحد حتى تتمكّن من معالجة عنصر التحكّم كوحدة واحدة. وسنستخدم نمط التصميم هذا في النماذج الموضحة أدناه.
يتطلّب تصميم عناصر تحكّم جذّابة بعض المعرفة بلغة CSS وبنية DOM. تعرض الشفرة التالية دالة لإنشاء عنصر زر لتحريك الخريطة لتوسيطها في شيكاغو.
function createCenterControl(map) { const controlButton = document.createElement("button"); // Set CSS for the control. controlButton.style.backgroundColor = "#fff"; controlButton.style.border = "2px solid #fff"; controlButton.style.borderRadius = "3px"; controlButton.style.boxShadow = "0 2px 6px rgba(0,0,0,.3)"; controlButton.style.color = "rgb(25,25,25)"; controlButton.style.cursor = "pointer"; controlButton.style.fontFamily = "Roboto,Arial,sans-serif"; controlButton.style.fontSize = "16px"; controlButton.style.lineHeight = "38px"; controlButton.style.margin = "8px 0 22px"; controlButton.style.padding = "0 5px"; controlButton.style.textAlign = "center"; controlButton.textContent = "Center Map"; controlButton.title = "Click to recenter the map"; controlButton.type = "button"; // Setup the click event listeners: simply set the map to Chicago. controlButton.addEventListener("click", () => { map.setCenter(chicago); }); return controlButton; }
معالجة الأحداث من عناصر التحكم المخصصة
ولكي يكون عنصر التحكم مفيدًا، يجب أن يؤدي شيئًا فعليًا. ولك حرية التحكّم في المحتوى. قد يستجيب عنصر التحكم إلى إدخال المستخدم أو قد يستجيب للتغييرات في حالة Map
.
للرد على إدخال المستخدم، استخدِم addEventListener()
، والذي سيعالج أحداث DOM المتوافقة. يضيف مقتطف الرمز التالي أداة معالجة للحدث 'click'
على المتصفّح. لاحظ أن هذا الحدث يتم استلامه من DOM، وليس من الخريطة.
// Setup the click event listener: set the map to center on Chicago var chicago = {lat: 41.850, lng: -87.650}; controlButton.addEventListener('click', () => { map.setCenter(chicago); });
إتاحة إمكانية الوصول إلى عناصر التحكم المخصصة
لضمان تلقّي عناصر التحكّم لأحداث لوحة المفاتيح والظهور بشكل صحيح لبرامج قراءة الشاشة:
- استخدم دائمًا عناصر HTML الأصلية للأزرار وعناصر النموذج والتصنيفات. لا تستخدم سوى عنصر DIV كحاوية للاحتفاظ بعناصر التحكم الأصلية، ولا تستخدم عنصر DIV كعنصر تفاعلي في واجهة المستخدم مطلقًا.
- استخدِم العنصر
label
أو السمةtitle
أو السمةaria-label
متى أمكن ذلك لتقديم معلومات عن عنصر في واجهة المستخدم.
تحديد عناصر التحكم المخصصة
يتم تحديد عناصر التحكّم المخصّصة على الخريطة من خلال وضعها في
المواضع المناسبة ضمن السمة controls
لكائن Map
. تحتوي هذه الخاصية على مجموعة من
google.maps.ControlPosition
. يمكنك إضافة عنصر تحكّم مخصّص إلى الخريطة من خلال إضافة Node
(<div>
عادةً) إلى ControlPosition
مناسب. (للحصول على معلومات حول هذه
المواضع، راجع التحكم في تحديد الموقع
أعلاه.)
ويخزّن كل عنصر ControlPosition
MVCArray
عنصر من عناصر التحكم المعروضة في هذا الموضع. ونتيجة لذلك، عند إضافة عناصر التحكّم أو إزالتها من الموضع، ستُحدِّث واجهة برمجة التطبيقات عناصر التحكّم وفقًا لذلك.
تضع واجهة برمجة التطبيقات عناصر التحكّم في كل موضع حسب ترتيب السمة index
، ويتم وضع عناصر التحكّم ذات المؤشر الأقل أولاً.
على سبيل المثال، سيتم وضع عنصرَي تحكّم مخصّصَين في الموضع BOTTOM_RIGHT
وفقًا لترتيب الفهرس هذا، مع إعطاء قيم الفهرس الأقل الأولوية. وفقًا للإعدادات التلقائية، يتم وضع جميع عناصر التحكّم المخصّصة بعد وضع أي عناصر تحكّم تلقائية في واجهة برمجة التطبيقات. يمكنك إلغاء هذا السلوك عن طريق ضبط
سمة index
في عنصر التحكم لتكون قيمة سالبة. لا يمكن وضع عناصر التحكّم المخصّصة على يمين الشعار أو على يسار حقوق الطبع والنشر.
ينشئ الرمز التالي عنصر تحكّم مخصّصًا جديدًا (لا يتم عرض منشئه) ويضيفه إلى الخريطة في الموضع TOP_RIGHT
.
var map = new google.maps.Map(document.getElementById('map'), mapOptions); // Create a DIV to attach the control UI to the Map. const centerControlDiv = document.createElement("div"); // Create the control. This code calls a function that // creates a new instance of a button control. const centerControl = createCenterControl(map); // Append the control to the DIV. centerControlDiv.appendChild(centerControl); // Add the control to the map at a designated control position // by pushing it on the position's array. This code will // implicitly add the control to the DOM, through the Map // object. You should not attach the control manually. map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
مثال للتحكم المخصص
عنصر التحكّم التالي بسيط (ولكنه غير مفيد بشكل خاص) ويجمع بين الأنماط الموضّحة أعلاه. يستجيب عنصر التحكم هذا لأحداث DOM 'click'
من خلال توسيط الخريطة على موقع تلقائي محدد:
TypeScript
let map: google.maps.Map; const chicago = { lat: 41.85, lng: -87.65 }; /** * Creates a control that recenters the map on Chicago. */ function createCenterControl(map) { const controlButton = document.createElement('button'); // Set CSS for the control. controlButton.style.backgroundColor = '#fff'; controlButton.style.border = '2px solid #fff'; controlButton.style.borderRadius = '3px'; controlButton.style.boxShadow = '0 2px 6px rgba(0,0,0,.3)'; controlButton.style.color = 'rgb(25,25,25)'; controlButton.style.cursor = 'pointer'; controlButton.style.fontFamily = 'Roboto,Arial,sans-serif'; controlButton.style.fontSize = '16px'; controlButton.style.lineHeight = '38px'; controlButton.style.margin = '8px 0 22px'; controlButton.style.padding = '0 5px'; controlButton.style.textAlign = 'center'; controlButton.textContent = 'Center Map'; controlButton.title = 'Click to recenter the map'; controlButton.type = 'button'; // Setup the click event listeners: simply set the map to Chicago. controlButton.addEventListener('click', () => { map.setCenter(chicago); }); return controlButton; } function initMap() { map = new google.maps.Map(document.getElementById('map') as HTMLElement, { zoom: 12, center: chicago, }); // Create the DIV to hold the control. const centerControlDiv = document.createElement('div'); // Create the control. const centerControl = createCenterControl(map); // Append the control to the DIV. centerControlDiv.appendChild(centerControl); map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
let map; const chicago = { lat: 41.85, lng: -87.65 }; /** * Creates a control that recenters the map on Chicago. */ function createCenterControl(map) { const controlButton = document.createElement("button"); // Set CSS for the control. controlButton.style.backgroundColor = "#fff"; controlButton.style.border = "2px solid #fff"; controlButton.style.borderRadius = "3px"; controlButton.style.boxShadow = "0 2px 6px rgba(0,0,0,.3)"; controlButton.style.color = "rgb(25,25,25)"; controlButton.style.cursor = "pointer"; controlButton.style.fontFamily = "Roboto,Arial,sans-serif"; controlButton.style.fontSize = "16px"; controlButton.style.lineHeight = "38px"; controlButton.style.margin = "8px 0 22px"; controlButton.style.padding = "0 5px"; controlButton.style.textAlign = "center"; controlButton.textContent = "Center Map"; controlButton.title = "Click to recenter the map"; controlButton.type = "button"; // Setup the click event listeners: simply set the map to Chicago. controlButton.addEventListener("click", () => { map.setCenter(chicago); }); return controlButton; } function initMap() { map = new google.maps.Map(document.getElementById("map"), { zoom: 12, center: chicago, }); // Create the DIV to hold the control. const centerControlDiv = document.createElement("div"); // Create the control. const centerControl = createCenterControl(map); // Append the control to the DIV. centerControlDiv.appendChild(centerControl); map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv); } window.initMap = initMap;
تجربة النموذج
إضافة حالة إلى عناصر التحكم
قد تخزن عناصر التحكم أيضًا الحالة. المثال التالي مشابه للمثال السابق، ولكن وحدة التحكم تحتوي على زر "تعيين الصفحة الرئيسية" الإضافي الذي يضبط عنصر التحكم لعرض موقع منزل جديد. ونفعل ذلك من خلال إنشاء السمة home_
ضمن عنصر التحكّم لتخزين هذه الحالة وتوفير قيم واستدعاءات لتلك الحالة.
TypeScript
let map: google.maps.Map; const chicago: google.maps.LatLngLiteral = { lat: 41.85, lng: -87.65 }; /** * The CenterControl adds a control to the map that recenters the map on * Chicago. */ class CenterControl { private map_: google.maps.Map; private center_: google.maps.LatLng; constructor( controlDiv: HTMLElement, map: google.maps.Map, center: google.maps.LatLngLiteral ) { this.map_ = map; // Set the center property upon construction this.center_ = new google.maps.LatLng(center); controlDiv.style.clear = "both"; // Set CSS for the control border const goCenterUI = document.createElement("button"); goCenterUI.id = "goCenterUI"; goCenterUI.title = "Click to recenter the map"; controlDiv.appendChild(goCenterUI); // Set CSS for the control interior const goCenterText = document.createElement("div"); goCenterText.id = "goCenterText"; goCenterText.innerHTML = "Center Map"; goCenterUI.appendChild(goCenterText); // Set CSS for the setCenter control border const setCenterUI = document.createElement("button"); setCenterUI.id = "setCenterUI"; setCenterUI.title = "Click to change the center of the map"; controlDiv.appendChild(setCenterUI); // Set CSS for the control interior const setCenterText = document.createElement("div"); setCenterText.id = "setCenterText"; setCenterText.innerHTML = "Set Center"; setCenterUI.appendChild(setCenterText); // Set up the click event listener for 'Center Map': Set the center of // the map // to the current center of the control. goCenterUI.addEventListener("click", () => { const currentCenter = this.center_; this.map_.setCenter(currentCenter); }); // Set up the click event listener for 'Set Center': Set the center of // the control to the current center of the map. setCenterUI.addEventListener("click", () => { const newCenter = this.map_.getCenter()!; if (newCenter) { this.center_ = newCenter; } }); } } function initMap(): void { map = new google.maps.Map(document.getElementById("map") as HTMLElement, { zoom: 12, center: chicago, }); // Create the DIV to hold the control and call the CenterControl() // constructor passing in this DIV. const centerControlDiv = document.createElement("div"); const control = new CenterControl(centerControlDiv, map, chicago); // @ts-ignore centerControlDiv.index = 1; centerControlDiv.style.paddingTop = "10px"; map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
let map; const chicago = { lat: 41.85, lng: -87.65 }; /** * The CenterControl adds a control to the map that recenters the map on * Chicago. */ class CenterControl { map_; center_; constructor(controlDiv, map, center) { this.map_ = map; // Set the center property upon construction this.center_ = new google.maps.LatLng(center); controlDiv.style.clear = "both"; // Set CSS for the control border const goCenterUI = document.createElement("button"); goCenterUI.id = "goCenterUI"; goCenterUI.title = "Click to recenter the map"; controlDiv.appendChild(goCenterUI); // Set CSS for the control interior const goCenterText = document.createElement("div"); goCenterText.id = "goCenterText"; goCenterText.innerHTML = "Center Map"; goCenterUI.appendChild(goCenterText); // Set CSS for the setCenter control border const setCenterUI = document.createElement("button"); setCenterUI.id = "setCenterUI"; setCenterUI.title = "Click to change the center of the map"; controlDiv.appendChild(setCenterUI); // Set CSS for the control interior const setCenterText = document.createElement("div"); setCenterText.id = "setCenterText"; setCenterText.innerHTML = "Set Center"; setCenterUI.appendChild(setCenterText); // Set up the click event listener for 'Center Map': Set the center of // the map // to the current center of the control. goCenterUI.addEventListener("click", () => { const currentCenter = this.center_; this.map_.setCenter(currentCenter); }); // Set up the click event listener for 'Set Center': Set the center of // the control to the current center of the map. setCenterUI.addEventListener("click", () => { const newCenter = this.map_.getCenter(); if (newCenter) { this.center_ = newCenter; } }); } } function initMap() { map = new google.maps.Map(document.getElementById("map"), { zoom: 12, center: chicago, }); // Create the DIV to hold the control and call the CenterControl() // constructor passing in this DIV. const centerControlDiv = document.createElement("div"); const control = new CenterControl(centerControlDiv, map, chicago); // @ts-ignore centerControlDiv.index = 1; centerControlDiv.style.paddingTop = "10px"; map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv); } window.initMap = initMap;