chrome.system.display

說明

使用 system.display API 查詢向上傳者顯示的中繼資料。

權限

system.display

類型

ActiveState

Chrome 117 以上版本

用於判斷系統是否偵測到及使用螢幕的列舉。如果系統偵測不到螢幕 (可能會中斷連線或遭睡眠模式中斷等)，就會視為「閒置」。例如，在所有螢幕中斷連線時，這個狀態是用來保留現有螢幕。

列舉

"active"

"已停用"

Bounds

屬性

• 高度

  數字

  螢幕高度 (以像素為單位)。

• 左側

  數字

  左上角的 x 座標。

• 頂端

  數字

  左上角的 y 座標。

• 寬度

  數字

  螢幕寬度 (以像素為單位)。

DisplayLayout

Chrome 53 以上版本

屬性

• id

  字串

  螢幕的專屬 ID。

• 碳補償

  數字

  螢幕沿著連線邊緣的偏移值。0 表示最上方或最左側的角落對齊。

• parentId

  字串

  父項螢幕的專屬 ID。如果是根目錄，則為空白。

• 位置

  LayoutPosition

  這個螢幕相對於父項的版面配置位置。系統會忽略根層級這項設定。

DisplayMode

Chrome 52 以上版本

屬性

• deviceScaleFactor

  數字

  顯示模式的裝置縮放比例係數。

• 高度

  數字

  顯示模式高度，以裝置獨立 (使用者可見) 像素為準。

• heightInNativePixels

  數字

  顯示模式的高度 (以原生像素為單位)。

• isInterlaced

  布林值 選填

  Chrome 74 以上版本

  如果是交錯模式，則為「true」；如未提供，則為「false」。

• isNative

  布林值

  如果模式是螢幕的原生模式，則為「true」。

• isSelected

  布林值

  如果目前選取顯示模式，則為「是」。

• refreshRate

  數字

  Chrome 67 以上版本

  顯示模式刷新率 (單位為赫茲)。

• uiScale

  編號 選填

  自 Chrome 70 版起已淘汰

  使用 displayZoomFactor

  顯示模式 UI 縮放比例係數。

• 寬度

  數字

  顯示模式寬度的裝置獨立 (使用者可見) 像素。

• widthInNativePixels

  數字

  顯示模式的寬度 (以原生像素為單位)。

DisplayProperties

屬性

• boundsOriginX

  編號 選填

  如果已設定，系統會沿著 x 軸更新螢幕的邏輯邊界來源。與 boundsOriginY 一併套用。如果未設定並設定了 boundsOriginY，預設為目前的值。請注意，更新顯示來源時，系統會套用某些限制，因此最終邊界起點可能會與集合來源不同。您可以使用 getInfo 擷取最終邊界。無法在主要螢幕上變更邊界來源。

• boundsOriginY

  編號 選填

  如果已設定，系統會沿著 Y 軸更新螢幕的邏輯邊界起點。請參閱 boundsOriginX 參數的說明文件。

• displayMode

  DisplayMode 選用

  Chrome 52 以上版本

  設定後，將顯示模式更新為符合這個值的模式。如果其他參數無效，就不會套用。如果顯示模式無效，系統就不會套用且會設定錯誤，但仍會套用其他屬性。

• displayZoomFactor

  編號 選填

  Chrome 65 以上版本

  設定後，系統會更新與螢幕相關聯的縮放。這種變焦功能會執行重新版面配置和重新繪製作業，比起只執行 1 個像素的延展放大作業，呈現更好的畫質。

• isPrimary (主要)

  布林值 選填

  如果設為 true，系統會將顯示設為主要螢幕。如果設為 false，則不需要人工管理。注意：如果已設定，系統會將顯示畫面視為所有其他屬性的主要內容 (也就是說，可以設定 isUnified，且邊界起點可能不會設定)。

• isUnified

  布林值 選填

  Chrome 59 以上版本

  僅限 ChromeOS。如果設為 true，將顯示模式變更為整合桌面 (詳情請參閱 enableUnifiedDesktop)。如果設為 False，則會停用整合桌面模式。這只適用於主要顯示畫面。如有提供，則必須提供 MirroringSourceId，系統將忽略其他屬性。如果沒有提供，就不會產生任何作用。

• mirroringSourceId

  string optional

  自 Chrome 68 版起已淘汰

  使用 setMirrorMode。

  僅限 ChromeOS。如果設定此值且不是空白，則只會為這個螢幕啟用鏡像功能。否則系統會停用所有螢幕的鏡像功能。這個值應指出要鏡像顯示的來源顯示畫面 ID，且不得與傳送至 setDisplayProperties 的 ID 相同。如果設定此屬性，就無法設定任何其他屬性。

• 遮視區域

  插邊 選用

  設定後，請將顯示器的過度掃描插邊設為提供的值。請注意，過度掃描值不得為負值或大於螢幕尺寸的一半。無法變更內部監控器的過度顯示設定。

• 旋轉

  編號 選填

  如果已設定，請更新螢幕的旋轉角度。法定值包括 [0、90、180、270]。旋轉是以順時針方向設定為相對於螢幕的垂直位置。

DisplayUnitInfo

屬性

• activeState

  ActiveState

  Chrome 117 以上版本

  如果系統偵測到及使用螢幕，則會啟用。

• availableDisplayZoomFactors

  數字 []

  Chrome 67 以上版本

  可為顯示畫面設定的縮放係數值清單。

• 界限

  邊界

  螢幕的邏輯邊界。

• displayZoomFactor

  數字

  Chrome 65 以上版本

  螢幕當前縮放與預設縮放的比例。例如，值 1 相當於 100% 的縮放，值 1.5 則相當於 150% 的縮放。

• dpiX

  數字

  沿 X 軸每英寸像素數。

• dpiY

  數字

  Y 軸每英寸像素數。

• Eidid

  Edid 選用

  Chrome 67 以上版本

  注意：這僅適用於 Chrome OS 資訊站應用程式和網頁 UI。

• hasTouchSupport

  布林值

  Chrome 57 以上版本

  如果這個螢幕有相關聯的觸控輸入裝置，則為「true」。

• id

  字串

  螢幕的專屬 ID。

• isEnabled

  布林值

  如果已啟用這個顯示器，則為「是」。

• isPrimary (主要)

  布林值

  如果這是主要顯示畫面，則為「true」。

• isUnified

  布林值

  Chrome 59 以上版本

  如果是整合桌面模式時的所有顯示畫面，則為 True。請參閱 enableUnifiedDesktop 的說明文件。

• mirroringDestinationIds

  string[]

  Chrome 64 以上版本

  僅限 ChromeOS。要建立鏡像來源螢幕的螢幕 ID。如未鏡像顯示任何畫面，則為空白。這會為所有螢幕採用相同的值。此值不得包含 mirroringSourceId。

• mirroringSourceId

  字串

  僅限 ChromeOS。在鏡像功能啟用的情況下，要鏡射的螢幕 ID，否則為空白。系統將為所有螢幕 (包括鏡像的螢幕) 調整這項設定。

• 模式

  DisplayMode[]

  Chrome 52 以上版本

  可用的顯示模式清單。目前模式會是 isSelected=true。僅適用於 ChromeOS。將設為其他平台上的空白陣列。

• 名稱

  字串

  容易記名的名稱 (例如「HP LCD 螢幕」)。

• 遮視區域

  插邊

  螢幕在其螢幕邊界內的插邊。目前僅在 ChromeOS 上公開。在其他平台上將設為空白插邊。

• 旋轉

  數字

  顯示器相對於垂直位置的順時針旋轉角度。目前僅在 ChromeOS 上公開。在其他平台上將設為 0。如果裝置處於實體平板電腦狀態，系統會將值為 -1 解讀為自動旋轉。

• workArea

  邊界

  螢幕在顯示範圍內的可用工作區域。工作區不包含作業系統預留的顯示區域，例如工作列和啟動器。

Edid

Chrome 67 以上版本

屬性

• manufacturerId

  字串

  3 個字元製造商代碼。參見秒3.4.1 頁 21.v1.4 中的必要欄位。

• productId

  字串

  2 位元組製造商指派的代碼，秒。3.4.2 第 21 頁。v1.4 中的必要欄位。

• yearOfManufacture

  數字

  製造商年份、秒3.4.4 頁 22.v1.4 中的必要欄位。

GetInfoFlags

Chrome 59 以上版本

屬性

• singleUnified

  布林值 選填

  如果設為 True，則在整合桌面模式中，getInfo 只會傳回一個 DisplayUnitInfo (請參閱 enableUnifiedDesktop)。預設值為 false。

Insets

屬性

• 底部

  數字

  Y 軸與底部邊界的距離。

• 左側

  數字

  X 軸與左側邊界之間的距離。

• 右側

  數字

  X 軸與右側邊界的距離。

• 頂端

  數字

  Y 軸與頂端邊界的距離。

LayoutPosition

Chrome 53 以上版本

版面配置位置，即螢幕所連接的父項邊緣。

列舉

"top"

"右"

"bottom"

"左"

MirrorMode

Chrome 65 以上版本

鏡像模式，也就是螢幕鏡像翻轉到其他螢幕的不同方式。

列舉

"off"
指定預設模式 (擴充或整合桌面)。

"normal"
指定預設來源螢幕會鏡像到所有其他螢幕。

"mixed"
指定將指定的來源螢幕鏡像投射到提供的目的地螢幕。系統會延長所有已連結的螢幕。

MirrorModeInfo

Chrome 65 以上版本

屬性

• mirroringDestinationIds

  string[] 選填

  鏡像目的地的 ID 隨即顯示。這個引數只適用於「混合」。

• mirroringSourceId

  string optional

  鏡像來源顯示畫面的 ID。這個引數只適用於「混合」。

• 模式

  MirrorMode

  應設定的鏡像模式。

Point

Chrome 57 以上版本

屬性

• x

  數字

  點的 x 座標。

• y

  數字

  點的 y 座標。

TouchCalibrationPair

Chrome 57 以上版本

屬性

• displayPoint

  分數

  顯示點的座標。

• touchPoint

  分數

  與顯示點相對應的觸控點座標。

TouchCalibrationPairQuad

Chrome 57 以上版本

屬性

• pair1

  TouchCalibrationPair

  第一組觸控和顯示點需要進行觸控校正。

• pair2

  TouchCalibrationPair

  第二組觸控和顯示點必須用於觸控校正。

• pair3

  TouchCalibrationPair

  第 3 組觸控和顯示點必須搭配使用，才能執行觸控校正作業。

• pair4

  TouchCalibrationPair

  第四組觸控和顯示點必須搭配使用，才能執行觸控校正功能。

方法

clearTouchCalibration()

Chrome 57 以上版本

chrome.system.display.clearTouchCalibration(
  id: string,
)

重設螢幕的觸控校正功能，並清除與螢幕相關的任何觸控校正資料，讓螢幕恢復預設狀態。

參數

• id

  字串

  螢幕的專屬 ID。

completeCustomTouchCalibration()

Chrome 57 以上版本

chrome.system.display.completeCustomTouchCalibration(
  pairs: TouchCalibrationPairQuad,
  bounds: Bounds,
)

設定螢幕的觸控校正配對。這些 pairs 將用於校正觸控螢幕，以透過 startCustomTouchCalibration() 呼叫的 id 顯示螢幕。在呼叫這個方法之前，請一律呼叫 startCustomTouchCalibration。如果正在進行其他觸控校正，就會擲回錯誤。

參數

• 成對

  TouchCalibrationPairQuad

  用來校正螢幕的點對組。

• 界限

  邊界

  執行觸控校正時的螢幕邊界。系統會忽略 bounds.left 和 bounds.top 值。

enableUnifiedDesktop()

Chrome 46 以上版本

chrome.system.display.enableUnifiedDesktop(
  enabled: boolean,
)

啟用/停用整合桌面功能。如果啟用鏡像功能，請先啟用鏡像模式，直到鏡像功能關閉為止。否則，桌面模式會立即切換為整合。注意：這僅適用於 Chrome OS 資訊站應用程式和網頁 UI。

參數

• 已啟用

  布林值

  如果應啟用整合桌面，則為「是」。

getDisplayLayout()

Promise Chrome 53 以上版本

chrome.system.display.getDisplayLayout(
  callback?: function,
)

要求所有螢幕的版面配置資訊。注意：這僅適用於 Chrome OS 資訊站應用程式和網頁 UI。

參數

• 回呼

  函式 選用

  callback 參數如下所示：

  (layouts: DisplayLayout[]) => void

  • 版面配置

    DisplayLayout[]

傳回

• Promise<DisplayLayout[]>

  Chrome 91 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getInfo()

Promise

chrome.system.display.getInfo(
  flags?: GetInfoFlags,
  callback?: function,
)

要求所有已連結顯示裝置的資訊。

參數

• flags

  GetInfoFlags 選用

  Chrome 59 以上版本

  影響資訊傳回方式的選項。

• 回呼

  函式 選用

  callback 參數如下所示：

  (displayInfo: DisplayUnitInfo[]) => void

  • displayInfo

    DisplayUnitInfo[]

傳回

• Promise<DisplayUnitInfo[]>

  Chrome 91 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

overscanCalibrationAdjust()

Chrome 53 以上版本

chrome.system.display.overscanCalibrationAdjust(
  id: string,
  delta: Insets,
)

調整顯示器目前的過度掃描插邊。一般而言，這應該是沿著軸移動 (例如，左側 + 右鍵的值會相同) 或是沿著軸縮放 (例如，上 + 底部具有相反的值)。每次 Adjust 呼叫都會累計自開始使用後先前的通話。

參數

• id

  字串

  螢幕的專屬 ID。

• Delta

  插邊

  變更過度掃描插邊的量。

overscanCalibrationComplete()

Chrome 53 以上版本

chrome.system.display.overscanCalibrationComplete(
  id: string,
)

儲存目前的值並隱藏疊加層，完成螢幕的過度掃描調整。

參數

• id

  字串

  螢幕的專屬 ID。

overscanCalibrationReset()

Chrome 53 以上版本

chrome.system.display.overscanCalibrationReset(
  id: string,
)

將顯示螢幕的過度掃描插邊重設為上次儲存的值 (例如在呼叫 Start 之前)。

參數

• id

  字串

  螢幕的專屬 ID。

overscanCalibrationStart()

Chrome 53 以上版本

chrome.system.display.overscanCalibrationStart(
  id: string,
)

開始過度掃描校準螢幕。螢幕上會顯示疊加層，指出目前過度掃描插邊。如果系統正在進行螢幕 id 的過度掃描校正，會重設校正。

參數

• id

  字串

  螢幕的專屬 ID。

setDisplayLayout()

Promise Chrome 53 以上版本

chrome.system.display.setDisplayLayout(
  layouts: DisplayLayout[],
  callback?: function,
)

設定所有螢幕的版面配置。所有未納入螢幕的螢幕都會使用預設版面配置。如果版面配置會重疊或無效，則會將其調整為有效的版面配置。版面配置解析後，會觸發 onDisplayChanged 事件。注意：這僅適用於 Chrome OS 資訊站應用程式和網頁 UI。

參數

• 版面配置

  DisplayLayout[]

  所有螢幕都需要的版面配置資訊 (主要顯示畫面除外)。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setDisplayProperties()

Promise

chrome.system.display.setDisplayProperties(
  id: string,
  info: DisplayProperties,
  callback?: function,
)

根據 info 中提供的資訊，更新 id 指定螢幕的屬性。失敗時，系統將會設定 runtime.lastError。注意：這僅適用於 Chrome OS 資訊站應用程式和網頁 UI。

參數

• id

  字串

  螢幕的專屬 ID。

• 資訊

  DisplayProperties

  應變更的顯示屬性相關資訊。只有在 info 中指定新的值時，才會變更屬性。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setMirrorMode()

Promise Chrome 65 以上版本

chrome.system.display.setMirrorMode(
  info: MirrorModeInfo,
  callback?: function,
)

將顯示模式設為指定的鏡像模式。每次呼叫都會重設先前呼叫的狀態。無法為鏡像目的地顯示畫面呼叫 setDisplayProperties()。注意：這僅適用於 Chrome OS 資訊站應用程式和網頁 UI。

參數

• 資訊

  MirrorModeInfo

  應套用至顯示模式的鏡像模式資訊。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 91 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

showNativeTouchCalibration()

Promise Chrome 57 以上版本

chrome.system.display.showNativeTouchCalibration(
  id: string,
  callback?: function,
)

顯示螢幕 ID 為 id 的原生觸控校正使用者體驗。此時系統會在螢幕上疊加顯示畫面，並提供後續步驟指示。只有在校正成功時，才會叫用回呼。如果校正失敗，就會擲回錯誤。

參數

• id

  字串

  螢幕的專屬 ID。

• 回呼

  函式 選用

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    布林值

傳回

• Promise&lt;boolean&gt;

  Chrome 91 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

startCustomTouchCalibration()

Chrome 57 以上版本

chrome.system.display.startCustomTouchCalibration(
  id: string,
)

開始在螢幕上自訂觸控校正功能。使用自訂使用者體驗收集校正資料時，應呼叫此方法。如果正在進行其他觸控校正，就會擲回錯誤。

參數

• id

  字串

  螢幕的專屬 ID。

活動

onDisplayChanged

chrome.system.display.onDisplayChanged.addListener(
  callback: function,
)

當顯示設定發生變更時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void