chrome.system.display

說明

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

權限

system.display

類型

ActiveState

Chrome 117 以上版本

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

列舉

"active"

"已停用"

Bounds

屬性

  • 高度

    數字

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

  • 左側

    數字

    左上角的 x 座標。

  • 頂端

    數字

    左上角的 y 座標。

  • 寬度

    數字

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

DisplayLayout

Chrome 53 以上版本

屬性

  • id

    字串

    螢幕的專屬 ID。

  • 碳補償

    數字

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

  • parentId

    字串

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

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

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 以上版本

屬性

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 以上版本

屬性

方法

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。如果正在進行其他觸控校正，就會擲回錯誤。

參數

  • 用來校正螢幕的點對組。

  • 界限

    邊界

    執行觸控校正時的螢幕邊界。系統會忽略 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。

參數

傳回

  • 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

傳回

  • 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。

  • 應變更的顯示屬性相關資訊。只有在 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。

參數

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

  • 回呼

    函式 選用

    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