رویداد

پلتفرم را انتخاب کنید: Android iOS JavaScript

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

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

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

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

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

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

برای فهرست کامل رویدادها، به مرجع Maps JavaScript API مراجعه کنید. رویدادها در یک بخش جداگانه برای هر شی فهرست شده اند که شامل رویدادها است.

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

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

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

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

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

اشیاء MVC معمولاً شامل حالت هستند. هر زمان که ویژگی یک شی تغییر کند، Maps JavaScript API رویدادی را اجرا می کند که ویژگی تغییر کرده است. به عنوان مثال، API یک رویداد zoom_changed را در زمانی که سطح بزرگنمایی نقشه تغییر می کند، روی نقشه اجرا می کند. شما می توانید با فراخوانی addListener() این تغییرات حالت را متوقف کنید تا کنترل کننده های رویداد را روی شی نیز ثبت کنید.

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

رسیدگی به رویدادها

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

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

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

TypeScript

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

  const myLatlng = { lat: -25.363, lng: 131.044 };

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

  const marker = new google.maps.marker.AdvancedMarkerElement({
    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.position as google.maps.LatLng);
    }, 3000);
  });

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

initMap();
index.ts

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

جاوا اسکریپت

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");
  const myLatlng = { lat: -25.363, lng: 131.044 };
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: myLatlng,
    mapId: "DEMO_MAP_ID",
  });
  const marker = new google.maps.marker.AdvancedMarkerElement({
    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.position);
    }, 3000);
  });
  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.position);
  });
}

initMap();
index.js

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

مشاهده نمونه

Sample را امتحان کنید

JSFiddle.net Google Cloud Shell

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

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

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

مشاهده نمونه (rectangle-event.html)

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

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

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

TypeScript

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

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

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

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.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary(
    "marker",
  );
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
    mapId: "DEMO_MAP_ID",
  });

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

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

initMap();
index.js

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

مشاهده نمونه

Sample را امتحان کنید

JSFiddle.net Google Cloud Shell

از بستن در شنوندگان رویداد استفاده کنید

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

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

TypeScript

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

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

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

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

initMap();
index.ts

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

جاوا اسکریپت

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
    mapId: "DEMO_MAP_ID",
  });
  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.AdvancedMarkerElement({
      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.map, marker);
  });
}

initMap();
index.js

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

مشاهده نمونه

Sample را امتحان کنید

JSFiddle.net Google Cloud Shell

دریافت و تنظیم ویژگی ها در رویداد Handlers

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

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

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

TypeScript

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 کامپایل شده است.

مشاهده نمونه

Sample را امتحان کنید

JSFiddle.net Google Cloud Shell

به رویدادهای DOM گوش دهید

مدل رویداد Maps JavaScript API رویدادهای سفارشی خود را ایجاد و مدیریت می کند. با این حال، DOM (مدل شیء سند) درون مرورگر نیز رویدادهای خود را، با توجه به مدل رویداد مرورگر خاص در حال استفاده، ایجاد و ارسال می‌کند. اگر می‌خواهید این رویدادها را ضبط کنید و به آنها پاسخ دهید، Maps JavaScript API روش ثابت addDomListener() برای گوش دادن و اتصال به رویدادهای DOM ارائه می‌کند.

این روش راحت دارای امضایی است که در زیر نشان داده شده است:

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

که در آن instance ممکن است هر عنصر DOM پشتیبانی شده توسط مرورگر باشد، از جمله:

• اعضای سلسله مراتبی DOM مانند window یا document.body. myform
• عناصر نامگذاری شده مانند document.getElementById("foo")

توجه داشته باشید که addDomListener() رویداد مشخص شده را به مرورگر ارسال می کند، که آن را مطابق با مدل رویداد DOM مرورگر مدیریت می کند. با این حال، تقریباً همه مرورگرهای مدرن حداقل از DOM Level 2 پشتیبانی می کنند. (برای اطلاعات بیشتر در مورد رویدادهای سطح DOM، به مرجع Mozilla DOM Levels مراجعه کنید.)

TypeScript

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

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

initMap();
index.ts

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

جاوا اسکریپت

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

initMap();
index.js

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

HTML

<html>
  <head>
    <title>Listening to DOM Events</title>

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

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

مشاهده نمونه

Sample را امتحان کنید

JSFiddle.net Google Cloud Shell

اگرچه کد بالا کد API جاوا اسکریپت Maps است، روش addDomListener() به شی window مرورگر متصل می شود و به API اجازه می دهد با اشیاء خارج از دامنه معمولی API ارتباط برقرار کند.

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

برای حذف یک شنونده رویداد خاص، باید به یک متغیر اختصاص داده شده باشد. سپس می توانید 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 */ };