說明
使用 system.display
API 查詢顯示中繼資料。
權限
system.display
類型
ActiveState
指出系統是否偵測到及使用螢幕的列舉。如果系統未偵測到螢幕,則螢幕會視為「未啟用」(可能會中斷連線,或是因睡眠模式而判定為未連線)。舉例來說,這個狀態可在所有螢幕中斷連線時保留現有螢幕。
列舉
Bounds
屬性
-
高度
號碼
螢幕的高度 (以像素為單位)。
-
左
號碼
左上角的 x 座標。
-
上
號碼
左上角的 y 座標。
-
寬度
號碼
螢幕的寬度 (以像素為單位)。
DisplayLayout
屬性
-
id
字串
螢幕的專屬 ID。
-
碳補償
號碼
螢幕在連結邊緣的偏移情形。0 表示最頂端或最左側的角落已對齊。
-
parentId
字串
上層螢幕的專屬 ID。如果這是根目錄,則為空白。
-
這個螢幕相對於父項的版面配置位置。系統會在根層級忽略這個屬性。
DisplayMode
屬性
-
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
屬性
-
activeStateChrome 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,否則為空白。這項設定會套用到所有螢幕 (包括鏡像的螢幕)。
-
modesChrome 52 以上版本
可用的顯示模式清單。目前的模式將是 isSelected=true。(僅適用於 ChromeOS)。會設為其他平台上的空白陣列。
-
名稱
字串
使用者易記的名稱 (例如「HP LCD 螢幕」)。
-
遮視範圍
螢幕的插邊位於螢幕邊界內。目前只會顯示在 ChromeOS 上。在其他平台上的插邊會設為空白。
-
旋轉
號碼
螢幕的順時針旋轉 (相對於垂直位置)。目前只會顯示在 ChromeOS 上。在其他平台上將設為 0。如果裝置處於實體平板電腦狀態,系統會將值為 -1 的判定為自動旋轉。
-
workArea
螢幕在顯示範圍內的可用工作區域。工作區域不含為 OS 預留的螢幕區域,例如工作列和啟動器。
Edid
屬性
-
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
屬性
-
singleUnified
布林值 (選用)
如果設為 True,
getInfo
會在整合桌面模式時只傳回一個DisplayUnitInfo
(請參閱enableUnifiedDesktop
)。預設值為 False。
Insets
屬性
-
下
號碼
Y 軸與底部邊界的距離。
-
左
號碼
與左側邊界之間的 x 軸距離。
-
右
號碼
與右側邊界的 X 軸距離。
-
上
號碼
Y 軸與頂端邊界的距離。
LayoutPosition
版面配置位置,即螢幕附加的父項邊緣。
列舉
"top"
"left"
MirrorMode
鏡像模式,亦即採取不同方式將螢幕鏡像呈現到其他螢幕的方式。
列舉
"off"
指定預設模式 (擴充或統一桌面)。
"normal"
指定預設來源螢幕將鏡像到所有其他螢幕。
"mixed"
指定指定的來源螢幕將同步到提供的目的地螢幕。系統會擴充所有其他已連結的螢幕。
MirrorModeInfo
屬性
-
mirroringDestinationIds
string[] 選填
鏡像目的地的 ID 會隨即顯示。這個值僅適用於「混合」內容。
-
mirroringSourceId
字串 選用
鏡像來源顯示畫面的 ID。這個值僅適用於「混合」內容。
-
模式
應設定的鏡像模式。
Point
屬性
-
x
號碼
點的 x 座標。
-
y
號碼
點的 y 座標。
TouchCalibrationPair
TouchCalibrationPairQuad
屬性
-
pair1
使用第一組觸控和顯示點進行觸控校正。
-
pair2
進行觸控校正時需要兩對觸控和顯示點。
-
pair3
進行觸控校正時需要使用第三對觸控和顯示點。
-
pair4
進行觸控校正時需要使用第四對觸控和顯示點。
方法
clearTouchCalibration()
chrome.system.display.clearTouchCalibration(
id: string,
)
如要重設螢幕的觸控校正,並清除與螢幕相關的任何觸控校正資料,則請清除螢幕設定。
參數
-
id
字串
螢幕的專屬 ID,
completeCustomTouchCalibration()
chrome.system.display.completeCustomTouchCalibration(
pairs: TouchCalibrationPairQuad,
bounds: Bounds,
)
設定螢幕的觸控校正配對。這些 pairs
將使用在 startCustomTouchCalibration() 中呼叫的 id
校正觸控螢幕的顯示設定。呼叫此方法前,務必先呼叫 startCustomTouchCalibration
。如果正在執行其他觸控校正,就會擲回錯誤。
參數
-
用於校正顯示畫面的點對組。
-
邊界
執行觸控校正時的畫面邊界。系統會忽略
bounds.left
和bounds.top
值。
enableUnifiedDesktop()
chrome.system.display.enableUnifiedDesktop(
enabled: boolean,
)
啟用/停用整合桌面功能。如果啟用鏡像功能,系統會在鏡像功能關閉前變更桌面模式。否則,桌面模式會立即切換為統合。注意:這項功能僅適用於 Chrome 作業系統資訊站應用程式和網頁 UI。
參數
-
已啟用
boolean
如果應啟用統合桌面,則為 True。
getDisplayLayout()
chrome.system.display.getDisplayLayout(
callback?: function,
)
要求所有螢幕的版面配置資訊。注意:這項功能僅適用於 Chrome 作業系統資訊站應用程式和網頁 UI。
參數
-
回呼
函式選用
callback
參數如下所示:(layouts: DisplayLayout[]) => void
-
版面配置
-
傳回
-
Promise<DisplayLayout[]>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getInfo()
chrome.system.display.getInfo(
flags?: GetInfoFlags,
callback?: function,
)
要求取得所有連接的顯示裝置的資訊。
參數
-
flag
GetInfoFlags 選用
Chrome 59 以上版本影響資訊傳回方式的選項。
-
回呼
函式選用
callback
參數如下所示:(displayInfo: DisplayUnitInfo[]) => void
-
displayInfo
-
傳回
-
Promise<DisplayUnitInfo[]>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
overscanCalibrationAdjust()
chrome.system.display.overscanCalibrationAdjust(
id: string,
delta: Insets,
)
調整顯示畫面目前的遮蔽插邊。一般而言,這麼做應沿著軸線移動螢幕 (例如:向左 + 向右移動的值相同),或是沿著軸縮放 (例如,頂端和底部的值相反)。每次調整呼叫後,系統會隨先前的通話累積次數。
參數
-
id
字串
螢幕的專屬 ID,
-
Delta 符號
變更過度掃描插邊的量。
overscanCalibrationComplete()
chrome.system.display.overscanCalibrationComplete(
id: string,
)
儲存目前的值並隱藏疊加層,完成螢幕的過度掃描調整。
參數
-
id
字串
螢幕的專屬 ID,
overscanCalibrationReset()
chrome.system.display.overscanCalibrationReset(
id: string,
)
將顯示畫面的過度掃描插邊重設為最後儲存的值 (即呼叫 Start 之前)。
參數
-
id
字串
螢幕的專屬 ID,
overscanCalibrationStart()
chrome.system.display.overscanCalibrationStart(
id: string,
)
開始掃描螢幕的過度掃描。螢幕上會顯示重疊元素,指出目前的過度掃描插邊。如果正在進行螢幕 id
的掃描校正,這會重設校正。
參數
-
id
字串
螢幕的專屬 ID,
setDisplayLayout()
chrome.system.display.setDisplayLayout(
layouts: DisplayLayout[],
callback?: function,
)
設定所有螢幕的版面配置。任何未納入的螢幕都會使用預設版面配置。如果版面配置重疊或無效,系統會將版面配置調整為有效的版面配置。解決版面配置後,就會觸發 onDisplayChanged 事件。注意:這項功能僅適用於 Chrome 作業系統資訊站應用程式和網頁 UI。
參數
-
版面配置
所有螢幕 (主要螢幕除外) 所需的版面配置資訊。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setDisplayProperties()
chrome.system.display.setDisplayProperties(
id: string,
info: DisplayProperties,
callback?: function,
)
根據 info
中提供的資訊,更新 id
指定的螢幕屬性。失敗時,系統會設定runtime.lastError
。注意:這項功能僅適用於 Chrome 作業系統資訊站應用程式和網頁 UI。
參數
-
id
字串
螢幕的專屬 ID,
-
應變更的顯示屬性相關資訊。只有在
info
指定該屬性的新值時,系統才會變更屬性。 -
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setMirrorMode()
chrome.system.display.setMirrorMode(
info: MirrorModeInfo,
callback?: function,
)
將顯示模式設為指定的鏡像模式。每次通話都會重設先前的通話狀態。鏡像目的地顯示畫面將無法呼叫 setDisplayProperties()。注意:這項功能僅適用於 Chrome 作業系統資訊站應用程式和網頁 UI。
參數
-
應套用至顯示模式的鏡像模式資訊。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
showNativeTouchCalibration()
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.system.display.startCustomTouchCalibration(
id: string,
)
開始自訂螢幕的觸控校正。使用自訂使用者體驗收集校正資料時,應呼叫這個方法。如果正在執行其他觸控校正,就會擲回錯誤。
參數
-
id
字串
螢幕的專屬 ID,
活動
onDisplayChanged
chrome.system.display.onDisplayChanged.addListener(
callback: function,
)
對顯示設定做出任何變更時觸發。
參數
-
回呼
功能
callback
參數如下所示:() => void