chrome.system.display

說明

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

權限

system.display

類型

ActiveState

Chrome 117 以上版本

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

列舉

"active"

「inactive」

Bounds

屬性

  • 高度

    數字

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

  • 左側

    數字

    左上角的 X 座標。

  • 頂端

    數字

    左上角的 y 座標。

  • 寬度

    數字

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

DisplayLayout

Chrome 53 以上版本

屬性

  • id

    字串

    螢幕的專屬 ID。

  • 碳補償

    數字

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

  • parentId

    字串

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

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

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

屬性

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

屬性

方法

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

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

參數

  • 已啟用

    布林值

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

getDisplayLayout()

Promise Chrome 53 以上版本 
chrome.system.display.getDisplayLayout(
  callback?: function,
)

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

參數

傳回

  • Promise<DisplayLayout[]>

    Chrome 91 以上版本

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

getInfo()

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

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

參數

  • flags

    GetInfoFlags 選填

    Chrome 59 以上版本

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (displayInfo: DisplayUnitInfo[]) => void

傳回

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

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

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

setMirrorMode()

Promise Chrome 65 以上版本 
chrome.system.display.setMirrorMode(
  info: MirrorModeInfo,
  callback?: function,
)

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

參數

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

  • 回呼

    函式 選填

    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