chrome.system.display

说明

使用 system.display API 查询显示元数据。

权限

system.display

类型

ActiveState

Chrome 117 及更高版本

一个枚举，用于指明系统是否检测到显示屏并使用了显示屏。如果系统未检测到显示屏（可能已断开连接，或因进入休眠模式等原因而被视为已断开连接），则系统会将显示屏视为“非活跃”。例如，此状态用于在所有显示屏断开连接时保留现有显示屏。

枚举

"active"

"inactive"

Bounds

属性

  • 高度

    数值

    显示屏的高度（以像素为单位）。

  • 左侧

    数值

    左上角的 x 坐标。

  • 顶部

    数值

    左上角的 y 坐标。

  • width

    数值

    显示屏的宽度（以像素为单位）。

DisplayLayout

Chrome 53 及更高版本

属性

  • id

    字符串

    显示屏的唯一标识符。

  • offset

    数值

    显示屏沿连接边缘的偏移量。0 表示最上角或最左角对齐。

  • parentId

    字符串

    父级显示屏的唯一标识符。如果这是根目录，则为空。

  • position

    LayoutPosition

    此显示屏相对于父项的布局位置。系统会忽略根目录。

DisplayMode

Chrome 52 及更高版本

属性

  • deviceScaleFactor

    数值

    显示模式设备缩放比例。

  • 高度

    数值

    显示模式高度（以设备无关 [用户可见] 像素为单位）。

  • heightInNativePixels

    数值

    显示模式高度（以原生像素为单位）。

  • isInterlaced

    布尔值（可选）

    Chrome 74 及更高版本

    如果此模式为交错模式，则为 true；如果未提供，则为 false。

  • isNative

    布尔值

    如果模式是显示屏的原生模式，则为 true。

  • isSelected

    布尔值

    如果当前已选择该显示模式，则为 true。

  • refreshRate

    数值

    Chrome 67 及更高版本

    显示模式刷新率（以赫兹为单位）。

  • uiScale

    number 可选

    从 Chrome 70 开始已废弃

    使用 displayZoomFactor

    显示模式界面缩放比例。

  • width

    数值

    显示模式宽度（以设备无关 [用户可见] 像素为单位）。

  • widthInNativePixels

    数值

    显示模式宽度（以原生像素为单位）。

DisplayProperties

属性

  • boundsOriginX

    number 可选

    如果设置，则更新显示屏在 x 轴上的逻辑边界原点。与 boundsOriginY 一起应用。如果未设置且已设置 boundsOriginY，则默认为当前值。请注意，更新显示屏原点时，系统会应用一些约束条件，因此最终边界原点可能与所设置的原点不同。您可以使用 getInfo 检索最终边界。无法更改主显示屏上的边界原点。

  • boundsOriginY

    number 可选

    如果设置，则更新显示屏沿 y 轴的逻辑边界原点。请参阅 boundsOriginX 参数的文档。

  • displayMode

    DisplayMode（可选）

    Chrome 52 及更高版本

    如果设置，则将显示模式更新为与此值匹配的模式。如果其他参数无效，则不会应用此参数。如果显示模式无效，系统将不会应用该模式，并会设置错误，但仍会应用其他属性。

  • displayZoomFactor

    number 可选

    Chrome 65 版以上

    如果设置，则更新与显示屏关联的缩放比例。与仅按像素进行拉伸放大相比，此放大功能会执行重新布局和重新绘制，从而获得更高质量的放大效果。

  • isPrimary

    布尔值（可选）

    如果设置为 true，则将显示屏设为主显示屏。如果设为 false，则无操作。注意：如果设置，则显示屏会被视为所有其他属性的主要显示屏（即可以设置 isUnified，但可能无法设置边界原点）。

  • isUnified

    布尔值（可选）

    Chrome 59 及更高版本

    仅限 ChromeOS。如果设置为 true，则会将显示模式更改为统一桌面（如需了解详情，请参阅 enableUnifiedDesktop）。如果设为 false，则会停用统一桌面模式。此属性仅适用于主显示屏。如果提供，则不得提供 mirroringSourceId，系统会忽略其他属性。如果未提供，则不会产生任何影响。

  • mirroringSourceId

    字符串（选填）

    从 Chrome 68 开始已废弃

    使用 setMirrorMode。

    仅限 ChromeOS。如果已设置且不为空，则仅为此显示屏启用镜像。否则，会为所有显示屏停用镜像。此值应指明要镜像的源显示屏的 ID，该 ID 不得与传递给 setDisplayProperties 的 ID 相同。如果设置了此属性，则不得设置任何其他属性。

  • 过扫描

    边衬区 可选

    如果设置，则将显示屏的过扫边距设置为所提供的值。请注意，过扫值不得为负数，也不得大于屏幕尺寸的一半。无法在内部显示屏上更改过扫范围。

  • 旋转

    number 可选

    如果设置，则更新显示屏的旋转。有效值为 [0, 90, 180, 270]。旋转是相对于显示屏的垂直位置顺时针设置的。

DisplayUnitInfo

属性

  • activeState

    ActiveState

    Chrome 117 及更高版本

    如果系统检测到并使用显示屏，则为“有效”。

  • availableDisplayZoomFactors

    number[]

    Chrome 67 及更高版本

    可为显示屏设置的缩放比例值列表。

  • bounds

    边界

    显示屏的逻辑边界。

  • displayZoomFactor

    数值

    Chrome 65 版以上

    显示屏当前缩放比例与默认缩放比例之间的比率。例如，值 1 相当于 100% 缩放，值 1.5 相当于 150% 缩放。

  • dpiX

    数值

    x 轴上的每英寸像素数。

  • dpiY

    数值

    y 轴上的每英寸像素数。

  • edid

    Edid 可选

    Chrome 67 及更高版本

    注意：此功能仅适用于 ChromeOS 自助服务终端应用和 Web 界面。

  • hasTouchSupport

    布尔值

    Chrome 57 及更高版本

    如果此显示屏与触摸输入设备相关联，则为 true。

  • id

    字符串

    显示屏的唯一标识符。

  • isEnabled

    布尔值

    如果此显示屏处于启用状态，则为“true”。

  • isPrimary

    布尔值

    如果这是主显示屏，则为 true。

  • isUnified

    布尔值

    Chrome 59 及更高版本

    在统一桌面模式下，所有显示屏均为 true。请参阅 enableUnifiedDesktop 的文档。

  • mirroringDestinationIds

    字符串[]

    Chrome 64+

    仅限 ChromeOS。要将源显示屏镜像到的显示屏的标识符。如果没有任何显示屏处于镜像模式，则为空。此值将设为所有显示屏的相同值。此值不得包含 mirroringSourceId。

  • mirroringSourceId

    字符串

    仅限 ChromeOS。正在镜像的显示屏的标识符（如果已启用镜像），否则为空。系统会为所有显示屏（包括要镜像的显示屏）设置此值。

  • 模式

    DisplayMode[]

    Chrome 52 及更高版本

    可用显示模式的列表。当前模式将具有 isSelected=true。仅适用于 ChromeOS。在其他平台上将设置为空数组。

  • name

    字符串

    易于理解的名称（例如“HP 液晶显示器”）。

  • 过扫描

    边衬区

    显示屏在其屏幕边界内的内边距。目前仅在 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

    字符串（选填）

    镜像源显示屏的 ID。此值仅适用于“混合”。

  • 模式

    MirrorMode

    应设置的镜像模式。

Point

Chrome 57 及更高版本

属性

  • x

    数值

    点的 x 坐标。

  • y

    数值

    点的 y 坐标。

TouchCalibrationPair

Chrome 57 及更高版本

属性

  • displayPoint

    点

    显示点的坐标。

  • touchPoint

    点

    与显示点对应的触摸点的坐标。

TouchCalibrationPairQuad

Chrome 57 及更高版本

属性

方法

clearTouchCalibration()

Chrome 57 及更高版本 
chrome.system.display.clearTouchCalibration(
  id: string,
)

清除与显示屏关联的所有触摸校准数据，从而重置显示屏的触摸校准并将其恢复为默认状态。

参数

  • id

    字符串

    显示屏的唯一标识符。

completeCustomTouchCalibration()

Chrome 57 及更高版本 
chrome.system.display.completeCustomTouchCalibration(
  pairs: TouchCalibrationPairQuad,
  bounds: Bounds,
)

设置显示屏的触摸校准对。这些 pairs 将用于对触摸屏进行校准，以便在 startCustomTouchCalibration() 中调用 id 进行显示。请务必先调用 startCustomTouchCalibration，然后再调用此方法。如果另一个触摸校准正在进行，则会抛出错误。

参数

  • 用于校准显示屏的点对。

  • bounds

    边界

    执行触摸校准时显示屏的边界。系统会忽略 bounds.left 和 bounds.top 值。

enableUnifiedDesktop()

Chrome 46 及更高版本 
chrome.system.display.enableUnifiedDesktop(
  enabled: boolean,
)

启用/停用统一桌面功能。如果在镜像处于启用状态时启用，则桌面模式在镜像关闭之前不会发生变化。否则，桌面模式将立即切换为统一模式。注意：此功能仅适用于 ChromeOS 自助服务终端应用和 Web 界面。

参数

  • 已启用

    布尔值

    如果应启用统一桌面，则为 True。

getDisplayLayout()

Promise Chrome 53 及更高版本 
chrome.system.display.getDisplayLayout(
  callback?: function,
)

请求所有显示屏的布局信息。注意：此功能仅适用于 ChromeOS 自助服务终端应用和 Web 界面。

参数

返回

  • Promise<DisplayLayout[]>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getInfo()

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

请求所有已连接显示设备的信息。

参数

  • flags

    GetInfoFlags（可选）

    Chrome 59 及更高版本

    影响信息返回方式的选项。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (displayInfo: DisplayUnitInfo[]) => void

返回

  • Promise<DisplayUnitInfo[]>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

overscanCalibrationAdjust()

Chrome 53 及更高版本 
chrome.system.display.overscanCalibrationAdjust(
  id: string,
  delta: Insets,
)

调整显示屏的当前过扫边距。通常，这应该是沿轴移动显示屏（例如，left+right 具有相同的值），或者沿轴缩放显示屏（例如，top+bottom 具有相反的值）。每次调用 Adjust 都会与自开始以来的所有先前调用累加。

参数

  • id

    字符串

    显示屏的唯一标识符。

  • delta

    边衬区

    用于更改过扫边距的量。

overscanCalibrationComplete()

Chrome 53 及更高版本 
chrome.system.display.overscanCalibrationComplete(
  id: string,
)

保存当前值并隐藏叠加层，以完成显示屏的过扫调整。

参数

  • id

    字符串

    显示屏的唯一标识符。

overscanCalibrationReset()

Chrome 53 及更高版本 
chrome.system.display.overscanCalibrationReset(
  id: string,
)

将显示屏的过扫边距重置为上次保存的值（即在调用 Start 之前）。

参数

  • id

    字符串

    显示屏的唯一标识符。

overscanCalibrationStart()

Chrome 53 及更高版本 
chrome.system.display.overscanCalibrationStart(
  id: string,
)

开始对显示屏进行过扫校准。这会在屏幕上显示一个叠加层，指示当前的过扫边距。如果显示屏 id 的过扫校准正在进行，此操作将重置校准。

参数

  • id

    字符串

    显示屏的唯一标识符。

setDisplayLayout()

Promise Chrome 53 及更高版本 
chrome.system.display.setDisplayLayout(
  layouts: DisplayLayout[],
  callback?: function,
)

为所有显示屏设置布局。未包含的任何显示屏都将使用默认布局。如果布局会重叠或以其他方式无效，系统会将其调整为有效的布局。解析布局后，系统会触发 onDisplayChanged 事件。注意：此功能仅适用于 ChromeOS 自助服务终端应用和 Web 界面。

参数

  • layouts

    DisplayLayout[]

    布局信息，主显示屏除外，所有显示屏都需要此信息。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setDisplayProperties()

prometido 
chrome.system.display.setDisplayProperties(
  id: string,
  info: DisplayProperties,
  callback?: function,
)

根据 info 中提供的信息更新 id 指定的显示屏的属性。如果失败，系统会设置 runtime.lastError。注意：此功能仅适用于 ChromeOS 自助服务终端应用和 Web 界面。

参数

  • id

    字符串

    显示屏的唯一标识符。

  • 有关应更改的显示属性的信息。只有在 info 中为属性指定了新值时，系统才会更改该属性。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setMirrorMode()

Promise Chrome 65 及更高版本 
chrome.system.display.setMirrorMode(
  info: MirrorModeInfo,
  callback?: function,
)

将显示模式设置为指定的镜像模式。每次调用都会重置之前调用的状态。调用 setDisplayProperties() 将会针对镜像目标显示屏失败。注意：此功能仅适用于 ChromeOS 自助服务终端应用和 Web 界面。

参数

  • 应应用于显示模式的镜像模式的信息。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

showNativeTouchCalibration()

Promise Chrome 57 及更高版本 
chrome.system.display.showNativeTouchCalibration(
  id: string,
  callback?: function,
)

显示屏幕的原生触摸校准界面，其中 id 为显示屏 ID。系统会在屏幕上显示叠加层，其中包含有关如何继续操作的必要说明。只有在成功校准后，系统才会调用回调。如果校准失败，则会抛出错误。

参数

  • id

    字符串

    显示屏的唯一标识符。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise<boolean>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

startCustomTouchCalibration()

Chrome 57 及更高版本 
chrome.system.display.startCustomTouchCalibration(
  id: string,
)

为显示屏启动自定义触摸校准。使用自定义用户体验收集校准数据时，应调用此方法。如果另一个触摸校准正在进行，则会抛出错误。

参数

  • id

    字符串

    显示屏的唯一标识符。

事件

onDisplayChanged

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

当显示配置发生任何更改时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    () => void