chrome.system.display

說明

使用 system.display API 查詢顯示中繼資料。

權限

system.display

類型

ActiveState

Chrome 117 以上版本

指出系統是否偵測到及使用螢幕的列舉。如果系統未偵測到螢幕，則螢幕會視為「未啟用」(可能會中斷連線，或是因睡眠模式而判定為未連線)。舉例來說，這個狀態可在所有螢幕中斷連線時保留現有螢幕。

列舉

Bounds

屬性

• 高度

  號碼

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

• 左

  號碼

  左上角的 x 座標。

• 上

  號碼

  左上角的 y 座標。

• 寬度

  號碼

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

DisplayLayout

Chrome 53 以上版本

屬性

• id

  字串

  螢幕的專屬 ID。

• 碳補償

  號碼

  螢幕在連結邊緣的偏移情形。0 表示最頂端或最左側的角落已對齊。

• parentId

  字串

  上層螢幕的專屬 ID。如果這是根目錄，則為空白。

• 排名

  LayoutPosition

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

DisplayMode

Chrome 52 以上版本

屬性

• deviceScaleFactor

  號碼

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

• 高度

  號碼

  顯示模式高度 (以裝置為單位) (使用者可見) 像素。

• heightInNativePixels

  號碼

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

• isInterlaced

  布林值 (選用)

  Chrome 74 以上版本

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

• isNative

  boolean

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

• isSelected

  boolean

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

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

  設定後，更新與顯示畫面相關聯的縮放比例。這個縮放功能可執行重新配置與重新繪製的動作，因此，與單純執行像素延展放大功能相比，這項縮放功能可提供更好的縮放品質。

• isPrimary

  布林值 (選用)

  如果設為 true，系統會將螢幕設為主要顯示畫面。如果設為 false，則為 No-op。注意：如有設定，系統會將顯示畫面視為所有其他資源的主要畫面 (也就是說，可選擇設定 isUnified，且邊界來源不得)。

• isUnified

  布林值 (選用)

  Chrome 59 以上版本

  僅限 ChromeOS。如果設為 True，系統會將顯示模式變更為整合桌面 (詳情請參閱 enableUnifiedDesktop)。如果設為 False，系統就會停用整合桌面模式。這個做法僅適用於主要螢幕。如果提供 MirroringSourceId，則不得提供，系統會忽略其他屬性。如未提供，則不會產生任何影響。

• mirroringSourceId

  字串 選用

  自 Chrome 68 版起已淘汰的項目

  使用 setMirrorMode。

  僅限 ChromeOS。如果設定並非空白，請只啟用這個螢幕的鏡像功能。否則，系統會停用所有螢幕的鏡像功能。這個值應指定要建立鏡像的來源顯示畫面 ID，此 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 軸的每英寸像素數。

• Edid

  Edid 選用

  Chrome 67 以上版本

  注意：這項功能僅適用於 Chrome 作業系統資訊站應用程式和網頁 UI。

• hasTouchSupport

  boolean

  Chrome 57 以上版本

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

• id

  字串

  螢幕的專屬 ID。

• isEnabled

  boolean

  如果已啟用這個螢幕，則為「true」。

• isPrimary

  boolean

  如果這是主要螢幕，則為「true」。

• isUnified

  boolean

  Chrome 59 以上版本

  採用整合桌面模式時，所有螢幕均為 true。請參閱 enableUnifiedDesktop 的說明文件。

• mirroringDestinationIds

  string[]

  Chrome 64 以上版本

  僅限 ChromeOS。用於鏡像顯示來源螢幕的螢幕 ID。如果未鏡像投放任何螢幕，則為空白。在所有螢幕中，這會設為相同的值。其中不得包含 mirroringSourceId。

• mirroringSourceId

  字串

  僅限 ChromeOS。在已啟用鏡像功能的情況下，所鏡像顯示螢幕的 ID，否則為空白。這項設定會套用到所有螢幕 (包括鏡像的螢幕)。

• modes

  DisplayMode[]

  Chrome 52 以上版本

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

• 名稱

  字串

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

• 遮視範圍

  插邊

  螢幕的插邊位於螢幕邊界內。目前只會顯示在 ChromeOS 上。在其他平台上的插邊會設為空白。

• 旋轉

  號碼

  螢幕的順時針旋轉 (相對於垂直位置)。目前只會顯示在 ChromeOS 上。在其他平台上將設為 0。如果裝置處於實體平板電腦狀態，系統會將值為 -1 的判定為自動旋轉。

• workArea

  邊界

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

Edid

Chrome 67 以上版本

屬性

• manufacturerId

  字串

  3 個字元的製造商代碼。請參閱「Sec. 3.4.1」第 21 頁。1.4 版是必要項目。

• productId

  字串

  2 位元組製造商指派的程式碼，第 3.4.2 頁，第 21 頁。1.4 版是必要項目。

• yearOfManufacture

  號碼

  製造商年份，第 3.4.4 頁，第 22 頁。1.4 版是必要項目。

GetInfoFlags

Chrome 59 以上版本

屬性

• singleUnified

  布林值 (選用)

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

Insets

屬性

• 下

  號碼

  Y 軸與底部邊界的距離。

• 左

  號碼

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

• 右

  號碼

  與右側邊界的 X 軸距離。

• 上

  號碼

  Y 軸與頂端邊界的距離。

LayoutPosition

Chrome 53 以上版本

版面配置位置，即螢幕附加的父項邊緣。

列舉

"top"

"left"

MirrorMode

Chrome 65 以上版本

鏡像模式，亦即採取不同方式將螢幕鏡像呈現到其他螢幕的方式。

列舉

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

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

"mixed"
指定指定的來源螢幕將同步到提供的目的地螢幕。系統會擴充所有其他已連結的螢幕。

MirrorModeInfo

Chrome 65 以上版本

屬性

• mirroringDestinationIds

  string[] 選填

  鏡像目的地的 ID 會隨即顯示。這個值僅適用於「混合」內容。

• mirroringSourceId

  字串 選用

  鏡像來源顯示畫面的 ID。這個值僅適用於「混合」內容。

• 模式

  MirrorMode

  應設定的鏡像模式。

Point

Chrome 57 以上版本

屬性

• x

  號碼

  點的 x 座標。

• y

  號碼

  點的 y 座標。

TouchCalibrationPair

Chrome 57 以上版本

屬性

• displayPoint

  點

  顯示點的座標。

• touchPoint

  點

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

TouchCalibrationPairQuad

Chrome 57 以上版本

屬性

• pair1

  TouchCalibrationPair

  使用第一組觸控和顯示點進行觸控校正。

• pair2

  TouchCalibrationPair

  進行觸控校正時需要兩對觸控和顯示點。

• pair3

  TouchCalibrationPair

  進行觸控校正時需要使用第三對觸控和顯示點。

• 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 作業系統資訊站應用程式和網頁 UI。

參數

• 已啟用

  boolean

  如果應啟用統合桌面，則為 True。

getDisplayLayout()

Promise Chrome 53 以上版本

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

要求所有螢幕的版面配置資訊。注意：這項功能僅適用於 Chrome 作業系統資訊站應用程式和網頁 UI。

參數

• 回呼

  函式選用

  callback 參數如下所示：

  (layouts: DisplayLayout[])=>void

  • 版面配置

    DisplayLayout[]

傳回

• Promise<DisplayLayout[]>

  Chrome 91 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getInfo()

Promise

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

要求取得所有連接的顯示裝置的資訊。

參數

• flag

  GetInfoFlags 選用

  Chrome 59 以上版本

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

• 回呼

  函式選用

  callback 參數如下所示：

  (displayInfo: DisplayUnitInfo[])=>void

  • displayInfo

    DisplayUnitInfo[]

傳回

• Promise<DisplayUnitInfo[]>

  Chrome 91 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

overscanCalibrationAdjust()

Chrome 53 以上版本

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

調整顯示畫面目前的遮蔽插邊。一般而言，這麼做應沿著軸線移動螢幕 (例如：向左 + 向右移動的值相同)，或是沿著軸縮放 (例如，頂端和底部的值相反)。每次調整呼叫後，系統會隨先前的通話累積次數。

參數

• 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 作業系統資訊站應用程式和網頁 UI。

參數

• 版面配置

  DisplayLayout[]

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

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 91 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setDisplayProperties()

Promise

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

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

參數

• id

  字串

  螢幕的專屬 ID，

• 資訊

  DisplayProperties

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

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 91 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setMirrorMode()

Promise Chrome 65 以上版本

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

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

參數

• 資訊

  MirrorModeInfo

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

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 91 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

showNativeTouchCalibration()

Promise Chrome 57 以上版本

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

顯示螢幕原生觸控校正使用者體驗，以 id 做為螢幕 ID。畫面上會顯示重疊訊息，說明如何繼續進行後續步驟。只有在校正成功時，系統才會叫用回呼。如果校正失敗，就會擲回錯誤。

參數

• id

  字串

  螢幕的專屬 ID，

• 回呼

  函式選用

  callback 參數如下所示：

  (success: boolean)=>void

  • 成功

    boolean

傳回

• Promise<boolean>

  Chrome 91 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

startCustomTouchCalibration()

Chrome 57 以上版本

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

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

參數

• id

  字串

  螢幕的專屬 ID，

活動

onDisplayChanged

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

對顯示設定做出任何變更時觸發。

參數

• 回呼

  功能

  callback 參數如下所示：

  ()=>void