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

    布林值 選填

    Chrome 74 以上版本

    如果這個模式是交錯式，則為 True；如果未提供，則為 False。

  • isNative

    布林值

    如果模式為螢幕的原始模式，則為 True。

  • 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

    布林值 選填

    如果設為 true，則會將螢幕設為主要螢幕。如果設為 false，則為無運算。注意：如果已設定，系統會將顯示畫面視為所有其他屬性的主要顯示畫面 (即可以設定 isUnified，但可能無法設定界線原點)。

  • isUnified

    布林值 選填

    Chrome 59 以上版本

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

  • mirroringSourceId

    字串 選填

    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

    布林值

    如果已啟用這個螢幕，則為 True。

  • isPrimary

    布林值

    如果這是主要螢幕，則為 True。

  • isUnified

    布林值

    Chrome 59 以上版本

    在整合桌面模式下，所有螢幕都會顯示這個畫面。請參閱 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

    字串陣列 選用

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

  • mirroringSourceId

    字串 選填

    鏡像來源螢幕的 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,
): void

清除與螢幕相關聯的觸控校正資料，將螢幕的觸控校正重設為預設狀態。

參數

  • id

    字串

    螢幕的專屬 ID。

completeCustomTouchCalibration()

Chrome 57 以上版本 
chrome.system.display.completeCustomTouchCalibration(
  pairs: TouchCalibrationPairQuad,
  bounds: Bounds,
): void

為螢幕設定觸控校正配對。這些 pairs 會用於校正顯示器的觸控螢幕，並在 startCustomTouchCalibration() 中呼叫 id。呼叫這個方法前，請務必先呼叫 startCustomTouchCalibration。如果系統正在進行其他觸控校準作業，這項作業就會擲回錯誤。

參數

  • 用於校正螢幕的點對。

  • 界限

    界限

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

enableUnifiedDesktop()

Chrome 46 以上版本 
chrome.system.display.enableUnifiedDesktop(
  enabled: boolean,
): void

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

參數

  • 已啟用

    布林值

    是否應啟用整合桌面。

getDisplayLayout()

Chrome 53 以上版本 
chrome.system.display.getDisplayLayout(): Promise<DisplayLayout[]>

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

傳回

getInfo()

chrome.system.display.getInfo(
  flags?: GetInfoFlags,
): Promise<DisplayUnitInfo[]>

要求所有已連接螢幕裝置的資訊。

參數

  • flags

    GetInfoFlags optional

    Chrome 59 以上版本

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

傳回

overscanCalibrationAdjust()

Chrome 53 以上版本 
chrome.system.display.overscanCalibrationAdjust(
  id: string,
  delta: Insets,
): void

調整螢幕目前的過掃內插。通常這應該會沿著軸移動螢幕 (例如左+右的值相同)，或沿著軸縮放螢幕 (例如頂端+底部的值相反)。自「開始」以來，每次呼叫 Adjust 都會累計先前的呼叫。

參數

  • id

    字串

    螢幕的專屬 ID。

  • Delta

    插邊

    變更過掃內插量的量。

overscanCalibrationComplete()

Chrome 53 以上版本 
chrome.system.display.overscanCalibrationComplete(
  id: string,
): void

儲存目前的值並隱藏重疊畫面，即可完成螢幕的過掃調整。

參數

  • id

    字串

    螢幕的專屬 ID。

overscanCalibrationReset()

Chrome 53 以上版本 
chrome.system.display.overscanCalibrationReset(
  id: string,
): void

將螢幕的過掃描插邊重設為上次儲存的值 (即呼叫 Start 前的值)。

參數

  • id

    字串

    螢幕的專屬 ID。

overscanCalibrationStart()

Chrome 53 以上版本 
chrome.system.display.overscanCalibrationStart(
  id: string,
): void

開始螢幕的過掃校正。畫面上會顯示疊加層，指出目前的過掃內插。如果顯示器 id 正在進行過掃描校正，這項操作會重設校正。

參數

  • id

    字串

    螢幕的專屬 ID。

setDisplayLayout()

Chrome 53 以上版本 
chrome.system.display.setDisplayLayout(
  layouts: DisplayLayout[],
): Promise<void>

為所有螢幕設定版面配置。未納入的螢幕會使用預設版面配置。如果版面配置會重疊或無效，系統會調整為有效版面配置。版面配置解決後，系統會觸發 onDisplayChanged 事件。注意：這項功能僅適用於 ChromeOS 資訊站應用程式和網頁使用者介面。

參數

  • 版面配置

    DisplayLayout[]

    版面配置資訊，所有螢幕 (主要螢幕除外) 皆須提供。

傳回

  • Promise<void>

    Chrome 91 以上版本

setDisplayProperties()

chrome.system.display.setDisplayProperties(
  id: string,
  info: DisplayProperties,
): Promise<void>

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

參數

  • id

    字串

    螢幕的專屬 ID。

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

傳回

  • Promise<void>

    Chrome 91 以上版本

setMirrorMode()

Chrome 65 以上版本 
chrome.system.display.setMirrorMode(
  info: MirrorModeInfo,
): Promise<void>

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

參數

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

傳回

  • Promise<void>

    Chrome 91 以上版本

showNativeTouchCalibration()

Chrome 57 以上版本 
chrome.system.display.showNativeTouchCalibration(
  id: string,
): Promise<boolean>

顯示螢幕的觸控校正原生 UX，其中 id 為螢幕 ID。畫面上會顯示疊加層，內含後續步驟的必要指示。只有在校正成功時，系統才會叫用回呼。如果校正失敗，系統會擲回錯誤。

參數

  • id

    字串

    螢幕的專屬 ID。

傳回

  • Promise<boolean>

    Chrome 91 以上版本

startCustomTouchCalibration()

Chrome 57 以上版本 
chrome.system.display.startCustomTouchCalibration(
  id: string,
): void

開始螢幕的自訂觸控校正。如果使用自訂使用者體驗收集校正資料，就應呼叫這個函式。如果系統正在進行其他觸控校準作業，這項作業就會擲回錯誤。

參數

  • id

    字串

    螢幕的專屬 ID。

事件

onDisplayChanged

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

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

參數

  • callback

    函式

    callback 參數如下： 

    () => void