chrome.system.display

refresh date: 2026-09-25 robots: noindex

說明

使用 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 頁。1.4 版的必要條件。

  • productId

    字串

    2 位元組的製造商指派代碼，請參閱第 3.4.2 節第 21 頁。1.4 版必須提供這項資訊。

  • yearOfManufacture

    數字

    製造年份，第 3.4.4 節第 22 頁。1.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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。清除與螢幕相關聯的觸控校準資料，將螢幕的觸控校準重設為預設狀態。

參數

  • id

    字串

    螢幕的專屬 ID。

completeCustomTouchCalibration()

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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。設定螢幕的觸控校準配對。這些 pairs 會用於校正螢幕，以便在 startCustomTouchCalibration() 中呼叫 id。呼叫這個方法前，請務必先呼叫 startCustomTouchCalibration。如果已在進行其他觸控校正，系統會擲回錯誤。

參數

  • 用於校正螢幕的點對。

  • 界限

    界線

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

enableUnifiedDesktop()

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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。啟用/停用統一電腦版功能。如果啟用這項功能時正在鏡像輸出，電腦模式不會變更，直到鏡像輸出關閉為止。否則，電腦模式會立即切換為整合模式。

參數

  • 已啟用

    布林值

    如果應啟用統一桌面，則為 True。

getDisplayLayout()

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

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

參數

傳回

  • Promise<DisplayLayout[]>

    Chrome 91 以上版本

    Promise，會以結果解析。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

getInfo()

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

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

參數

  • flags

    GetInfoFlags 選用

    Chrome 59 以上版本

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

  • callback

    函式 選填

    callback 參數如下： 

    (displayInfo: DisplayUnitInfo[]) => void

傳回

  • Promise<DisplayUnitInfo[]>

    Chrome 91 以上版本

    Promise，會以結果解析。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

overscanCalibrationAdjust()

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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。調整螢幕目前的過掃內插。通常這應該會沿著軸移動螢幕 (例如左側和右側的值相同)，或沿著軸縮放螢幕 (例如頂端和底端的值相反)。自「開始」以來，每次 Adjust 呼叫都會累加。

參數

  • id

    字串

    螢幕的專屬 ID。

  • delta

    插邊

    要變更過掃內插量的量。

overscanCalibrationComplete()

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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。如要完成螢幕的過掃調整，請儲存目前的值並隱藏疊加層。

參數

  • id

    字串

    螢幕的專屬 ID。

overscanCalibrationReset()

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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。將螢幕的過掃描插邊重設為上次儲存的值 (即呼叫 Start 前的值)。

參數

  • id

    字串

    螢幕的專屬 ID。

overscanCalibrationStart()

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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。開始螢幕的過掃校正。畫面上會顯示疊加層，指出目前的過掃內插。如果正在校正螢幕 id 的過掃，這項操作會重設校正。

參數

  • id

    字串

    螢幕的專屬 ID。

setDisplayLayout()

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

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

參數

  • 版面配置

    DisplayLayout[]

    版面配置資訊，主要螢幕以外的所有螢幕都必須提供。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    函式完成時會解析的 Promise。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

setDisplayProperties()

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

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

參數

  • id

    字串

    螢幕的專屬 ID。

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

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    函式完成時會解析的 Promise。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

setMirrorMode()

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

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

參數

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

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    函式完成時會解析的 Promise。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

showNativeTouchCalibration()

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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。顯示螢幕的原生觸控校準 UX，其中 id 為螢幕 ID。畫面上會顯示疊加層，內含繼續操作的必要指示。只有在校正成功時，才會叫用回呼。如果校正失敗，系統會擲回錯誤。

參數

  • id

    字串

    螢幕的專屬 ID。

  • callback

    函式 選填

    callback 參數如下： 

    (success: boolean) => void

    • 成功

      布林值

傳回

  • Promise<boolean>

    Chrome 91 以上版本

    這個 Promise 會解析，通知呼叫者觸控校正已結束。布林值會指出校準是否成功。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

startCustomTouchCalibration()

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

注意：這項功能僅適用於 ChromeOS 資訊站應用程式。開始校正螢幕的自訂觸控功能。使用自訂 UX 收集校準資料時，應呼叫此函式。如果已在進行其他觸控校正，系統會擲回錯誤。

參數

  • id

    字串

    螢幕的專屬 ID。

事件

onDisplayChanged

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

顯示器設定有任何變更時，就會觸發這個事件。

參數

  • callback

    函式

    callback 參數如下： 

    () => void