chrome.system.display

說明

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

權限

system.display

類型

ActiveState

Chrome 117 以上版本

列舉值，用於指出系統是否偵測到並使用螢幕。如果系統未偵測到螢幕 (可能已中斷連線，或因睡眠模式而被視為中斷連線)，則系統會將螢幕視為「非活動」狀態。例如，當所有螢幕都已中斷連線時，系統會使用此狀態保留現有螢幕。

列舉

"active"

「inactive」

Bounds

屬性

• 高度

  數字

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

• 左側

  數字

  左上角的 X 座標。

• 頂端

  數字

  左上角的 y 座標。

• 寬度

  數字

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

DisplayLayout

Chrome 53 以上版本

屬性

• id

  字串

  螢幕的專屬 ID。

• 碳補償

  數字

  沿著連接邊緣的顯示偏移量。0 表示最上方或最左側的角落已對齊。

• parentId

  字串

  父項顯示項目的專屬 ID。如果是根目錄，則留空。

• 位置

  LayoutPosition

  這個顯示畫面相對於父項的版面配置位置。系統會忽略根目錄。

DisplayMode

Chrome 52 以上版本

屬性

• deviceScaleFactor

  數字

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

• 高度

  數字

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

• heightInNativePixels

  數字

  原生像素的顯示模式高度。

• isInterlaced

  boolean 選填

  Chrome 74 以上版本

  如果是交錯模式，則傳回「是」；如果未提供，則傳回「否」。

• isNative

  布林值

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

• isSelected

  布林值

  如果目前選取了顯示模式，則為 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

  boolean 選填

  如果設為 true，則會將螢幕設為主要螢幕。如果設為 false，則不會執行任何操作。注意：如果已設定，系統會將顯示畫面視為所有其他屬性的主要屬性 (也就是 isUnified 可能已設定，但邊界原點可能未設定)。

• isUnified

  boolean 選填

  Chrome 59 以上版本

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

• mirroringSourceId

  string 選填

  自 Chrome 68 版起淘汰

  使用 setMirrorMode。

  僅限 ChromeOS。如果已設定且不為空白，則只會為此螢幕啟用鏡像。否則會停用所有螢幕的鏡像輸出功能。這個值應指出要鏡像的來源螢幕 ID，且不得與傳遞至 setDisplayProperties 的 ID 相同。如果已設定，則無法再設定其他屬性。

• 過掃

  插邊 選填

  如果已設定，則會將顯示器的過掃邊距設定為提供的值。請注意，過掃值不得為負值，也不得大於螢幕尺寸的一半。無法在內部螢幕上變更過掃範圍。

• 旋轉

  號碼 選填

  如果設為此值，系統會更新螢幕旋轉功能。有效值為 [0, 90, 180, 270]。旋轉方向是依據螢幕的垂直位置，以順時針方向設定。

DisplayUnitInfo

屬性

• activeState

  ActiveState

  Chrome 117 以上版本

  如果系統偵測到並使用螢幕，則為有效。

• availableDisplayZoomFactors

  number[]

  Chrome 67 以上版本

  可為螢幕設定的縮放比例值清單。

• 邊界

  邊界

  螢幕的邏輯邊界。

• displayZoomFactor

  數字

  Chrome 65 以上版本

  顯示畫面目前與預設縮放比例的差距。舉例來說，值 1 等同於 100% 縮放，值 1.5 等同於 150% 縮放。

• dpiX

  數字

  沿著 X 軸的每英寸像素數量。

• dpiY

  數字

  沿著 Y 軸的每英寸像素數量。

• edid

  Edid 選填

  Chrome 67 以上版本

  注意：這項功能僅適用於 ChromeOS 資訊站應用程式和網頁使用者介面。

• hasTouchSupport

  布林值

  Chrome 57 以上版本

  如果螢幕與觸控輸入裝置相關聯，則為 True。

• id

  字串

  螢幕的專屬 ID。

• isEnabled

  布林值

  如果已啟用這項顯示功能，則為「是」。

• isPrimary

  布林值

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

• 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

  boolean 選填

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

Insets

屬性

• 底部

  數字

  與底部邊界之間的 y 軸距離。

• 左側

  數字

  與左邊界線的 x 軸距離。

• 右側

  數字

  與右邊界線的 x 軸距離。

• 頂端

  數字

  與頂端邊界之間的 y 軸距離。

LayoutPosition

Chrome 53 以上版本

版面配置位置，也就是顯示器連結的父項邊緣。

列舉

"top"

「right」

"bottom"

"left"

MirrorMode

Chrome 65 以上版本

鏡像模式，也就是將畫面鏡像投放至其他螢幕的不同方式。

列舉

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

「normal」
指定預設來源螢幕會鏡像顯示至所有其他螢幕。

「mixed」
指定來源螢幕會鏡像至提供的目的螢幕。所有其他已連接的螢幕都會延長。

MirrorModeInfo

Chrome 65 以上版本

屬性

• mirroringDestinationIds

  string[] 選填

  顯示鏡像目的地的 ID。這項屬性僅適用於「混合」模式。

• mirroringSourceId

  string 選填

  鏡像來源螢幕的 ID。這項屬性僅適用於「混合」模式。

• 模式

  MirrorMode

  應設定的鏡像模式。

Point

Chrome 57 以上版本

屬性

• x

  數字

  點的 x 座標。

• y

  數字

  點的 y 座標。

TouchCalibrationPair

Chrome 57 以上版本

屬性

• displayPoint

  Point

  顯示點的座標。

• touchPoint

  Point

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

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,
)

啟用/停用整合式桌面功能。如果在鏡像模式啟用時啟用這項功能，系統會在鏡像模式關閉時才變更桌面模式，否則桌面模式會立即切換為整合模式。注意：這項功能僅適用於 ChromeOS 資訊站應用程式和網頁使用者介面。

參數

• 已啟用

  布林值

  如果應啟用統一桌面，則為「是」。

getDisplayLayout()

Promise Chrome 53 以上版本

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

要求所有顯示裝置的版面配置資訊。注意：這項功能僅適用於 ChromeOS 資訊站應用程式和網頁使用者介面。

參數

• 回呼

  函式 選填

  callback 參數如下所示：

  (layouts: DisplayLayout[]) => void

  • layouts

    DisplayLayout[]

傳回

• Promise<DisplayLayout[]>

  Chrome 91 以上版本

  承諾僅支援資訊清單 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 以上版本

  承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

overscanCalibrationAdjust()

Chrome 53 以上版本

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

調整顯示器目前的過掃邊距內嵌。一般來說，這個值應沿著軸移動 (例如左+右的值相同)，或沿著軸縮放 (例如上+下有相反的值)。每個 Adjust 呼叫都會累加自「Start」後的先前呼叫。

參數

• 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 事件。注意：這項功能僅適用於 ChromeOS 資訊站應用程式和網頁使用者介面。

參數

• layouts

  DisplayLayout[]

  版面配置資訊，除了主要螢幕外，所有螢幕都需要這項資訊。

• 回呼

  函式 選填

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 91 以上版本

  承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

setDisplayProperties()

Promise

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

根據 info 提供的資訊，更新 id 指定顯示畫面的屬性。發生失敗時，系統會設定 runtime.lastError。注意：這項功能僅適用於 ChromeOS 資訊站應用程式和網頁使用者介面。

參數

• id

  字串

  螢幕的專屬 ID。

• 資訊

  DisplayProperties

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

• 回呼

  函式 選填

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 91 以上版本

  承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

setMirrorMode()

Promise Chrome 65 以上版本

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

將顯示模式設為指定的鏡像模式。每次呼叫都會重設先前呼叫的狀態。對於鏡像的目的螢幕，呼叫 setDisplayProperties() 會失敗。注意：這項功能僅適用於 ChromeOS 資訊站應用程式和網頁使用者介面。

參數

• 資訊

  MirrorModeInfo

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

• 回呼

  函式 選填

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 91 以上版本

  承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

showNativeTouchCalibration()

Promise Chrome 57 以上版本

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

顯示螢幕的本機觸控校正使用者體驗，其中 id 為螢幕 ID。系統會在畫面上顯示疊加層，並提供必要的操作說明。只有在校正成功的情況下，系統才會叫用回呼。如果校正失敗，系統會擲回錯誤。

參數

• id

  字串

  螢幕的專屬 ID。

• 回呼

  函式 選填

  callback 參數如下所示：

  (success: boolean) => void

  • 成功

    布林值

傳回

• Promise<布林值>

  Chrome 91 以上版本

  承諾僅支援資訊清單 V3 以上版本，其他平台則需使用回呼。

startCustomTouchCalibration()

Chrome 57 以上版本

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

開始為螢幕進行自訂觸控校正。使用自訂使用者體驗收集校正資料時，應呼叫此方法。如果系統正在進行其他觸控校正作業，這項作業會擲回錯誤。

參數

• id

  字串

  螢幕的專屬 ID。

活動

onDisplayChanged

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

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

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void