使用 Window Management API 管理多個螢幕

取得已連接螢幕的相關資訊，並將視窗置於這些螢幕上。

Thomas Steiner

Window Management API

您可以使用 Window Management API 列舉連接至機器的螢幕，並在特定螢幕上放置視窗。

建議用途

以下是可能會使用這個 API 的網站：

• Gimp 等多視窗圖形編輯器可將各種編輯工具放置在精確定位的視窗中。
• 虛擬交易平台可在多個視窗中顯示市場趨勢，且每個視窗皆可以全螢幕模式查看。
• 幻燈片應用程式可在內部主畫面上顯示演講者備忘稿，並在外部投影機上顯示簡報。

如何使用 Window Management API

問題

經過時間考驗的視窗控制方法 Window.open() 不幸無法偵測到其他畫面。雖然這個 API 的某些部分 (例如 windowFeatures DOMString 參數) 似乎有點過時，但多年下來，這個 API 仍為我們提���良好的服務。如要指定視窗的位置，您可以將座標傳遞為 left 和 top (或分別為 screenX 和 screenY)，並將所需大小傳遞為 width 和 height (或分別為 innerWidth 和 innerHeight)。舉例來說，如要開啟 400 x 300 視窗，並將視窗置於距離左側 50 個像素和頂端 50 個像素的位置，您可以使用以下程式碼：

const popup = window.open(
  'https://example.com/',
  'My Popup',
  'left=50,top=50,width=400,height=300',
);

您可以查看 window.screen 屬性，該屬性會傳回 Screen 物件，藉此取得目前畫面的相關資訊。這是我的 MacBook Pro 13 吋的輸出結果：

window.screen;
/* Output from my MacBook Pro 13″:
  availHeight: 969
  availLeft: 0
  availTop: 25
  availWidth: 1680
  colorDepth: 30
  height: 1050
  isExtended: true
  onchange: null
  orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
  pixelDepth: 30
  width: 1680
*/

和大多數科技業人士一樣，我必須適應新的工作現實，並設立個人居家辦公室。我的設定如下圖所示 (如有興趣，可以參閱我的設定詳細資訊)。我 MacBook 旁邊的 iPad 已透過 Sidecar 與筆電連線，因此每當需要時，我都能快速將 iPad 變成第二個螢幕。

如��我想善用更大的螢幕，可以將上述程式碼範例中的彈出式視窗放到第二個螢幕上。我會這麼做：

popup.moveTo(2500, 50);

這是粗略的估計值，因為我們無法得知第二個螢幕的尺寸。window.screen 提供的資訊僅涵蓋內建螢幕，不包含 iPad 螢幕。內建螢幕回報的 width 為 1680 像素，所以改用 2500 像素「可能」可以將視窗移到 iPad，因為「我」知道它位於 MacBook 右側的右側。在一般情況下，要怎麼做？答案是，有比猜測更好的方法了。那就是 Window Management API。

特徵偵測

如要檢查是否支援 Window Management API，請使用：

if ('getScreenDetails' in window) {
  // The Window Management API is supported.
}

window-management 權限

我必須先向使用者索取權限，才能使用 Window Management API。您可以使用 Permissions API 查詢 window-management 權限，如下所示：

let granted = false;
try {
  const { state } = await navigator.permissions.query({ name: 'window-management' });
  granted = state === 'granted';
} catch {
  // Nothing.
}

在使用舊版和新版權限名稱的瀏覽器時，請務必在要求權限時使用防禦性程式碼，如以下範例所示。

async function getWindowManagementPermissionState() {
  let state;
  // The new permission name.
  try {
    ({ state } = await navigator.permissions.query({
      name: "window-management",
    }));
  } catch (err) {
    return `${err.name}: ${err.message}`;
  }
  return state;
}

document.querySelector("button").addEventListener("click", async () => {
  const state = await getWindowManagementPermissionState();
  document.querySelector("pre").textContent = state;
});

瀏覽器可以選擇在首次嘗試使用新 API 的方法時，動態顯示權限提示。請繼續閱讀以瞭解詳情！

window.screen.isExtended 屬性

如要瞭解裝置是否連結至多個螢幕，我會存取 window.screen.isExtended 屬性。會傳回 true 或 false。根據我的設定，此值會傳回 true。

window.screen.isExtended;
// Returns `true` or `false`.

getScreenDetails() 方法

我知道目前的設定是多螢幕，因此可以使用 Window.getScreenDetails() 取得第二個螢幕的更多資訊。呼叫這個函式會顯示權限提示，要求我詢問網站是否可開啟並在我的畫面上顯示視窗。該函式會傳回使用 ScreenDetailed 物件來解析的承諾。在已連結 iPad 的 MacBook Pro 13 上，這包括一個 screens 欄位，其中包含兩個 ScreenDetailed 物件：

await window.getScreenDetails();
/* Output from my MacBook Pro 13″ with the iPad attached:
{
  currentScreen: ScreenDetailed {left: 0, top: 0, isPrimary: true, isInternal: true, devicePixelRatio: 2, …}
  oncurrentscreenchange: null
  onscreenschange: null
  screens: [{
    // The MacBook Pro
    availHeight: 969
    availLeft: 0
    availTop: 25
    availWidth: 1680
    colorDepth: 30
    devicePixelRatio: 2
    height: 1050
    isExtended: true
    isInternal: true
    isPrimary: true
    label: "Built-in Retina Display"
    left: 0
    onchange: null
    orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
    pixelDepth: 30
    top: 0
    width: 1680
  },
  {
    // The iPad
    availHeight: 999
    availLeft: 1680
    availTop: 25
    availWidth: 1366
    colorDepth: 24
    devicePixelRatio: 2
    height: 1024
    isExtended: true
    isInternal: false
    isPrimary: false
    label: "Sidecar Display (AirPlay)"
    left: 1680
    onchange: null
    orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
    pixelDepth: 24
    top: 0
    width: 1366
  }]
}
*/

screens 陣列會提供已連結螢幕的相關資訊。請注意，iPad 的 left 值從 1680 開始，這正是內建螢幕的 width。這樣一來，我就能精確決定螢幕的邏輯排列方式 (彼此相鄰、彼此重疊等)。現在每個畫面都有資料，可顯示各畫面是否為 isInternal 屬性，以及是否為 isPrimary。請注意，內建畫面不一定是主畫面。

currentScreen 欄位是與目前 window.screen 相對應的使用中物件。物件會在跨螢幕視窗放置或裝置變更時更新。

screenschange 事件

目前唯一缺少的是偵測螢幕設定變更的方式。新事件 screenschange 就是用來執行這項操作：只要螢幕星座有所變更，就會觸發這項事件。(請注意，「screens」在事件名稱中是複數)。也就是說，每當新螢幕或現有螢幕 (在 Sidecar 的情況下為實體或虛擬) 插入或拔除時，系統就會觸發事件。

請注意，您必須以非同步方式查詢新的畫面詳細資料，screenschange 事件本身並不會提供這項資料。如要查詢螢幕詳細資料，請使用快取 Screens 介面的即時物件。

const screenDetails = await window.getScreenDetails();
let cachedScreensLength = screenDetails.screens.length;
screenDetails.addEventListener('screenschange', (event) => {
  if (screenDetails.screens.length !== cachedScreensLength) {
    console.log(
      `The screen count changed from ${cachedScreensLength} to ${screenDetails.screens.length}`,
    );
    cachedScreensLength = screenDetails.screens.length;
  }
});

currentscreenchange 事件

如果只想查看目前畫面的變更 (也就是使用中物件 currentScreen 的值)，可以監聽 currentscreenchange 事件。

const screenDetails = await window.getScreenDetails();
screenDetails.addEventListener('currentscreenchange', async (event) => {
  const details = screenDetails.currentScreen;
  console.log('The current screen has changed.', event, details);
});

change 事件

最後，如果我只想知道特定畫面的變更，可以監聽該畫面的 change 事件。

const firstScreen = (await window.getScreenDetails())[0];
firstScreen.addEventListener('change', async (event) => {
  console.log('The first screen has changed.', event, firstScreen);
});

全新的全螢幕選項

在此之前，您可以透過適當命名的 requestFullScreen() 方法，要求讓元素以全螢幕模式顯示。此方法會使用 options 參數，您可在此傳遞 FullscreenOptions。目前，其唯一的屬性是 navigationUI。Window Management API 會新增 screen 屬性，讓您決定要在哪個畫面啟動全螢幕檢視畫面。舉例來說，如果您想將主要畫面設為全螢幕：

try {
  const primaryScreen = (await getScreenDetails()).screens.filter((screen) => screen.isPrimary)[0];
  await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
  console.error(err.name, err.message);
}

聚酯纖維

我們無法將 Window Management API 多元化，但您可以填充其形狀，以便只針對新 API 進行程式碼：

if (!('getScreenDetails' in window)) {
  // Returning a one-element array with the current screen,
  // noting that there might be more.
  window.getScreenDetails = async () => [window.screen];
  // Set to `false`, noting that this might be a lie.
  window.screen.isExtended = false;
}

API 的其他部分 (也就是各種螢幕變更事件和 FullscreenOptions 的 screen 屬性) 則不會觸發，或會在未支援的瀏覽器中遭到靜默忽略。

示範

如果你跟我一樣，一直密切關注各種加密貨幣的發展，(實際上我並沒有，因為我很愛這個星球，但為了這篇文章，請假設我有)。為了追蹤我擁有的加密貨幣，我開發了一個網頁應用程式，讓我可以在任何生活情境下觀看市場，例如在床上觀看單螢幕設定。

由於加密貨幣市場隨時都可���出現劇烈波動，在這種情況下，我可以快速移動到有多螢幕設定的辦公桌。我可以按一下任何貨幣的視窗，在另一個畫面的全螢幕檢視畫面中快速查看完整詳細資料。以下是我在最近一次 YCY 血戰期間拍攝的相片。這讓我完全措手不及，我只好用手遮住臉。

您可以試用下方嵌入的示範，或在 Glitch 上查看原始碼。

安全性和權限

Chrome 團隊根據「控管強大網頁平台功能的存取權」一文中定義的核心原則，設計並實作了 Window Management API，包括使用者控制、透明度和人體工學。Window Management API 會公開與裝置連線的螢幕相關的新資訊，增加使用者的指紋表面，特別是那些與裝置持續連線的多螢幕使用者。為了緩解這項隱私權疑慮，我們僅公開常見刊登位置用途所需的最低必要畫面屬性。網站必須取得使用者授權，才能取得多螢幕資訊，並在其他螢幕上放置視窗。雖然 Chromium 會傳回詳細的畫面標籤，但瀏覽器可以自由傳回較不具描述性的標籤 (甚至是空白標籤)。

使用者控制項

使用者可以完全控制設定的曝光程度。使用者可以接受或拒絕權限提示，也能透過瀏覽器的網站資訊功能撤銷先前授予的權限。

企業控管功能

Chrome Enterprise 使用者可以控制 Window Management API 的多個層面，如 Atomic Policy Groups 設定的相關部分所述。

透明度

瀏覽器的網站資訊會顯示是否已授予使用 Window Management API 的權限，您也可以透過 Permissions API 查詢這項資訊。

權限持續性

瀏覽器會持續授予權限。您可以透過瀏覽器的網站資訊撤銷權限。

意見回饋

Chrome 團隊希望瞭解你使用 Window Management API 的體驗。

請說明 API 設計

API 是否有任何功能無法正常運作？還是你還需要實現想法或屬性呢？您對安全性模型有疑問或意見嗎？

• 在對應的 GitHub 存放區中提出規格問題，或在現有問題中加入您的想法。

回報實作問題

你是否發現 Chrome 實作項目有錯誤？或者實作方式與規格不同？

• 請前往 new.crbug.com 提交錯誤。請務必提供盡可能多的詳細資料、重現問題的簡單操作說明，並在「Components」方塊中輸入「Blink>Screen>MultiScreen」。Glitch 可讓您輕鬆快速地分享重現內容。

顯示 API 支援

您打算使用 Window Management API 嗎？公開支援可協助 Chrome 團隊優先推出各項功能，並讓其他瀏覽器廠商瞭解支援這些功能的重要性。

• 請在 WICG Discourse 討論串中分享您打算如何使用這項功能。
• 使用主題標記 #WindowManagement 將推文傳送到 @ChromiumDev，並告訴我們您在哪裡使用它。
• 請其他瀏覽器供應商實作 API。

實用連結

• 規格草稿
• 公開說明
• Window Management API 示範 | Window Management API 示範來源
• Chromium 追蹤錯誤
• ChromeStatus.com 項目
• 閃爍元件：Blink>Screen>MultiScreen
• TAG 審查
• 意圖進行實驗

特別銘謝

Window Management API 規格是由 Victor Costan、Joshua Bell 和 Mike Wasserman 編輯。這個 API 是由 Mike Wasserman 和 Adrienne Walker 實作。本文由 Joe Medley、François Beaufort 和 Kayce Basques 審查。感謝 Laura Torrent Puig 提供相片。