กิจกรรม

เลือกแพลตฟอร์ม: Android iOS JavaScript

หน้านี้อธิบายเหตุการณ์ในอินเทอร์เฟซผู้ใช้และเหตุการณ์ข้อผิดพลาดที่คุณสามารถฟังและจัดการ แบบเป็นโปรแกรมได้

เหตุการณ์ในอินเทอร์เฟซผู้ใช้

JavaScript ภายในเบราว์เซอร์เป็นแบบขับเคลื่อนด้วยเหตุการณ์ ซึ่งหมายความว่า JavaScript จะตอบสนองต่อการโต้ตอบด้วยการสร้างเหตุการณ์ และคาดหวังว่า โปรแกรมจะรับฟังเหตุการณ์ที่น่าสนใจ เหตุการณ์มี 2 ประเภท ได้แก่

  • เหตุการณ์ของผู้ใช้ (เช่น เหตุการณ์เมาส์ "คลิก") จะได้รับการส่งต่อจาก DOM ไปยัง Maps JavaScript API เหตุการณ์เหล่านี้แยกต่างหากและแตกต่างจาก เหตุการณ์ DOM มาตรฐาน
  • การแจ้งเตือนการเปลี่ยนแปลงสถานะ MVC จะแสดงการเปลี่ยนแปลงในออบเจ็กต์ Maps JavaScript API และตั้งชื่อโดยใช้รูปแบบ property_changed

ออบเจ็กต์ Maps JavaScript API แต่ละรายการจะส่งออกเหตุการณ์ที่มีชื่อหลายรายการ โปรแกรมที่สนใจเหตุการณ์บางอย่างจะลงทะเบียน เครื่องมือตรวจหาเหตุการณ์ JavaScript สำหรับเหตุการณ์เหล่านั้น และเรียกใช้โค้ดเมื่อได้รับเหตุการณ์เหล่านั้นโดย เรียกใช้ addListener() เพื่อลงทะเบียนตัวแฮนเดิลเหตุการณ์ในออบเจ็กต์

ตัวอย่างต่อไปนี้แสดงเหตุการณ์ที่ทริกเกอร์โดย google.maps.Map ขณะที่คุณโต้ตอบกับแผนที่

ดูรายการเหตุการณ์ทั้งหมดได้ในเอกสารอ้างอิง Maps JavaScript API กิจกรรมจะแสดงอยู่ในส่วนแยกต่างหากสำหรับแต่ละออบเจ็กต์ที่มีกิจกรรม

เหตุการณ์ UI

ออบเจ็กต์บางอย่างภายใน Maps JavaScript API ได้รับการออกแบบมาเพื่อตอบสนองต่อเหตุการณ์ของผู้ใช้ เช่น เหตุการณ์ของเมาส์หรือคีย์บอร์ด ตัวอย่างเช่น เหตุการณ์ของผู้ใช้บางส่วนที่ออบเจ็กต์ google.maps.marker.AdvancedMarkerElement สามารถรับฟังได้มีดังนี้

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

ดูรายการทั้งหมดได้ที่คลาส AdvancedMarkerElement เหตุการณ์เหล่านี้อาจดูเหมือนเหตุการณ์ DOM มาตรฐาน แต่จริงๆ แล้วเป็นส่วนหนึ่งของ Maps JavaScript API เนื่องจากเบราว์เซอร์ต่างๆ ใช้รูปแบบเหตุการณ์ DOM ที่แตกต่างกัน Maps JavaScript API จึงมีกลไกเหล่านี้เพื่อใช้ฟังและตอบสนองต่อเหตุการณ์ DOM โดยไม่ต้อง จัดการลักษณะเฉพาะต่างๆ ของเบราว์เซอร์ โดยปกติแล้ว เหตุการณ์เหล่านี้จะส่งอาร์กิวเมนต์ ภายในเหตุการณ์เพื่อบันทึกสถานะ UI บางอย่าง (เช่น ตำแหน่งเมาส์)

การเปลี่ยนแปลงสถานะ MVC

โดยปกติแล้วออบเจ็กต์ MVC จะมีสถานะ เมื่อใดก็ตามที่พร็อพเพอร์ตี้ของออบเจ็กต์เปลี่ยนแปลง Maps JavaScript API จะทริกเกอร์เหตุการณ์ว่าพร็อพเพอร์ตี้มีการเปลี่ยนแปลง เช่น API จะทริกเกอร์เหตุการณ์ zoom_changed ในแผนที่เมื่อระดับการซูมของแผนที่เปลี่ยนแปลง คุณสามารถสกัดกั้นการเปลี่ยนแปลงสถานะเหล่านี้ได้โดยการเรียกใช้ addListener() เพื่อลงทะเบียนตัวแฮนเดิลเหตุการณ์ในออบเจ็กต์ด้วย

เหตุการณ์ของผู้ใช้และการเปลี่ยนแปลงสถานะ MVC อาจดูคล้ายกัน แต่คุณควรจัดการกับเหตุการณ์เหล่านี้แตกต่างกันในโค้ด เช่น เหตุการณ์ MVC จะไม่ส่งอาร์กิวเมนต์ภายในเหตุการณ์ ตรวจสอบพร็อพเพอร์ตี้ที่ เปลี่ยนไปเมื่อมีการเปลี่ยนแปลงสถานะ MVC โดยเรียกใช้เมธอด getProperty ที่เหมาะสมในออบเจ็กต์นั้น

จัดการเหตุการณ์

หากต้องการลงทะเบียนรับการแจ้งเตือนกิจกรรม ให้ใช้ตัวแฮนเดิลเหตุการณ์ addListener() เมธอดดังกล่าวจะใช้เหตุการณ์เพื่อฟังและฟังก์ชันที่จะเรียกใช้เมื่อเกิดเหตุการณ์ที่ระบุ

ตัวอย่าง: เหตุการณ์แผนที่และเครื่องหมาย

โค้ดต่อไปนี้จะรวมเหตุการณ์ของผู้ใช้กับเหตุการณ์การเปลี่ยนสถานะ ตัวอย่างนี้แนบตัวแฮนเดิลเหตุการณ์ กับตัวทำเครื่องหมายที่ซูมแผนที่เมื่อคลิก นอกจากนี้ยังแนบตัวแฮนเดิลเหตุการณ์กับแผนที่ สำหรับการเปลี่ยนแปลงพร็อพเพอร์ตี้ center และเลื่อนแผนที่กลับไปที่ตัวทำเครื่องหมายหลังจาก 3 วินาทีเมื่อได้รับเหตุการณ์ center_changed

TypeScript

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

JavaScript

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
ดูตัวอย่าง

ลองใช้ตัวอย่าง

เคล็ดลับ: หากพยายามตรวจหาการเปลี่ยนแปลงใน วิวพอร์ต ให้ใช้เหตุการณ์ bounds_changed ที่เฉพาะเจาะจง แทนเหตุการณ์ zoom_changed และ center_changed ที่เป็นส่วนประกอบ เนื่องจาก Maps JavaScript API จะทริกเกอร์เหตุการณ์หลังนี้แยกกัน getBounds() อาจไม่รายงานผลลัพธ์ที่เป็นประโยชน์ จนกว่าวิวพอร์ตจะมีการเปลี่ยนแปลงอย่างเป็นทางการ หากต้องการ getBounds() หลังจากเหตุการณ์ดังกล่าว โปรดฟังเหตุการณ์ bounds_changed แทน

ตัวอย่าง: เหตุการณ์การแก้ไขและการลากรูปร่าง

เมื่อแก้ไขหรือลากรูปร่าง ระบบจะทริกเกอร์เหตุการณ์เมื่อดำเนินการเสร็จสมบูรณ์ ดูรายการเหตุการณ์และข้อมูลโค้ดบางส่วนได้ที่ รูปร่าง

ดู ตัวอย่าง (rectangle-event.html)

เข้าถึงอาร์กิวเมนต์ในเหตุการณ์ UI

โดยปกติแล้ว เหตุการณ์ UI ภายใน Maps JavaScript API จะส่งอาร์กิวเมนต์เหตุการณ์ ซึ่ง Listener เหตุการณ์จะเข้าถึงได้ โดยสังเกตสถานะ UI เมื่อเกิดเหตุการณ์ เช่น โดยปกติแล้ว 'click' เหตุการณ์ UI จะส่ง MouseEvent ที่มีพร็อพเพอร์ตี้ latLng ซึ่งระบุ ตําแหน่งที่คลิกบนแผนที่ โปรดทราบว่าลักษณะการทำงานนี้มีเฉพาะในเหตุการณ์ UI เท่านั้น การเปลี่ยนแปลงสถานะ MVC จะไม่ส่งอาร์กิวเมนต์ในเหตุการณ์

คุณเข้าถึงอาร์กิวเมนต์ของเหตุการณ์ภายใน Listener เหตุการณ์ได้ในลักษณะเดียวกับ การเข้าถึงพร็อพเพอร์ตี้ของออบเจ็กต์ ตัวอย่างต่อไปนี้จะเพิ่ม Listener เหตุการณ์ สําหรับแผนที่ และสร้างตัวทำเครื่องหมายเมื่อผู้ใช้คลิกแผนที่ที่ ตําแหน่งที่คลิก

TypeScript

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

JavaScript

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
ดูตัวอย่าง

ลองใช้ตัวอย่าง

ใช้ Closure ใน Listener เหตุการณ์

เมื่อเรียกใช้ Listener เหตุการณ์ การมีทั้งข้อมูลส่วนตัวและข้อมูลที่คงอยู่ซึ่งแนบกับออบเจ็กต์มักจะเป็นประโยชน์ JavaScript ไม่รองรับข้อมูลอินสแตนซ์ "ส่วนตัว" แต่รองรับการปิด ซึ่งช่วยให้ฟังก์ชันภายในเข้าถึงตัวแปรภายนอกได้ Closure มีประโยชน์ภายในเครื่องมือฟังเหตุการณ์ในการเข้าถึงตัวแปรที่ปกติแล้วไม่ได้แนบกับออบเจ็กต์ที่เกิดเหตุการณ์

ตัวอย่างต่อไปนี้ใช้การปิดฟังก์ชันใน Listener เหตุการณ์ เพื่อ กำหนดข้อความลับให้กับชุดตัวทำเครื่องหมาย การคลิกเครื่องหมายแต่ละรายการจะ แสดงข้อความลับบางส่วน ซึ่งไม่ได้อยู่ในเครื่องหมาย นั้นๆ

TypeScript

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

JavaScript

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
ดูตัวอย่าง

ลองใช้ตัวอย่าง

รับและตั้งค่าพร็อพเพอร์ตี้ภายในตัวแฮนเดิลเหตุการณ์

เหตุการณ์การเปลี่ยนแปลงสถานะ MVC ในระบบเหตุการณ์ของ Maps JavaScript API จะไม่ส่งอาร์กิวเมนต์เมื่อมีการทริกเกอร์เหตุการณ์ (เหตุการณ์ของผู้ใช้จะส่งอาร์กิวเมนต์ที่ตรวจสอบได้) หากต้องการตรวจสอบพร็อพเพอร์ตี้ เมื่อมีการเปลี่ยนแปลงสถานะ MVC คุณควรเรียกใช้เมธอด getProperty() ที่เหมาะสมในออบเจ็กต์นั้นอย่างชัดเจน การตรวจสอบนี้จะดึงข้อมูลสถานะปัจจุบันของออบเจ็กต์ 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

JavaScript

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
ดูตัวอย่าง

ลองใช้ตัวอย่าง

นำ Listener เหตุการณ์ออก

หากต้องการนำ Listener เหตุการณ์ที่เฉพาะเจาะจงออก จะต้องกำหนด Listener ให้กับตัวแปร จากนั้นคุณจะเรียกใช้ removeListener() โดยส่งชื่อตัวแปรที่กำหนด Listener ได้

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

google.maps.event.removeListener(listener1);

หากต้องการนำ Listener ทั้งหมดออกจากอินสแตนซ์ใดอินสแตนซ์หนึ่ง ให้เรียกใช้ 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);

หากต้องการนำ Listener ทั้งหมดสำหรับประเภทเหตุการณ์ที่เฉพาะเจาะจงสำหรับอินสแตนซ์ที่เฉพาะเจาะจงออก ให้เรียกใช้ 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

ฟังข้อผิดพลาดในการตรวจสอบสิทธิ์

หากต้องการตรวจหาการตรวจสอบสิทธิ์ล้มเหลวแบบเป็นโปรแกรม (เช่น เพื่อส่งบีคอนโดยอัตโนมัติ) คุณสามารถเตรียมฟังก์ชัน Callback ได้ หากกำหนดฟังก์ชันส่วนกลางต่อไปนี้ ระบบจะเรียกใช้ฟังก์ชันดังกล่าวเมื่อการตรวจสอบสิทธิ์ล้มเหลว 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 {};