عناصر التحكم

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

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

تعرض الخريطة التالية مجموعة عناصر التحكّم التلقائية التي تظهر من خلال Maps JavaScript API:

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

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

• يتوفّر عنصر التحكّم في نوع الخريطة في قائمة منسدلة أو نمط شريط أزرار أفقي، ما يسمح للمستخدم باختيار نوع الخريطة (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: MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: [MapTypeId.ROADMAP, MapTypeId.TERRAIN],
        position: ControlPosition.TOP_CENTER,
    },
});
index.ts

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

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

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

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

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

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

التحكّم في تحديد المواضع

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

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

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

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

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

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

const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;

async function init() {
    // Request needed libraries.
    const [{ MapTypeControlStyle }, { ControlPosition }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('core'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;

    // Set the map's controls options.
    innerMap.setOptions({
        mapTypeControl: true,
        mapTypeControlOptions: {
            style: MapTypeControlStyle.HORIZONTAL_BAR,
            position: ControlPosition.BLOCK_START_INLINE_CENTER,
        },
        zoomControl: true,
        zoomControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_CENTER,
        },
        scaleControl: true,
        streetViewControl: true,
        streetViewControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_START,
        },
        fullscreenControl: true,
    });
}

void init();
index.ts

const mapElement = document.querySelector('gmp-map');
let innerMap;

async function init() {
    // Request needed libraries.
    const [{ MapTypeControlStyle }, { ControlPosition }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('core'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;

    // Set the map's controls options.
    innerMap.setOptions({
        mapTypeControl: true,
        mapTypeControlOptions: {
            style: MapTypeControlStyle.HORIZONTAL_BAR,
            position: ControlPosition.BLOCK_START_INLINE_CENTER,
        },
        zoomControl: true,
        zoomControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_CENTER,
        },
        scaleControl: true,
        streetViewControl: true,
        streetViewControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_START,
        },
        fullscreenControl: true,
    });
}

void init();
index.js

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

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

في 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>

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

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

const chicago = { lat: 41.85, lng: -87.65 };

// Get the gmp-map element
const mapElement = document.querySelector('gmp-map')!;

async function init() {
    (await google.maps.importLibrary('maps')) as typeof google.maps;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the button element from the HTML
    const centerButton = document.getElementById(
        'btnCenterMap'
    ) as HTMLButtonElement;
    // Move the event listener here
    centerButton.addEventListener('click', () => {
        innerMap.setCenter(chicago);
    });
}

void init();
index.ts

const chicago = { lat: 41.85, lng: -87.65 };
// Get the gmp-map element
const mapElement = document.querySelector('gmp-map');
async function init() {
    (await google.maps.importLibrary('maps'));
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the button element from the HTML
    const centerButton = document.getElementById('btnCenterMap');
    // Move the event listener here
    centerButton.addEventListener('click', () => {
        innerMap.setCenter(chicago);
    });
}
void init();
index.js

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

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

let innerMap: google.maps.Map;
const mapElement = document.querySelector('gmp-map')!;

let center: google.maps.LatLngLiteral | google.maps.LatLng = {
    lat: 41.85,
    lng: -87.65,
};

async function init() {
    await google.maps.importLibrary('maps');

    innerMap = mapElement.innerMap;

    // Get the button UI elements.
    const centerMapButton = document.getElementById(
        'btnCenterMap'
    ) as HTMLInputElement;
    const setCenterButton = document.getElementById(
        'btnSetCenter'
    ) as HTMLInputElement;

    // Set up the click event listener for the 'Center Map' button. Set the map
    // to the currently stored center.
    centerMapButton.addEventListener('click', () => {
        const currentCenter = center;
        innerMap.setCenter(currentCenter);
    });

    // Set up the click event listener for 'Set Center': Set the center of
    // the control to the current center of the map.
    setCenterButton.addEventListener('click', () => {
        const newCenter = innerMap.getCenter();

        if (newCenter) {
            center = newCenter;
        }
    });
}

void init();
index.ts

let innerMap;
const mapElement = document.querySelector('gmp-map');

let center = {
    lat: 41.85,
    lng: -87.65,
};

async function init() {
    await google.maps.importLibrary('maps');

    innerMap = mapElement.innerMap;

    // Get the button UI elements.
    const centerMapButton = document.getElementById('btnCenterMap');
    const setCenterButton = document.getElementById('btnSetCenter');

    // Set up the click event listener for the 'Center Map' button. Set the map
    // to the currently stored center.
    centerMapButton.addEventListener('click', () => {
        const currentCenter = center;
        innerMap.setCenter(currentCenter);
    });

    // Set up the click event listener for 'Set Center': Set the center of
    // the control to the current center of the map.
    setCenterButton.addEventListener('click', () => {
        const newCenter = innerMap.getCenter();

        if (newCenter) {
            center = newCenter;
        }
    });
}

void init();
index.js