عناصر التحكم

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

تحتوي الخرائط المعروضة من خلال 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 على التوالي.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يعرض المثال التالي خريطة أساسية مع تفعيل جميع عناصر التحكّم، في مواضع مختلفة.

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

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

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

بالإضافة إلى تعديل نمط عناصر التحكّم الحالية في واجهة برمجة التطبيقات وموضعها، يمكنك إنشاء عناصر تحكّم خاصة بك للتعامل مع تفاعل المستخدم. عناصر التحكّم هي أدوات ثابتة تظهر فوق الخريطة في مواضع مطلقة، على عكس التراكبات التي تتحرك مع الخريطة الأساسية. بشكل أساسي، عنصر التحكّم هو عنصر <div> له موضع مطلق على الخريطة، ويعرض بعض عناصر واجهة المستخدم للمستخدم، ويتعامل مع التفاعل مع المستخدم أو الخريطة، عادةً من خلال معالج الأحداث.

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

• حدِّد CSS المناسب لعناصر التحكّم التي سيتم عرضها.
• التعامل مع التفاعل مع المستخدم أو الخريطة من خلال معالجات الأحداث الخاصة إما بتغييرات في خصائص الخريطة أو أحداث المستخدم (على سبيل المثال، أحداث 'click').
• أنشئ عنصر <div> لاحتواء عنصر التحكّم وأضِف هذا العنصر إلى السمة controls الخاصة بالعنصر Map.

نناقش كلًّا من هذه المخاوف أدناه.

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

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

يتطلّب تصميم عناصر تحكّم جذابة بعض المعرفة بلغة CSS وبنية نموذج المستند (DOM). توضّح أمثلة الرموز البرمجية التالية كيفية إضافة عنصر تحكّم مخصّص باستخدام كلّ من HTML التوضيحي والطرق البرمجية.

Declarative 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>

في JavaScript، يتم استخدام 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);

JavaScript آلي

يوضّح مقتطف الرمز البرمجي هذا كيفية إنشاء عنصر تحكّم في الزر آليًا. يتم تحديد أنماط 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' من خلال توسيط الخريطة في موقع جغرافي تلقائي معيّن:

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

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

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

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

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

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