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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -33, lng: 151 },
      disableDefaultUI: true,
    }
  );
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

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

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -33, lng: 151 },
    disableDefaultUI: true,
  });
}

window.initMap = initMap;
index.js

ملاحظة: يتم جمع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

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

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

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

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

حجم الخريطة	zoomControl	هل الجهاز مرئي؟
هل مِن	false	لا
هل مِن	true	نعم
>= 200 × 200 بكسل	undefined	نعم
< 200 × 200 بكسل	undefined	لا

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

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -33, lng: 151 },
      zoomControl: false,
      scaleControl: true,
    }
  );
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

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

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -33, lng: 151 },
    zoomControl: false,
    scaleControl: true,
  });
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

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

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

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

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

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

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

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

TypeScript

// You can set control options to change the default position or style of many
// of the map controls.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -33, lng: 151 },
      mapTypeControl: true,
      mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: ["roadmap", "terrain"],
      },
    }
  );
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

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

JavaScript

// You can set control options to change the default position or style of many
// of the map controls.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -33, lng: 151 },
    mapTypeControl: true,
    mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.DROPDOWN_MENU,
      mapTypeIds: ["roadmap", "terrain"],
    },
  });
}

window.initMap = initMap;
index.js

ملاحظة: يتم جمع JavaScript من مقتطف TypeScript.

عرض مثال

تجربة "عيّنة"

JSFiddle.net Google Cloud Shell

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

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

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

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

تجدر الإشارة إلى أنّه يمكنك تحديد خيارات لعناصر التحكّم التي تعطّلها في البداية.

التحكم في المكانة

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

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

يمكن استخدام مواضع التحكّم التالية:

• يشير TOP_CENTER إلى أنّه يجب وضع عنصر التحكّم. طول أعلى مركز للخريطة.
• يشير TOP_LEFT إلى أنّه يجب وضع عنصر التحكّم بطول الشاشة. الجزء العلوي الأيسر من الخريطة، مع أي عناصر فرعية لعناصر التحكم "تدفق" باتجاه أعلى المركز.
• يشير الرمز TOP_RIGHT إلى أنّه يجب وضع عنصر التحكّم في أعلى يسار الخريطة، مع أي عناصر فرعية لعنصر التحكّم "تتدفق" نحو أعلى وسط الخريطة.
• يشير LEFT_TOP إلى أنّه يجب وضع عنصر التحكّم بطول الشاشة. أعلى يسار الخريطة، ولكن أسفل أي من عناصر TOP_LEFT.
• يشير الرمز RIGHT_TOP إلى أنّه يجب وضع عنصر التحكّم في أعلى يسار الخريطة، ولكن أسفل أي عناصر TOP_RIGHT أخرى.
• يشير LEFT_CENTER إلى أنّه يجب وضع عنصر التحكّم. على طول الجانب الأيسر من الخريطة، في منتصف الخريطة بين TOP_LEFT وBOTTOM_LEFT موضعًا.
• يشير الرمز RIGHT_CENTER إلى أنّه يجب وضع عنصر التحكّم على الجانب الأيمن من الخريطة، في المنتصف بين الموضعَين TOP_RIGHT وBOTTOM_RIGHT.
• يشير LEFT_BOTTOM إلى أنّه يجب وضع عنصر التحكّم. على طول الجزء السفلي الأيسر من الخريطة، ولكن فوق أي BOTTOM_LEFT عناصر.
• يشير الرمز RIGHT_BOTTOM إلى أنّه يجب وضع عنصر التحكّم في أسفل يسار الخريطة، ولكن فوق أي عناصر BOTTOM_RIGHT أخرى.
• يشير BOTTOM_CENTER إلى أنّه يجب وضع عنصر التحكّم. طول مركز الخريطة.
• يشير BOTTOM_LEFT إلى أنّه يجب وضع عنصر التحكّم. أسفل يسار الخريطة، مع أي عناصر فرعية من عناصر التحكم، "متدفق" باتجاه أسفل المركز.
• يشير الرمز BOTTOM_RIGHT إلى أنّه يجب وضع عنصر التحكّم في أسفل يسار الخريطة، مع أي عناصر فرعية لعنصر التحكّم "تتدفق" نحو أسفل الوسط.

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

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

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 12,
      center: { lat: -28.643387, lng: 153.612224 },
      mapTypeControl: true,
      mapTypeControlOptions: {
        style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
        position: google.maps.ControlPosition.TOP_CENTER,
      },
      zoomControl: true,
      zoomControlOptions: {
        position: google.maps.ControlPosition.LEFT_CENTER,
      },
      scaleControl: true,
      streetViewControl: true,
      streetViewControlOptions: {
        position: google.maps.ControlPosition.LEFT_TOP,
      },
      fullscreenControl: true,
    }
  );
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

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

function createCenterControl(map) {
  const controlButton = document.createElement("button");

  // Set CSS for the control.
  controlButton.style.backgroundColor = "#fff";
  controlButton.style.border = "2px solid #fff";
  controlButton.style.borderRadius = "3px";
  controlButton.style.boxShadow = "0 2px 6px rgba(0,0,0,.3)";
  controlButton.style.color = "rgb(25,25,25)";
  controlButton.style.cursor = "pointer";
  controlButton.style.fontFamily = "Roboto,Arial,sans-serif";
  controlButton.style.fontSize = "16px";
  controlButton.style.lineHeight = "38px";
  controlButton.style.margin = "8px 0 22px";
  controlButton.style.padding = "0 5px";
  controlButton.style.textAlign = "center";

  controlButton.textContent = "Center Map";
  controlButton.title = "Click to recenter the map";
  controlButton.type = "button";

  // Setup the click event listeners: simply set the map to Chicago.
  controlButton.addEventListener("click", () => {
    map.setCenter(chicago);
  });

  return controlButton;
}

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

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

للاستجابة إلى إدخالات المستخدم، استخدِم addEventListener()، الذي يعالج أحداث DOM المتوافقة. يضيف المقتطف التالي من الرمز البرمجي أداة معالجة لحدث 'click' في المتصفّح. يُرجى العلم أنّ هذا الحدث يتم تلقّيه من DOM، وليس من الخريطة.

// Setup the click event listener: set the map to center on Chicago
var chicago = {lat: 41.850, lng: -87.650};

controlButton.addEventListener('click', () => {
  map.setCenter(chicago);
});

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

للتأكّد من أنّ عناصر التحكّم تتلقّى أحداث لوحة المفاتيح وتظهر بشكل صحيح لبرامج قراءة الشاشة:

• استخدام عناصر HTML الأصلية دائمًا للأزرار وعناصر النماذج والتسميات. استخدِم عنصر DIV كحاوية فقط لعرض عناصر التحكّم الأصلية، ولا تُعدّل أبدًا الغرض من عنصر DIV ليصبح عنصرًا تفاعليًا في واجهة المستخدم .
• استخدِم العنصر label أو سمة title أو سمة aria-label حسب الاقتضاء لتقديم معلومات عن عنصر واجهة مستخدِم.

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

يتم وضع عناصر التحكّم المخصّصة على الخريطة من خلال وضعها في مواضع مناسبة ضمن سمة controls لكائن Map. يحتوي هذا الموقع على صفيف من google.maps.ControlPosition ثانية. يمكنك إضافة عنصر تحكّم مخصّص إلى الخريطة من خلال إضافة Node (عادةً <div>) إلى ControlPosition مناسب. (للحصول على معلومات حول هذه المواضع، يُرجى الاطّلاع على التحكّم في مواضع الإعلانات أعلاه).

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

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

تُنشئ التعليمة البرمجية التالية عنصر تحكم مخصص جديد (أداة الإنشاء الخاصة به ليست ) وتضيفه إلى الخريطة في الموضع TOP_RIGHT.

var map = new google.maps.Map(document.getElementById('map'), mapOptions);

// Create a DIV to attach the control UI to the Map.
const centerControlDiv = document.createElement("div");

// Create the control. This code calls a function that
// creates a new instance of a button control.
const centerControl = createCenterControl(map);

// Append the control to the DIV.
centerControlDiv.appendChild(centerControl);

// Add the control to the map at a designated control position
// by pushing it on the position's array. This code will
// implicitly add the control to the DOM, through the Map
// object. You should not attach the control manually.
map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);

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

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

TypeScript

let map: google.maps.Map;

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

/**
 * Creates a control that recenters the map on Chicago.
 */
 function createCenterControl(map) {
  const controlButton = document.createElement('button');

  // Set CSS for the control.
  controlButton.style.backgroundColor = '#fff';
  controlButton.style.border = '2px solid #fff';
  controlButton.style.borderRadius = '3px';
  controlButton.style.boxShadow = '0 2px 6px rgba(0,0,0,.3)';
  controlButton.style.color = 'rgb(25,25,25)';
  controlButton.style.cursor = 'pointer';
  controlButton.style.fontFamily = 'Roboto,Arial,sans-serif';
  controlButton.style.fontSize = '16px';
  controlButton.style.lineHeight = '38px';
  controlButton.style.margin = '8px 0 22px';
  controlButton.style.padding = '0 5px';
  controlButton.style.textAlign = 'center';

  controlButton.textContent = 'Center Map';
  controlButton.title = 'Click to recenter the map';
  controlButton.type = 'button';

  // Setup the click event listeners: simply set the map to Chicago.
  controlButton.addEventListener('click', () => {
    map.setCenter(chicago);
  });

  return controlButton;
}

function initMap() {
  map = new google.maps.Map(document.getElementById('map') as HTMLElement, {
    zoom: 12,
    center: chicago,
  });

  // Create the DIV to hold the control.
  const centerControlDiv = document.createElement('div');
  // Create the control.
  const centerControl = createCenterControl(map);
  // Append the control to the DIV.
  centerControlDiv.appendChild(centerControl);

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(centerControlDiv);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اطّلِع على الدليل حول استخدام 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_ داخل العنصر للتخزين في هذه الحالة وتوفير وظائف للحصول على هذه الحالة وضبطها.

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