رویداد

پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، جاوا اسکریپت

این صفحه رویدادهای رابط کاربری و رویدادهای خطایی را که می‌توانید به آنها گوش دهید و از طریق برنامه‌نویسی مدیریت کنید، شرح می‌دهد.

رویدادهای رابط کاربری

جاوا اسکریپت در مرورگر رویداد محور است، به این معنی که جاوا اسکریپت با تولید رویدادها به تعاملات پاسخ می‌دهد و انتظار دارد که یک برنامه به رویدادهای جالب توجه گوش دهد . دو نوع رویداد وجود دارد:

• رویدادهای کاربر (مانند رویدادهای "کلیک" ماوس) از DOM به Maps JavaScript API منتشر می‌شوند. این رویدادها جدا و متمایز از رویدادهای استاندارد DOM هستند.
• اعلان‌های تغییر وضعیت MVC، تغییرات در اشیاء API جاوا اسکریپت Maps را منعکس می‌کنند و با استفاده از قرارداد property _changed نامگذاری می‌شوند.

هر شیء Maps JavaScript API تعدادی رویداد نامگذاری شده را صادر می‌کند. برنامه‌هایی که به رویدادهای خاص علاقه‌مند هستند ، شنونده‌های رویداد جاوا اسکریپت را برای آن رویدادها ثبت می‌کنند و هنگام دریافت آن رویدادها، با فراخوانی addListener() برای ثبت کنترل‌کننده‌های رویداد روی شیء، کد را اجرا می‌کنند.

نمونه زیر به شما نشان می‌دهد که هنگام تعامل شما با نقشه، کدام رویدادها توسط google.maps.Map فعال می‌شوند.

برای مشاهده لیست کاملی از رویدادها، به مرجع API جاوا اسکریپت نقشه‌ها مراجعه کنید. رویدادها در بخش جداگانه‌ای برای هر شیء که شامل رویدادها است، فهرست شده‌اند.

رویدادهای رابط کاربری

برخی از اشیاء درون Maps JavaScript API طوری طراحی شده‌اند که به رویدادهای کاربر مانند رویدادهای ماوس یا صفحه کلید پاسخ دهند. برای مثال، اینها برخی از رویدادهای کاربری هستند که یک شیء google.maps.marker.AdvancedMarkerElement می‌تواند به آنها گوش دهد:

• 'click'
• 'drag'
• 'dragend'
• 'dragstart'
• 'gmp-click'

برای لیست کامل، به کلاس AdvancedMarkerElement مراجعه کنید. این رویدادها ممکن است شبیه رویدادهای استاندارد DOM به نظر برسند، اما در واقع بخشی از API جاوا اسکریپت Maps هستند. از آنجا که مرورگرهای مختلف مدل‌های رویداد DOM متفاوتی را پیاده‌سازی می‌کنند، API جاوا اسکریپت Maps این مکانیزم‌ها را برای گوش دادن و پاسخ دادن به رویدادهای DOM بدون نیاز به مدیریت ویژگی‌های مختلف مرورگرهای مختلف فراهم می‌کند. این رویدادها همچنین معمولاً آرگومان‌هایی را درون رویداد ارسال می‌کنند که به برخی از حالت‌های رابط کاربری (مانند موقعیت ماوس) اشاره دارند.

تغییرات وضعیت MVC

MVC objects typically contain state. Whenever an object's property changes, the Maps JavaScript API will fire an event that the property has changed. For example, the API will fire a zoom_changed event on a map when the map's zoom level changes. You can intercept these state changes by calling addListener() to register event handlers on the object as well.

رویدادهای کاربر و تغییرات وضعیت MVC ممکن است شبیه به هم به نظر برسند، اما شما باید در کد خود با آنها متفاوت رفتار کنید. برای مثال، رویدادهای MVC آرگومان‌هایی را درون رویداد خود ارسال نمی‌کنند. با فراخوانی متد get Property مناسب در آن شیء، ویژگی‌ای را که در تغییر وضعیت MVC تغییر کرده است، بررسی کنید.

مدیریت رویدادها

برای ثبت اعلان‌های رویداد، از کنترل‌کننده‌ی رویداد addListener() استفاده کنید. این متد یک رویداد را برای گوش دادن به آن و یک تابع را برای فراخوانی در هنگام وقوع رویداد مشخص شده می‌گیرد.

مثال: رویدادهای نقشه و نشانگر

کد زیر رویدادهای کاربر را با رویدادهای تغییر وضعیت ترکیب می‌کند. این مثال یک کنترل‌کننده رویداد را به یک نشانگر متصل می‌کند که با کلیک روی آن، نقشه بزرگنمایی می‌شود. همچنین یک کنترل‌کننده رویداد را برای تغییرات در ویژگی center به نقشه متصل می‌کند و پس از ۳ ثانیه پس از دریافت رویداد center_changed نقشه را به نشانگر برمی‌گرداند.

تایپ اسکریپت

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps')) as google.maps.MapsLibrary;
    (await google.maps.importLibrary('marker')) as google.maps.MarkerLibrary;

    // Retrieve the map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

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

    const center = mapElement.center;

    const marker = new google.maps.marker.AdvancedMarkerElement({
        position: center,
        map: innerMap,
        title: 'Click to zoom',
        gmpClickable: true,
    });

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

    // Zoom in when the marker is clicked.
    marker.addListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(marker.position as google.maps.LatLng);
    });
}

initMap();
index.ts

نکته: راهنمای استفاده از TypeScript و Google Maps را مطالعه کنید.

جاوا اسکریپت

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps'));
    (await google.maps.importLibrary('marker'));
    // Retrieve the map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map from the map element.
    const innerMap = mapElement.innerMap;
    const center = mapElement.center;
    const marker = new google.maps.marker.AdvancedMarkerElement({
        position: center,
        map: innerMap,
        title: 'Click to zoom',
        gmpClickable: true,
    });
    innerMap.addListener('center_changed', () => {
        // 3 seconds after the center of the map has changed,
        // pan back to the marker.
        window.setTimeout(() => {
            innerMap.panTo(marker.position);
        }, 3000);
    });
    // Zoom in when the marker is clicked.
    marker.addListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(marker.position);
    });
}
initMap();
index.js

مشاهده مثال

نمونه را امتحان کنید

JSFiddle.net

نکته : اگر می‌خواهید تغییری در نمای دید (viewport) تشخیص دهید، حتماً از رویداد bounds_changed خاص به جای رویدادهای تشکیل‌دهنده‌ی zoom_changed و center_changed استفاده کنید. از آنجا که API جاوا اسکریپت Maps این رویدادهای اخیر را به طور مستقل اجرا می‌کند، getBounds() ممکن است نتایج مفیدی را تا زمانی که نمای دید به طور معتبر تغییر نکرده باشد، گزارش نکند. اگر می‌خواهید getBounds() پس از چنین رویدادی اجرا کنید، حتماً به رویداد bounds_changed گوش دهید.

مثال: رویدادهای ویرایش و کشیدن شکل

وقتی یک شکل ویرایش یا کشیده می‌شود، پس از اتمام عمل، یک رویداد اجرا می‌شود. برای فهرستی از رویدادها و برخی از قطعه کدها، به بخش Shapes مراجعه کنید.

مشاهده مثال (rectangle-event.html)

آرگومان‌های دسترسی در رویدادهای رابط کاربری

رویدادهای رابط کاربری (UI) در API جاوا اسکریپت Maps معمولاً یک آرگومان رویداد را ارسال می‌کنند که توسط شنونده رویداد قابل دسترسی است و وضعیت رابط کاربری را هنگام وقوع رویداد نشان می‌دهد. به عنوان مثال، یک رویداد 'click' رابط کاربری معمولاً یک MouseEvent حاوی یک ویژگی latLng را ارسال می‌کند که مکان کلیک شده روی نقشه را نشان می‌دهد. توجه داشته باشید که این رفتار منحصر به رویدادهای رابط کاربری است. تغییرات وضعیت MVC آرگومان‌هایی را در رویدادهای خود ارسال نمی‌کنند.

شما می‌توانید به آرگومان‌های رویداد در یک شنونده رویداد، همانطور که به ویژگی‌های یک شیء دسترسی پیدا می‌کنید، دسترسی پیدا کنید. مثال زیر یک شنونده رویداد برای نقشه اضافه می‌کند و وقتی کاربر روی نقشه در محل کلیک شده کلیک می‌کند، یک نشانگر ایجاد می‌کند.

تایپ اسکریپت

async function initMap() {
  // Request needed libraries.
  await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
  const innerMap = mapElement.innerMap;

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

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

initMap();
index.ts

نکته: راهنمای استفاده از TypeScript و Google Maps را مطالعه کنید.

جاوا اسکریپت

async function initMap() {
    // Request needed libraries.
    await google.maps.importLibrary("maps");
    await google.maps.importLibrary("marker");
    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    innerMap.addListener("click", (e) => {
        placeMarkerAndPanTo(e.latLng, innerMap);
    });
}
function placeMarkerAndPanTo(latLng, map) {
    new google.maps.marker.AdvancedMarkerElement({
        position: latLng,
        map: map,
    });
    map.panTo(latLng);
}
initMap();
index.js

مشاهده مثال

نمونه را امتحان کنید

JSFiddle.net

استفاده از Closureها در Event Listenerها

هنگام اجرای یک شنونده رویداد، اغلب مفید است که هر دو داده خصوصی و دائمی به یک شیء متصل باشند. جاوا اسکریپت از داده‌های نمونه "خصوصی" پشتیبانی نمی‌کند، اما از closureها پشتیبانی می‌کند که به توابع داخلی اجازه می‌دهد به متغیرهای بیرونی دسترسی داشته باشند. closureها در شنونده‌های رویداد برای دسترسی به متغیرهایی که معمولاً به اشیایی که رویدادها روی آنها رخ می‌دهند متصل نیستند، مفید هستند.

مثال زیر از یک تابع closure در شنونده رویداد برای اختصاص یک پیام مخفی به مجموعه‌ای از نشانگرها استفاده می‌کند. کلیک روی هر نشانگر، بخشی از پیام مخفی را که در خود نشانگر وجود ندارد، آشکار می‌کند.

تایپ اسکریپت

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps')) as google.maps.MapsLibrary;
    (await google.maps.importLibrary('marker')) as google.maps.MarkerLibrary;

    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;
    const innerMap = mapElement.innerMap;

    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.
    innerMap.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.AdvancedMarkerElement({
            position: {
                lat: bounds.south + latSpan * Math.random(),
                lng: bounds.west + lngSpan * Math.random(),
            },
            map: innerMap,
        });

        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.AdvancedMarkerElement,
    secretMessage: string
) {
    const infowindow = new google.maps.InfoWindow({
        content: secretMessage,
    });

    marker.addListener('gmp-click', () => {
        infowindow.open(marker.map, marker);
    });
}

initMap();
index.ts

نکته: راهنمای استفاده از TypeScript و Google Maps را مطالعه کنید.

جاوا اسکریپت

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps'));
    (await google.maps.importLibrary('marker'));
    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    const bounds = {
        north: -25.363882,
        south: -31.203405,
        east: 131.044922,
        west: 125.244141,
    };
    // Display the area between the location southWest and northEast.
    innerMap.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.AdvancedMarkerElement({
            position: {
                lat: bounds.south + latSpan * Math.random(),
                lng: bounds.west + lngSpan * Math.random(),
            },
            map: innerMap,
        });
        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('gmp-click', () => {
        infowindow.open(marker.map, marker);
    });
}
initMap();
index.js

مشاهده مثال

نمونه را امتحان کنید

JSFiddle.net

دریافت و تنظیم ویژگی‌ها در کنترل‌کننده‌های رویداد

هیچ یک از رویدادهای تغییر وضعیت MVC در سیستم رویداد Maps JavaScript API هنگام فعال شدن رویداد، آرگومان‌هایی را ارسال نمی‌کنند. (رویدادهای کاربر آرگومان‌هایی را ارسال می‌کنند که می‌توانند بررسی شوند.) اگر نیاز به بررسی یک ویژگی در تغییر وضعیت MVC دارید، باید صریحاً متد get Property () مناسب را روی آن شیء فراخوانی کنید. این بررسی همیشه وضعیت فعلی شیء MVC را بازیابی می‌کند، که ممکن است با وضعیت هنگام اجرای اولیه رویداد متفاوت باشد.

نکته : تنظیم صریح یک ویژگی در یک کنترل‌کننده رویداد که به تغییر وضعیت آن ویژگی خاص پاسخ می‌دهد، ممکن است رفتار غیرقابل پیش‌بینی و/یا ناخواسته‌ای ایجاد کند. برای مثال، تنظیم چنین ویژگی‌ای باعث ایجاد یک رویداد جدید می‌شود و اگر همیشه یک ویژگی را در این کنترل‌کننده رویداد تنظیم کنید، ممکن است در نهایت یک حلقه بی‌نهایت ایجاد کنید.

مثال زیر نحوه تنظیم یک کنترل‌کننده رویداد را برای پاسخ به رویدادهای بزرگنمایی با نمایش یک پنجره اطلاعات که آن سطح را نمایش می‌دهد، نشان می‌دهد.

تایپ اسکریپت

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;

  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()!);
  });
}

initMap();
index.ts

نکته: راهنمای استفاده از TypeScript و Google Maps را مطالعه کنید.

جاوا اسکریپت

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  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());
  });
}

initMap();
index.js

نکته: جاوا اسکریپت از قطعه کد TypeScript کامپایل می‌شود.

مشاهده مثال

نمونه را امتحان کنید

JSFiddle.net پوسته ابری گوگل

حذف شنوندگان رویداد

برای حذف یک شنونده‌ی رویداد خاص، باید آن را به یک متغیر اختصاص داده باشید. سپس می‌توانید تابع 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 مراجعه کنید.

خطاهای احراز هویت را بررسی کنید

اگر می‌خواهید از طریق برنامه‌نویسی، خطای احراز هویت را تشخیص دهید (مثلاً به‌طور خودکار یک beacon ارسال کنید)، می‌توانید یک تابع فراخوانی (callback function) آماده کنید. اگر تابع سراسری زیر تعریف شده باشد، در صورت عدم موفقیت احراز هویت، فراخوانی خواهد شد. function gm_authFailure() { /* Code */ };

در TypeScript، ممکن است لازم باشد تابع را به محدوده سراسری اضافه کنید، همانطور که در زیر نشان داده شده است:

// Define the callback function.
window.gm_authFailure = () => {
  console.error("Google Maps failed to authenticate.");
  /* Code */
};

// Add gm_authFailure to the global scope.
declare global {
  interface Window {
    gm_authFailure?: () => void;
  }
}
export {};