說明
使用 system.display API 查詢向上傳者顯示的中繼資料。
權限
system.display類型
ActiveState
這個列舉值可指出系統是否偵測到並使用螢幕。如果系統未偵測到螢幕 (可能已中斷連線，或因休眠模式等原因而視為中斷連線)，則會視為「未啟用」。舉例來說，當所有螢幕都中斷連線時，這個狀態可用於保留現有螢幕。
列舉
"active"
"inactive"
Bounds
屬性
-
高度
數字
螢幕高度 (以像素為單位)。
-
左
數字
左上角的 X 座標。
-
頂端
數字
左上角的 Y 座標。
-
寬度
數字
螢幕寬度 (以像素為單位)。
DisplayLayout
屬性
-
id
字串
螢幕的專屬 ID。
-
碳補償
數字
螢幕沿著連接邊緣的偏移量。0 表示最頂端或最左側的角落對齊。
-
parentId
字串
上層螢幕的專屬 ID。如果這是根目錄，則留空。
-
這個螢幕相對於父項的版面配置位置。根目錄會忽略這個值。
DisplayMode
屬性
-
deviceScaleFactor
數字
顯示模式裝置縮放比例係數。
-
高度
數字
顯示模式高度，以與裝置無關 (使用者可見) 的像素為單位。
-
heightInNativePixels
數字
顯示模式高度 (以原生像素為單位)。
-
isInterlaced
布林值 選填
Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起如果這個模式為交錯式，則為 True；如果未提供，則為 False。
-
isNative
布林值
如果模式是螢幕的原生模式，則為 True。
-
isSelected
布林值
如果目前已選取顯示模式，則為 True。
-
refreshRate
數字
Chrome 67 以上版本 Chrome 148 起為 browser.*顯示模式刷新率 (單位為赫茲)。
-
uiScale
數字 選填
自 Chrome 70 起淘汰使用
displayZoomFactor顯示模式 UI 縮放比例係數。
-
寬度
數字
顯示模式寬度，以裝置獨立 (使用者可見) 像素為單位。
-
widthInNativePixels
數字
顯示模式寬度 (以原生像素為單位)。
DisplayProperties
屬性
-
boundsOriginX
數字 選填
如果設定，則會沿著 X 軸更新螢幕的邏輯邊界原點。與
boundsOriginY一起套用。如未設定，但已設定boundsOriginY，則預設為目前的值。請注意，更新顯示原點時，系統會套用一些限制，因此最終的邊界原點可能與設定的原點不同。您可以使用getInfo擷取最終邊界。無法變更主要螢幕的邊界原點。 -
boundsOriginY
數字 選填
如果設定，則會沿著 Y 軸更新螢幕的邏輯邊界原點。請參閱
boundsOriginX參數的說明文件。 -
displayMode
DisplayMode 選填
Chrome 52 以上版本 Chrome 148 以上版本中的 browser.*如果設定，系統會將顯示模式更新為與這個值相符的模式。如果其他參數無效，系統就不會套用這項設定。如果顯示模式無效，系統就不會套用該模式，並會設定錯誤，但仍會套用其他屬性。
-
displayZoomFactor
數字 選填
Chrome 65 以上版本 瀏覽器。*自 Chrome 148 起設定後，系統會更新與螢幕相關聯的縮放比例。這種縮放方式會重新配置版面並重新繪製，因此縮放品質比單純逐像素放大更好。
-
isPrimary
布林值 選填
如果設為 True，則會將螢幕設為主要螢幕。如果設為 false，則不會執行任何操作。注意：如果設定，則顯示器會視為所有其他屬性的主要顯示器 (即可能設定
isUnified，且可能未設定邊界原點)。 -
isUnified
布林值 選填
Chrome 59 以上版本 Chrome 148 以上版本的瀏覽器。*僅限 ChromeOS。如果設為 True，系統會將顯示模式變更為統一桌面 (詳情請參閱
enableUnifiedDesktop)。如果設為 False，系統會停用整合桌面模式。這項設定僅適用於主要螢幕。如果提供這項屬性，則不得提供 mirroringSourceId，且系統會忽略其他屬性。如未提供，則不會有任何影響。 -
mirroringSourceId
字串 選填
自 Chrome 68 起淘汰使用
setMirrorMode。僅限 ChromeOS。如果設定且不為空白，則僅為這個螢幕啟用鏡像功能。否則會停用所有螢幕的鏡像功能。這個值應指出要鏡像的來源螢幕 ID，且不得與傳遞至 setDisplayProperties 的 ID 相同。如果設定這項屬性，就無法設定其他屬性。
-
overscan
Insets 選用
如果設定，系統會將螢幕的過度掃描內嵌設為提供的值。請注意，過度掃描值不得為負值，也不得大於螢幕大小的一半。無法變更內部螢幕的過度掃描設定。
-
輪替
數字 選填
如果設定，則會更新螢幕旋轉方向。合法值為 [0, 90, 180, 270]。旋轉角度是相對於螢幕垂直位置，以順時針方向設定。
DisplayUnitInfo
屬性
-
activeStateChrome 117 以上版本 瀏覽器 (自 Chrome 148 起)
如果系統偵測到並使用螢幕，則為「Active」。
-
availableDisplayZoomFactors
number[]
Chrome 67 以上版本 Chrome 148 起為 browser.*可為螢幕設定的縮放係數值清單。
-
bounds
螢幕的邏輯邊界。
-
displayZoomFactor
數字
Chrome 65 以上版本 瀏覽器。*自 Chrome 148 起螢幕目前縮放比例與預設縮放比例的比值。舉例來說，值 1 相當於 100% 縮放，值 1.5 相當於 150% 縮放。
-
dpiX
數字
x 軸上每英寸的像素數。
-
dpiY
數字
沿著 Y 軸每英寸的像素數量。
-
edid
Edid 選填
Chrome 67 以上版本 Chrome 148 起為 browser.*注意：這項功能僅適用於 ChromeOS 資訊站應用程式。
-
hasTouchSupport
布林值
Chrome 57 以上版本 Chrome 148 以上版本支援 browser.*如果這個螢幕有相關聯的觸控輸入裝置，則為 True。
-
id
字串
螢幕的專屬 ID。
-
isEnabled
布林值
如果已啟用這個螢幕，則為 True。
-
isPrimary
布林值
如果這是主要螢幕，則為 True。
-
isUnified
布林值
Chrome 59 以上版本 Chrome 148 以上版本的瀏覽器。*在整合桌面模式下，所有螢幕都會顯示 True。查看
enableUnifiedDesktop的說明文件。 -
mirroringDestinationIds
string[]
Chrome 64+ 瀏覽器 (自 Chrome 148 起)僅適用於 ChromeOS。來源螢幕鏡像輸出的目標螢幕 ID。如果沒有任何螢幕正在鏡像，則為空白。所有螢幕都會設為相同的值。不得包含
mirroringSourceId。 -
mirroringSourceId
字串
僅限 ChromeOS。如果已啟用鏡像功能，則為鏡像顯示器的 ID，否則為空白。這項設定會套用至所有螢幕 (包括鏡像螢幕)。
-
模式Chrome 52 以上版本 Chrome 148 以上版本中的 browser.*
可用顯示模式清單。目前模式的 isSelected 屬性會設為 true。僅適用於 ChromeOS。在其他平台上，這會設為空白陣列。
-
名稱
字串
使用者容易使用的名稱 (例如「HP LCD 螢幕」)。
-
overscan
螢幕邊界內的螢幕內嵌。目前僅在 ChromeOS 上公開。在其他平台上，則會設為空白插邊。
-
輪替
數字
螢幕相對於垂直位置的順時針旋轉角度。目前僅在 ChromeOS 上公開。在其他平台上會設為 0。如果裝置處於實體平板電腦狀態，系統會將 -1 解讀為自動旋轉。
-
workArea
顯示範圍內可用的顯示工作區。工作區不含保留給 OS 的顯示區域，例如工作列和啟動器。
Edid
屬性
-
manufacturerId
字串
3 個半形字元的製造商代碼。請參閱第 3.4.1 節第 21 頁。v1.4 必填。
-
productId
字串
2 位元組製造商指派代碼，第 3.4.2 節第 21 頁。v1.4 必填。
-
yearOfManufacture
數字
製造年份，第 3.4.4 節第 22 頁。v1.4 必填。
GetInfoFlags
屬性
-
singleUnified
布林值 選填
如果設為 True，在整合桌面模式下，
getInfo只會傳回單一DisplayUnitInfo(請參閱enableUnifiedDesktop)。預設值為 False。
Insets
屬性
-
底部
數字
與底部邊界的 Y 軸距離。
-
左
數字
與左側邊界的 X 軸距離。
-
右側
數字
與右側邊界的 X 軸距離。
-
頂端
數字
與頂端邊界的 y 軸距離。
LayoutPosition
版面配置位置，即螢幕連接的父項邊緣。
列舉
"top"
"right"
"bottom"
"left"
MirrorMode
鏡像模式，即將螢幕畫面鏡像到其他螢幕的不同方式。
列舉
"off"
指定預設模式 (延伸或統一桌面)。
"normal"
指定預設來源螢幕會鏡像到所有其他螢幕。
"mixed"
指定將指定的來源螢幕鏡像到提供的目的地螢幕。所有其他連接的螢幕都會延伸。
MirrorModeInfo
屬性
-
mirroringDestinationIds
string[] 選填
鏡像目標螢幕的 ID。這項設定僅適用於「mixed」。
-
mirroringSourceId
字串 選填
鏡像來源螢幕的 ID。這項設定僅適用於「mixed」。
-
模式
應設定的鏡像模式。
Point
屬性
-
x
數字
點的 X 座標。
-
y
數字
點的 y 座標。
TouchCalibrationPair
TouchCalibrationPairQuad
屬性
-
pair1
必須提供第一組觸控和顯示點，才能校正觸控功能。
-
pair2
必須提供第二組觸控和顯示點，才能校正觸控功能。
-
pair3
必須提供第三組觸控和顯示點，才能校正觸控功能。
-
pair4
必須提供第四組觸控和顯示點，才能校正觸控功能。
方法
clearTouchCalibration()
browser.system.display.clearTouchCalibration(
id: string,
): void
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。重設螢幕的觸控校正，並清除與螢幕相關聯的所有觸控校正資料，將螢幕還原為預設狀態。
參數
-
id
字串
螢幕的專屬 ID。
completeCustomTouchCalibration()
browser.system.display.completeCustomTouchCalibration(
pairs: TouchCalibrationPairQuad,
bounds: Bounds,
): void
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。設定螢幕的觸控校正配對。這些 pairs 會用於校正觸控螢幕，以便在 startCustomTouchCalibration() 中呼叫 id 顯示。請務必先呼叫 startCustomTouchCalibration，再呼叫這個方法。如果已有其他觸控校正作業正在進行，系統會擲回錯誤。
參數
-
用於校正顯示器的點組。
-
bounds
執行觸控校正時的螢幕邊界。系統會忽略
bounds.left和bounds.top值。
enableUnifiedDesktop()
browser.system.display.enableUnifiedDesktop(
enabled: boolean,
): void
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。啟用/停用統一桌面功能。如果在啟用鏡像模式時啟用這項設定，則必須先關閉鏡像模式，電腦模式才會變更。否則，電腦模式會立即切換為整合桌面。
參數
-
已啟用
布林值
如果應啟用統一桌面，則為 True。
getDisplayLayout()
browser.system.display.getDisplayLayout(): Promise<DisplayLayout[]>
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。要求所有螢幕的版面配置資訊。
傳回
-
Promise<DisplayLayout[]>
Chrome 91 以上版本 Chrome 148 以上版本：browser.*Promise 會解析結果。
getInfo()
browser.system.display.getInfo(
flags?: GetInfoFlags,
): Promise<DisplayUnitInfo[]>
要求所有連接顯示裝置的資訊。
參數
-
flags
GetInfoFlags 選用
Chrome 59 以上版本 Chrome 148 以上版本的瀏覽器。*影響資訊傳回方式的選項。
傳回
-
Promise<DisplayUnitInfo[]>
Chrome 91 以上版本 Chrome 148 以上版本：browser.*Promise 會解析結果。
overscanCalibrationAdjust()
browser.system.display.overscanCalibrationAdjust(
id: string,
delta: Insets,
): void
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。調整螢幕目前的過度掃描插邊。一般來說，這應該會沿著軸移動螢幕 (例如左側和右側的值相同)，或沿著軸縮放螢幕 (例如頂端和底部的值相反)。每次呼叫 Adjust 都會與自 Start 以來的先前呼叫累加。
參數
-
id
字串
螢幕的專屬 ID。
-
delta
要變更的過掃描內嵌量。
overscanCalibrationComplete()
browser.system.display.overscanCalibrationComplete(
id: string,
): void
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。儲存目前的值並隱藏疊加層，完成顯示器的過度掃描調整。
參數
-
id
字串
螢幕的專屬 ID。
overscanCalibrationReset()
browser.system.display.overscanCalibrationReset(
id: string,
): void
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。將螢幕的過度掃描插邊重設為上次儲存的值 (即呼叫 Start 之前的值)。
參數
-
id
字串
螢幕的專屬 ID。
overscanCalibrationStart()
browser.system.display.overscanCalibrationStart(
id: string,
): void
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。開始校正螢幕的過度掃描。畫面上會顯示疊加層，指出目前的過度掃描插邊。如果顯示器 id 的過度掃描校正作業正在進行中，系統會重設校正作業。
參數
-
id
字串
螢幕的專屬 ID。
setDisplayLayout()
browser.system.display.setDisplayLayout(
layouts: DisplayLayout[],
): Promise<void>
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。設定所有螢幕的版面配置。未包含的螢幕會使用預設版面配置。如果版面配置重疊或無效，系統會調整為有效版面配置。版面配置解析完成後，系統會觸發 onDisplayChanged 事件。
參數
-
版面配置
版面配置資訊，除了主要螢幕外，所有螢幕都必須提供。
傳回
-
承諾<void>
Chrome 91 以上版本 Chrome 148 以上版本：browser.*函式完成時解析的 Promise。
setDisplayProperties()
browser.system.display.setDisplayProperties(
id: string,
info: DisplayProperties,
): Promise<void>
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。根據 info 中提供的資訊，更新 id 指定螢幕的屬性。如果失敗，系統會設定 runtime.lastError。
參數
-
id
字串
螢幕的專屬 ID。
-
應變更的顯示屬性資訊。只有在
info中指定新值，屬性才會變更。
傳回
-
承諾<void>
Chrome 91 以上版本 Chrome 148 以上版本：browser.*函式完成時解析的 Promise。
setMirrorMode()
browser.system.display.setMirrorMode(
info: MirrorModeInfo,
): Promise<void>
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。將顯示模式設為指定的鏡像模式。每次呼叫都會重設先前呼叫的狀態。如果呼叫 setDisplayProperties()，鏡像目標螢幕會失敗。
參數
-
應套用至顯示模式的鏡像模式資訊。
傳回
-
承諾<void>
Chrome 91 以上版本 Chrome 148 以上版本：browser.*函式完成時解析的 Promise。
showNativeTouchCalibration()
browser.system.display.showNativeTouchCalibration(
id: string,
): Promise<boolean>
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。顯示原生觸控校正使用者體驗，適用於顯示 ID 為 id 的螢幕。畫面上會顯示疊加層，並提供必要的操作說明。只有在校正成功時，系統才會叫用回呼。如果校正失敗，系統會擲回錯誤。
參數
-
id
字串
螢幕的專屬 ID。
傳回
-
Promise<boolean>
Chrome 91 以上版本 Chrome 148 以上版本：browser.*Promise 會解析，通知呼叫端觸控校正已結束。布林值會指出校正是否成功。
startCustomTouchCalibration()
browser.system.display.startCustomTouchCalibration(
id: string,
): void
注意：這項功能僅適用於 ChromeOS 資訊站應用程式。開始自訂螢幕觸控校正。使用自訂使用者體驗收集校正資料時，應呼叫這個方法。如果已有其他觸控校正作業正在進行，系統會擲回錯誤。
參數
-
id
字串
螢幕的專屬 ID。
事件
onDisplayChanged
browser.system.display.onDisplayChanged.addListener(
callback: function,
)
顯示設定有任何變更時觸發。
參數
-
callback
函式
callback參數如下：() => void