الأحداث

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختَر النظام الأساسي: Android iOS JavaScript

تصف هذه الصفحة أحداث واجهة المستخدم وأحداث الأخطاء التي يمكنك الاستماع إليها ومعالجتها آليًا.

أحداث واجهة المستخدم

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

  • يتم نشر أحداث المستخدم (مثل أحداث "click"الماوس) من DOM إلى Maps JavaScript API. وهذه الفعاليات منفصلة عن أحداث DOM العادية.
  • تعرض إشعارات تغيير حالة MVC التغييرات في عناصر واجهة برمجة تطبيقات JavaScript للخرائط وتتم تسميتها باستخدام اصطلاح property_changed.

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

يوضّح لك النموذج التالي الأحداث التي يشغّلها google.maps.Map أثناء تفاعلك مع الخريطة.

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

أحداث واجهة المستخدم

تم تصميم بعض العناصر في Maps API API استجابةً لأحداث المستخدمين، مثل أحداث الماوس أو لوحة المفاتيح. على سبيل المثال، في ما يلي بعض فعاليات المستخدم التي يمكن أن يستمع إليها عنصر google.maps.Marker:

  • 'click'
  • 'dblclick'
  • 'mouseup'
  • 'mousedown'
  • 'mouseover'
  • 'mouseout'

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

تغييرات حالة MVC

عادةً ما تحتوي كائنات MVC على حالة. كلما تغيّر أحد العناصر، تعمل واجهة برمجة تطبيقات JavaScript للخرائط على تنشيط حدث تم تغييره في الموقع. على سبيل المثال، ستعمل واجهة برمجة التطبيقات على تنشيط حدث zoom_changed على الخريطة عند تغيير مستوى التكبير/التصغير في الخريطة. ويمكنك اعتراض تغييرات الحالة هذه من خلال استدعاء addListener() لتسجيل معالجات الحدث على العنصر أيضًا.

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

معالجة الأحداث

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

مثال: أحداث الخريطة والمحدّد

يدمج الرمز التالي أحداث المستخدمين مع أحداث تغيير الحالة. يتم إرفاق معالج الأحداث بعلامة محدّدة تعمل على تكبير/تصغير الخريطة عند النقر عليها. ونضيف أيضًا معالج أحداث إلى الخريطة لإجراء تغييرات على السمة center، ونعرض الخريطة مجددًا على العلامة بعد 3 ثوانٍ من تلقّي الفعالية center_changed:

TypeScript

function initMap(): void {
  const myLatlng = { lat: -25.363, lng: 131.044 };

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: myLatlng,
    }
  );

  const marker = new google.maps.Marker({
    position: myLatlng,
    map,
    title: "Click to zoom",
  });

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.getPosition() as google.maps.LatLng);
    }, 3000);
  });

  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.getPosition() as google.maps.LatLng);
  });
}

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

JavaScript

function initMap() {
  const myLatlng = { lat: -25.363, lng: 131.044 };
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: myLatlng,
  });
  const marker = new google.maps.Marker({
    position: myLatlng,
    map,
    title: "Click to zoom",
  });

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.getPosition());
    }, 3000);
  });
  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}

window.initMap = initMap;
عرض مثال

جرّب عيّنة

نصيحة: إذا كنت تحاول اكتشاف تغيير في إطار العرض، احرص على استخدام حدث bounds_changed المحدّد بدلاً من عرض zoom_changed و center_changed. ونظرًا لأن واجهة برمجة تطبيقات JavaScript لـ"خرائط Google"تطلق هذه الأحداث الأخيرة بشكلٍ مستقل، قد لا تُبلغ getBounds() عن نتائج مفيدة إلا بعد تغيير إطار العرض بشكل موثوق. إذا كنت تريد getBounds() بعد هذه الفعالية، احرص على الاستماع إلى فعالية bounds_changed بدلاً من ذلك.

مثال: تعديل الأشكال وسحب الأحداث

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

عرض مثال (rectangle-event.html)

الوصول إلى الوسيطات في أحداث واجهة المستخدم

عادةً ما تمرّ أحداث واجهة المستخدم في Maps API API بوسيطة الحدث، التي يمكن للمستمع الوصول إليها، مع ملاحظة حالة واجهة المستخدم عند وقوع الفعالية. على سبيل المثال، يمرّر حدث واجهة المستخدم 'click' عادةً MouseEvent الذي يحتوي على خاصية latLng تشير إلى الموقع الجغرافي الذي تم النقر عليه على الخريطة. يُرجى العِلم أنّ هذا السلوك فريد في أحداث واجهة المستخدم، ولا تمرِّر تغييرات حالة MVC في الوسيطات الخاصة بها.

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

TypeScript

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

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng: google.maps.LatLng, map: google.maps.Map) {
  new google.maps.Marker({
    position: latLng,
    map: map,
  });
  map.panTo(latLng);
}

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: -25.363882, lng: 131.044922 },
  });

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  new google.maps.Marker({
    position: latLng,
    map: map,
  });
  map.panTo(latLng);
}

window.initMap = initMap;
عرض مثال

جرّب عيّنة

استخدام حالات الإغلاق في أدوات معالجة الأحداث

عند تنفيذ أداة معالجة الحدث، من المفيد غالبًا إرفاق بيانات خاصة ومستمرة مع أحد العناصر. لا تتوافق JavaScript مع بيانات "&&;; الخاص"مثال: ولكنها تتوافق مع عمليات الإغلاق التي تسمح للوظائف الداخلية بالوصول إلى المتغيرات الخارجية. ويُعدّ الإغلاق مفيدًا للمستمعين إلى الفعاليات للوصول إلى متغيّرات غير مرتبطة عادةً بالعناصر التي تحدث.

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

TypeScript

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

  const bounds: google.maps.LatLngBoundsLiteral = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141,
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const marker = new google.maps.Marker({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random(),
      },
      map: map,
    });

    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(
  marker: google.maps.Marker,
  secretMessage: string
) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.get("map"), marker);
  });
}

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: -25.363882, lng: 131.044922 },
  });
  const bounds = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141,
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const marker = new google.maps.Marker({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random(),
      },
      map: map,
    });

    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(marker, secretMessage) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.get("map"), marker);
  });
}

window.initMap = initMap;
عرض مثال

جرّب عيّنة

الحصول على الخصائص وإعدادها ضمن "معالجات الأحداث"

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

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

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

TypeScript

function initMap(): void {
  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: originalMapCenter,
    }
  );

  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);

  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom()!);
  });
}

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

JavaScript

function initMap() {
  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: originalMapCenter,
  });
  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);
  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom());
  });
}

window.initMap = initMap;
عرض مثال

جرّب عيّنة

الاستماع إلى أحداث DOM

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

تتضمّن طريقة الراحة هذه توقيعًا كما هو موضّح أدناه:

addDomListener(instance:Object, eventName:string, handler:Function)

حيث قد يكون instance أي عنصر DOM متوافقًا مع المتصفح، بما في ذلك:

  • الأعضاء الهرميين في DOM، مثل window أو document.body.myform
  • العناصر المُسَمّاة مثل document.getElementById("foo")

يُرجى العِلم بأنّ addDomListener() يمرِّر الحدث المُشار إليه إلى المتصفِّح، الذي يعالجه وفقًا لنموذج حدث DOM في المتصفّح ، ومع ذلك، تتوافق جميع المتصفحات الحديثة على الأقل مع المستوى 2 في نموذج العناصر في المستند. (لمزيد من المعلومات حول أحداث مستوى DOM، راجِع مستويات Mozilla DOM).

TypeScript

function initMap(): void {
  const mapDiv = document.getElementById("map") as HTMLElement;
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

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

JavaScript

function initMap() {
  const mapDiv = document.getElementById("map");
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

window.initMap = initMap;

HTML

<html>
  <head>
    <title>Listening to DOM Events</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
عرض مثال

جرّب عيّنة

وعلى الرغم من أنّ الرمز أعلاه هو رمز لواجهة برمجة تطبيقات JavaScript في "خرائط Google"، ترتبط طريقة addDomListener() بالكائن window في المتصفّح وتسمح لواجهة برمجة التطبيقات بالتواصل مع كائنات خارج النطاق العادي لواجهة برمجة التطبيقات.

إزالة أدوات معالجة الأحداث

لإزالة مستمع حدث معيّن، يجب أن يكون قد تم تحديده إلى متغيّر. يمكنك عندئذٍ استدعاء الخاصية removeListener()، مع تمرير اسم المتغير الذي تم تخصيص المستمع إليه.

var listener1 = marker.addListener('click', aFunction);

google.maps.event.removeListener(listener1);

لإزالة جميع المستمعين من مثيل معيّن، يمكنك استدعاء clearInstanceListeners()، مع تمرير اسم النسخة الافتراضية.

var listener1 = marker.addListener('click', aFunction);
var listener2 = marker.addListener('mouseover', bFunction);

// Remove listener1 and listener2 from marker instance.
google.maps.event.clearInstanceListeners(marker);

لإزالة جميع المستمعين لنوع حدث معيّن لمثيل معيّن، يمكنك استدعاء الدالة clearListeners()، مع تمرير اسم النسخة الافتراضية واسم الفعالية.

marker.addListener('click', aFunction);
marker.addListener('click', bFunction);
marker.addListener('click', cFunction);

// Remove all click listeners from marker instance.
google.maps.event.clearListeners(marker, 'click');

لمزيد من المعلومات، اطّلِع على المستندات المرجعية لمساحة الاسم google.maps.event.

جارٍ الاستماع إلى أخطاء المصادقة

إذا كنت تريد رصد تعذُّر المصادقة آليًا (على سبيل المثال، إرسال إشارة تلقائيًا)، يمكنك إعداد دالة معاودة الاتصال. وإذا تم تعريف الدالة العامة التالية، سيتم طلبها عند تعذُّر المصادقة. function gm_authFailure() { /* Code */ };