您可以使用 Screen Capture API 在網路平台上分享分頁、視窗和螢幕畫面。當網頁應用程式呼叫 getDisplayMedia() 時，Chrome 會提示使用者將分頁、視窗或畫面以 MediaStreamTrack 影片的形式分享給網頁應用程式。
許多使用 getDisplayMedia() 的網路應用程式會向使用者顯示擷取畫面的影片預覽畫面。舉例來說，視訊會議應用程式通常會將這部影片串流傳送至遠端使用者，同時將影片轉譯為本機 HTMLVideoElement，讓本機使用者持續看到分享內容的預覽畫面。
本文件說明 Chrome 中的新 Captured Surface Control API，可讓您的網頁應用程式捲動已擷取的分頁，以及讀取及寫入已擷取分頁的縮放等級。
為什麼要使用已擷取的表面控制項？
所有視訊會議應用程式都會遇到相同的缺點。如果使用者想要與已擷取的分頁或視窗互動，就必須切換至該途徑，離開視訊會議應用程式。這會帶來一些挑戰：
- 除非使用者使用子母畫面功能，或將視訊會議分頁和共用分頁並排顯示，否則無法同時查看擷取的應用程式和遠端使用者的影片動態。在較小的螢幕上，這可能會很困難。
- 使用者必須在視訊會議應用程式和擷取畫面之間切換，這會造成負擔。
- 使用者離開視訊會議應用程式後，就無法存取該應用程式提供的控制項，例如內嵌的即時通訊應用程式、表情符號回應、要求加入通話的使用者通知、多媒體和版面配置控制項，以及其他實用的視訊會議功能。
- 主持人無法將控制權委派給遠端參與者。這會導致常見的情況：遠端使用者要求講者變更投影片、上下捲動畫面或調整縮放等級。
Captured Surface Control API 可解決這些問題。
如何使用已擷取的表面控制項？
要成功使用「Captured Surface Control」，您必須先完成幾個步驟，例如明確擷取瀏覽器分頁，並取得使用者的權限，才能捲動及縮放已擷取的分頁。
擷取瀏覽器分頁
首先，請使用 getDisplayMedia() 提示使用者選擇要分享的途徑，並在過程中將 CaptureController 物件與擷取工作階段建立關聯。我們很快就會使用該物件控制擷取的表面。
const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });
接下來，請以 <video> 元素的形式產生擷取表面的本機預覽畫面：
const previewTile = document.querySelector('video');
previewTile.srcObject = stream;
如果使用者選擇分享視窗或螢幕畫面，目前不在範圍內，但如果他們選擇分享分頁，我們可以繼續。
const [track] = stream.getVideoTracks();
if (track.getSettings().displaySurface !== 'browser') {
// Bail out early if the user didn't pick a tab.
return;
}
權限提示
在指定 CaptureController 物件上首次呼叫 forwardWheel()、increaseZoomLevel()、decreaseZoomLevel() 或 resetZoomLevel() 時，系統會顯示權限提示。如果使用者授予權限，系統就會允許進一步叫用這些方法。
您必須使用使用者手勢，才能向使用者顯示權限提示，因此應用程式應只在已擁有權限，或回應使用者手勢 (例如網頁應用程式中相關按鈕的 click) 時，才呼叫上述方法。
捲動
使用 forwardWheel() 時，擷取應用程式可將擷取應用程式本身內的來源元素輪詢事件轉送至擷取分頁的可視區域。這些事件對擷取應用程式而言，與直接使用者互動無法區分。
假設擷取應用程式採用名為 "previewTile" 的 <video> 元素，以下程式碼說明如何將傳送輪盤事件轉送至擷取的分頁：
const previewTile = document.querySelector('video');
try {
// Relay the user's action to the captured tab.
await controller.forwardWheel(previewTile);
} catch (error) {
// Inspect the error.
// ...
}
方法 forwardWheel() 會接受單一輸入，輸入內容可以是下列任一項：
- 會將輪盤事件轉送至已擷取的分頁的 HTML 元素。
null，表示應停止轉送。
成功呼叫 forwardWheel() 會覆寫先前的呼叫。
forwardWheel() 傳回的承諾可能會在下列情況下遭到拒絕：
- 擷取工作階段尚未開始或已停止。
- 如果使用者未授予相關權限。
縮放
您可以透過下列 CaptureController API 途徑，與擷取的分頁的縮放等級互動：
getSupportedZoomLevels()
這個方法會針對擷取的表面類型，傳回瀏覽器支援的縮放等級清單。此清單中的值會以百分比表示，相對於「預設縮放等級」(定義為 100%)。清單是單調遞增的，且包含值 100。
這個方法只能針對支援的顯示介面類型呼叫，目前僅限於分頁。
如果符合下列條件，可能會呼叫 controller.getSupportedZoomLevels()：
controller與有效擷取作業相關聯。- 擷取的是分頁。
否則系統會發出錯誤。
呼叫這個方法「不需要」具備 "captured-surface-control" 權限。
zoomLevel
這個唯讀屬性會保留擷取的分頁目前的縮放等級。這是可為空值的屬性，如果擷取的表面類型沒有有意義的縮放等級定義，則會保留 null。目前，縮放等級只適用於分頁，不適用於視窗或螢幕。
擷取結束後，屬性會保留最後一個縮放等級值。
您不必具備 "captured-surface-control" 權限，即可讀取這個屬性。
onzoomlevelchange
這個事件處理常式可讓您監聽所擷取分頁的縮放等級變更。這類情況可能發生在：
- 使用者與瀏覽器互動，手動變更擷取的分頁縮放等級。
- 回應擷取應用程式對縮放設定方法的呼叫 (如下所述)。
您不必具備 "captured-surface-control" 權限，即可讀取這個屬性。
「increaseZoomLevel()」、「decreaseZoomLevel()」和「resetZoomLevel()」
這些方法可用於操作已擷取分頁的縮放等級。
increaseZoomLevel() 和 decreaseZoomLevel() 會依照 getSupportedZoomLevels() 傳回的順序，分別將縮放等級變更為下一個或上一個縮放等級。resetZoomLevel() 會將值設為 100。
您必須具備 "captured-surface-control" 權限，才能呼叫這些方法。如果擷取應用程式未具備這項權限，系統會提示使用者授予或拒絕權限。
這些方法都會傳回承諾，如果呼叫成功，則會解析，否則會遭到拒絕。拒絕的可能原因包括：
- 權限不足。
- 在擷取開始前呼叫。
- 在擷取結束後呼叫。
- 在與不支援的顯示介面類型擷取作業相關聯的
controller上呼叫。也就是除了分頁擷取以外的任何內容。 - 嘗試分別增加或減少超過上限或下限的值。
值得注意的是，如果 controller.zoomLevel == controller.getSupportedZoomLevels().at(0)，建議您避免呼叫 decreaseZoomLevel()，並以類似 .at(-1) 的方式保護對 increaseZoomLevel() 的呼叫。
以下範例說明如何讓使用者直接從擷取應用程式中，增加已擷取分頁的縮放等級：
const zoomIncreaseButton = document.getElementById('zoomInButton');
zoomIncreaseButton.addEventListener('click', async (event) => {
if (controller.zoomLevel >= controller.getSupportedZoomLevels().at(-1)) {
return;
}
try {
await controller.increaseZoomLevel();
} catch (error) {
// Inspect the error.
// ...
}
});
以下範例說明如何回應已擷取分頁的縮放等級變更：
controller.addEventListener('zoomlevelchange', (event) => {
const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});
特徵偵測
如要檢查是否支援 Captured Surface Control API，請使用：
if (!!window.CaptureController?.prototype.forwardWheel) {
// CaptureController forwardWheel() is supported.
}
您也可以使用任何其他 Captured Surface Control API 介面，例如 increaseZoomLevel 或 decreaseZoomLevel，甚至檢查所有介面。
瀏覽器支援
Captured Surface Control 僅適用於 Chrome 136 以上版本的電腦。
安全性和隱私權
"captured-surface-control" 權限政策可讓您管理擷取應用程式和嵌入的第三方 iframe 如何存取「Captured Surface Control」。如要瞭解安全性取捨，請參閱「Captured Surface Control」說明中的「隱私權和安全性考量事項」一節。
示範
您可以在 Glitch 上執行示範，體驗 Captured Surface Control 的運作方式。請務必查看原始碼。
意見回饋
Chrome 團隊和網路標準社群希望瞭解您使用 Captured Surface Control 的體驗。
請提供設計相關資訊
Captured Surface Capture 是否無法正常運作？或者，您是否缺少實作想法所需的方法或屬性？如對安全性模型有任何疑問或意見，在 GitHub 存放區中提出規格問題，或在現有問題中加入您的想法。
導入時發生問題？
你是否發現 Chrome 實作項目有錯誤？或者實作方式與規格不同？請前往 https://new.crbug.com 回報錯誤。請務必提供盡可能多的詳細資訊，以及重現問題的操作說明。Glitch 非常適合用於分享可重現的錯誤。