CloseWatcher

建構函式

CloseWatcher() 實驗性

建立一個新的 CloseWatcher 例項。

例項方法

此介面還繼承了其父介面 EventTarget 的方法。

CloseWatcher.requestClose() 實驗性

觸發一個 cancel 事件，如果該事件未被 Event.preventDefault() 取消，則繼續觸發一個 close 事件，然後像呼叫 destroy() 一樣停用關閉監視器。

CloseWatcher.close() 實驗性

立即觸發 close 事件，而不先觸發 cancel，然後像呼叫 destroy() 一樣停用關閉監視器。

CloseWatcher.destroy() 實驗性

停用關閉監視器，使其不再接收 close 事件。

事件

cancel 實驗性

在 close 事件之前觸發的事件，以便可以阻止 close 事件觸發。

close 實驗性

收到關閉請求時觸發的事件。

描述

某些 UI 元件具有“關閉行為”，這意味著該元件會出現，並且使用者可以在完成使用後將其關閉。例如：側邊欄、彈出視窗、對話方塊或通知。

使用者通常希望能夠使用特定的機制來關閉這些元素，並且該機制傾向於特定於裝置。例如，在具有鍵盤的裝置上可能是 Esc 鍵，但 Android 可能會使用返回按鈕。對於內建元件，例如 popover 或 <dialog> 元素，瀏覽器會處理這些差異，並在使用者執行適合裝置的關閉操作時關閉該元素。但是，當 Web 開發者實現自己的可關閉 UI 元件（例如側邊欄）時，很難實現這種特定於裝置的關閉行為。

CloseWatcher 介面透過在使用者執行特定於裝置的關閉操作時傳送 cancel 事件，然後傳送 close 事件來解決此問題。Web 應用程式可以使用 onclose 處理程式來響應特定於裝置的事件來關閉 UI 元素。它們還可以響應 UI 元素的正常關閉機制來觸發相同的事件，然後為應用程式特定和裝置特定的關閉操作實現通用的 close 事件處理。一旦 onclose 事件處理程式完成，CloseWatcher 將被銷燬，事件將不再觸發。

在某些應用程式中，UI 元素可能只允許在特定狀態下關閉；例如，在填充了某些必需資訊後。為了解決這些情況，應用程式可以透過實現 cancel 事件的處理程式來阻止 close 事件的發出，如果 UI 元素尚未準備好關閉，則該處理程式會呼叫 Event.preventDefault()。

您可以建立 CloseWatcher 例項而無需 使用者啟用，這對於實現會話不活動超時對話方塊等場景很有用。但是，如果您在沒有使用者啟用的情況下建立多個 CloseWatcher，則這些監視器將被分組，因此一次關閉請求將同時關閉它們。此外，第一個關閉監視器不一定是 CloseWatcher 物件：它可能是一個模態對話方塊元素，或者是由帶有 popover 屬性的元素生成的 popover。

示例

處理關閉請求

在此示例中，您有自己的 UI 元件（一個選擇器），並且希望同時支援平臺的預設關閉方法（例如 Esc 鍵）和自定義關閉方法（一個關閉按鈕）。

您建立一個 CloseWatcher 來處理所有 close 事件。

您的 UI 元件的 onclick 處理程式可以呼叫 requestClose 來請求關閉，並將您的關閉請求路由到與平臺關閉方法相同的 onclose 處理程式。

const watcher = new CloseWatcher();
const picker = setUpAndShowPickerDOMElement();
let chosenValue = null;

watcher.onclose = () => {
  chosenValue = picker.querySelector("input").value;
  picker.remove();
};

picker.querySelector(".close-button").onclick = () => watcher.requestClose();

使用平臺關閉請求關閉側邊欄

在此示例中，我們有一個側邊欄元件，當選擇“開啟”按鈕時顯示，並使用“關閉”按鈕或平臺原生機制進行隱藏。為了更有趣，這是一個即時示例！

還要注意，該示例有點牽強，因為通常我們會使用切換按鈕來更改側邊欄狀態。我們當然可以這樣做，但使用單獨的“開啟”和“關閉”按鈕可以更輕鬆地演示該功能。

HTML

HTML 定義了“開啟”和“關閉” <button> 元素，以及用於主內容和側邊欄的 <div> 元素。CSS 用於在將 open 類新增到側邊欄和內容元素或從中刪除時為側邊欄元素顯示設定動畫（此 CSS 已隱藏，因為它與示例無關）。

<button id="sidebar-open" type="button">Open</button>
<button id="sidebar-close" type="button">Close</button>
<div class="sidebar">Sidebar</div>
<div class="main-content">Main content</div>

.sidebar {
  position: fixed;
  top: 20px;
  left: -300px;
  right: auto;
  bottom: 0;
  width: 300px; /* Adjust the width as needed */
  background-color: lightblue;
}

.main-content {
  position: fixed;
  top: 20px;
  left: 0;
  right: 0;
  bottom: 0;
  width: auto; /* Adjust the width as needed */
  background-color: green;
  margin-left: 0px; /* Adjust for the sidebar width */
}

.sidebar.open {
  left: 0; /* Slide the sidebar to the right when open */
  transition: left 0.3s ease-in-out; /* Add a smooth transition effect */
}

.main-content.open {
  margin-left: 300px; /* Adjust for the sidebar width */
  transition: margin-left 0.3s ease-in-out;
  background-color: green;
}

JavaScript

程式碼首先獲取 HTML 中定義的按鈕和 <div> 元素的變數。它還定義了一個 closeSidebar() 函式，該函式在關閉側邊欄時呼叫，以從 <div> 元素中刪除 open 類，並添加了一個 click 事件偵聽器，該偵聽器在單擊“開啟”按鈕時呼叫 openSidebar() 方法。

const sidebar = document.querySelector(".sidebar");
const mainContent = document.querySelector(".main-content");
const sidebarOpen = document.getElementById("sidebar-open");
const sidebarClose = document.getElementById("sidebar-close");

function closeSidebar() {
  sidebar.classList.remove("open");
  mainContent.classList.remove("open");
}

sidebarOpen.addEventListener("click", openSidebar);

openSidebar() 的實現如下。該方法首先檢查側邊欄是否已開啟，如果沒有，則將 open 類新增到元素，以便顯示側邊欄。

然後我們建立一個新的 CloseWatcher，並新增一個偵聽器，當單擊“關閉”按鈕時，該偵聽器將對其呼叫 close()。這確保了在使用平臺原生關閉方法或“關閉”按鈕時都呼叫 close 事件。onclose() 事件處理程式的實現只是關閉側邊欄，然後 CloseWatcher 會自動銷燬。

function openSidebar() {
  if (!sidebar.classList.contains("open")) {
    sidebar.classList.add("open");
    mainContent.classList.add("open");

    // Add new CloseWatcher
    const watcher = new CloseWatcher();

    sidebarClose.addEventListener("click", () => watcher.close());

    // Handle close event, invoked by platform mechanisms or "Close" button
    watcher.onclose = () => {
      closeSidebar();
    };
  }
}

請注意，我們選擇在監視器上呼叫 close() 而不是 CloseWatcher.requestClose()，因為我們不需要發出 cancel 事件（如果我們有理由阻止側邊欄過早關閉，我們將使用 requestClose() 和 cancel 事件處理程式）。

結果

選擇“開啟”按鈕以開啟側邊欄。您應該能夠使用“關閉”按鈕或通常的平臺方法（例如 Windows 上的 Esc 鍵）關閉側邊欄。

規範

瀏覽器相容性

另見

• close 事件在 HTMLDialogElement 上