事件

選取平台： Android iOS JavaScript

本頁說明可透過程式輔助方式監聽及處理的使用者介面事件和錯誤事件。

使用者介面事件

瀏覽器中的 JavaScript 是由「事件驅動」，這表示 JavaScript 會透過產生事件來回應互動，並預期程式會「監聽」相關事件。事件目前分為兩種：

使用者事件 (例如「點擊」滑鼠事件) 會從 DOM 傳播至 Maps JavaScript API。這些事件與標準 DOM 事件各自獨立，也互不相同。
MVC 狀態變更通知會反映 Maps JavaScript API 物件的變更，並採用 property_changed 慣例命名。

每個 Maps JavaScript API 物件都會匯出一系列具名的事件。與特定事件相關的程式會為這些事件註冊 JavaScript 事件監聽器，且會呼叫 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 事件不會在事件內傳遞引數。為該物件呼叫適當的 getProperty 方法，藉此檢查隨著 MVC 狀態變更而一併變更的屬性。

處理事件

如要註冊事件通知，請使用 addListener() 事件處理常式。該方法會採用要監聽的事件，以及特定事件發生時要呼叫的函式。

範例：地圖與標記事件

下方程式碼會混合使用者事件與狀態變更事件。這個範例會為標記加上事件處理常式，使用者按下標記時地圖會縮放。此外，它也會針對 center 屬性的變更，在地圖中附加事件處理常式，且會在收到 center_changed 事件 3 秒鐘後，將地圖平移回這個標記。

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

查看範例

試用範例

JSFiddle.net

提示：如要偵測可視區域的變更，請務必使用特定的 bounds_changed 事件，而非 zoom_changed 和 center_changed 的組成事件。Maps JavaScript API 會獨立觸發後兩個事件，因此在系統強制變更可視區域後，getBounds() 才能記錄到實用的結果。如果您想在這類事件之後執行 getBounds()，請務必改為監聽 bounds_changed 事件。

範例：形狀編輯及拖曳事件

編輯或拖曳形狀的動作完成後會觸發事件。如需事件和部分程式碼片段的清單，請參閱「形狀」一文。

查看範例 (rectangle-event.html)

在使用者介面事件中存取引數

Maps JavaScript API 中的使用者介面事件通常會傳遞事件引數 (可由事件監聽器存取)，指出事件發生時的使用者介面狀態。舉例來說，使用者介面的 'click' 事件通常會傳遞 MouseEvent，當中含有 latLng 屬性，代表地圖上獲得點擊的位置。請注意，這是 UI 事件的專屬行為，MVC 狀態變更不會在事件中傳遞引數。

您可以在事件監聽器內存取事件的引數，方法與存取物件的屬性時相同。下例會為地圖加入事件監聽器，並在地圖上使用者按下的位置建立標記。

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

查看範例

試用範例

JSFiddle.net

在事件監聽器中使用閉包

執行事件監聽器時，最好的做法通常是同時為物件加上私人資料和永久性資料。JavaScript 不支援「私人」執行個體資料，但支援可讓內部函式存取外部變數的閉包。閉包在事件監聽器內很實用，可存取通常不會附加至發生事件的物件上的變數。

下例會在事件監聽器中使用函式閉包，將秘密訊息指派給標記組合。按下每個標記即可看到秘密訊息的一部分，但標記本身不含秘密訊息。

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

查看範例

試用範例

JSFiddle.net

在事件處理常式內取得和設定屬性

觸發事件時，Maps JavaScript API 事件系統中的所有 MVC 狀態變更事件，都不會傳遞引數 (使用者事件則會傳遞可檢查的引數)。如要檢查 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

查看範例

測試範例程式碼

JSFiddle.net Google Cloud Shell

移除事件監聽器

如要移除特定事件監聽器，必須將事件監聽器指派給變數。接著，您可以呼叫 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 */ };

在 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 {};

事件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

使用者介面事件

使用者介面事件

MVC 狀態變更

處理事件

範例：地圖與標記事件

TypeScript

JavaScript

試用範例

範例：形狀編輯及拖曳事件

在使用者介面事件中存取引數

TypeScript

JavaScript

試用範例

在事件監聽器中使用閉包

TypeScript

JavaScript

試用範例

在事件處理常式內取得和設定屬性

TypeScript

JavaScript

測試範例程式碼

移除事件監聽器

監聽驗證錯誤

事件