กิจกรรม

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

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

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

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

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

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

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

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

เหตุการณ์ UI

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

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

ดูรายการทั้งหมดได้ที่ 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() เมธอดดังกล่าวจะรับเหตุการณ์ที่จะรอรับ และa ฟังก์ชันที่จะเรียกเมื่อเกิดเหตุการณ์ที่ระบุ

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

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

TypeScript

async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { LatLng }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('core'),
        google.maps.importLibrary('maps'),
    ]);

    // Retrieve the map element.
    const mapElement = document.querySelector('gmp-map')!;

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

    const originalPosition = new LatLng(mapElement.center!);

    const marker = new AdvancedMarkerElement({
        position: originalPosition,
        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(originalPosition);
        }, 3000);
    });

    // Zoom in when the marker is clicked.
    marker.addEventListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(originalPosition);
    });
}

void init();

JavaScript

async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { LatLng }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('core'),
        google.maps.importLibrary('maps'),
    ]);

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

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

    const originalPosition = new LatLng(mapElement.center);

    const marker = new AdvancedMarkerElement({
        position: originalPosition,
        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(originalPosition);
        }, 3000);
    });

    // Zoom in when the marker is clicked.
    marker.addEventListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(originalPosition);
    });
}

void init();
ดูตัวอย่าง

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

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

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

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

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

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

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

TypeScript

async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;

    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        if (!event.latLng) return;
        new AdvancedMarkerElement({
            position: event.latLng,
            map: innerMap,
        });
        innerMap.panTo(event.latLng);
    });
}

void init();

JavaScript

async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    innerMap.addListener('click', (event) => {
        if (!event.latLng) return;
        new AdvancedMarkerElement({
            position: event.latLng,
            map: innerMap,
        });
        innerMap.panTo(event.latLng);
    });
}

void init();
ดูตัวอย่าง

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

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

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

TypeScript

async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    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 (const secretMessage of secretMessages) {
        const marker = new AdvancedMarkerElement({
            position: {
                lat: bounds.south + latSpan * Math.random(),
                lng: bounds.west + lngSpan * Math.random(),
            },
            map: innerMap,
        });

        void attachSecretMessage(marker, secretMessage);
    }
}

// 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.
async function attachSecretMessage(
    marker: google.maps.marker.AdvancedMarkerElement,
    secretMessage: string
) {
    const { InfoWindow } = await google.maps.importLibrary('maps');

    const infoWindow = new InfoWindow({
        content: secretMessage,
    });

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

void init();

JavaScript

async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);

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

        void attachSecretMessage(marker, secretMessage);
    }
}

// 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.
async function attachSecretMessage(marker, secretMessage) {
    const { InfoWindow } = await google.maps.importLibrary('maps');

    const infoWindow = new InfoWindow({
        content: secretMessage,
    });

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

void init();
ดูตัวอย่าง

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

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

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

ตัวอย่างด้านล่างแสดงวิธีตั้งค่าตัวแฮนเดิลเหตุการณ์เพื่อตอบสนองต่อ เหตุการณ์การซูมโดยการแสดงหน้าต่างข้อมูลที่แสดงระดับการซูมนั้น

TypeScript

async function init() {
    // Request needed libraries.
    const { InfoWindow } = await google.maps.importLibrary('maps');

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;

    const infoWindow = new InfoWindow({
        content: 'Change the zoom level',
        position: mapElement.center,
    });

    infoWindow.open(innerMap);

    innerMap.addListener('zoom_changed', () => {
        infoWindow.setContent('Zoom: ' + innerMap.getZoom()!);
    });
}

void init();

JavaScript

async function init() {
    // Request needed libraries.
    const { InfoWindow } = await google.maps.importLibrary('maps');

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    const infoWindow = new InfoWindow({
        content: 'Change the zoom level',
        position: mapElement.center,
    });

    infoWindow.open(innerMap);

    innerMap.addListener('zoom_changed', () => {
        infoWindow.setContent('Zoom: ' + innerMap.getZoom());
    });
}

void init();
ดูตัวอย่าง

นำ 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 {};