browser.system.display

说明

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

权限

system.display

类型

ActiveState

Chrome 117+ browser.*（自 Chrome 148 起）

一个枚举，用于指示系统是否检测到并使用显示屏。如果系统未检测到显示屏（可能已断开连接，或因处于睡眠模式等而被视为已断开连接），则该显示屏会被视为“处于非活动状态”。例如，当所有显示屏都断开连接时，此状态用于保留现有显示屏。

枚举

"active"

"inactive"

Bounds

属性

• 高度

  数值

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

• 向左

  数值

  左上角的 x 坐标。

• 顶部

  数值

  左上角的 y 坐标。

• width

  数值

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

DisplayLayout

Chrome 53 及更高版本 browser.*（自 Chrome 148 起）

属性

• id

  字符串

  显示屏的唯一标识符。

• offset

  数值

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

• parentId

  字符串

  父级展示广告的唯一标识符。如果这是根，则为空。

• position

  LayoutPosition

  此显示屏相对于父级显示屏的布局位置。对于根，此字段将被忽略。

DisplayMode

Chrome 52 及更高版本 browser.*（自 Chrome 148 起）

属性

• deviceScaleFactor

  数值

  显示模式设备缩放比例。

• 高度

  数值

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

• heightInNativePixels

  数值

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

• isInterlaced

  布尔值 （可选）

  Chrome 74 及更高版本 browser.*（自 Chrome 148 起）

  如果此模式为隔行扫描，则为 true；如果未提供，则为 false。

• isNative

  布尔值

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

• isSelected

  布尔值

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

• refreshRate

  数值

  Chrome 67 及更高版本 browser.*（自 Chrome 148 起）

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

• uiScale

  number 可选

  自 Chrome 70 起已弃用

  使用 displayZoomFactor

  显示模式界面缩放比例。

• width

  数值

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

• widthInNativePixels

  数值

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

DisplayProperties

属性

• boundsOriginX

  number 可选

  如果设置，则会沿 X 轴更新显示屏的逻辑边界原点。与 boundsOriginY 一起应用。如果未设置此值，但设置了 boundsOriginY，则默认采用当前值。请注意，更新显示原点时，系统会应用一些限制，因此最终的边界原点可能与设置的原点不同。您可以使用 getInfo 检索最终边界。无法在主显示屏上更改边界原点。

• boundsOriginY

  number 可选

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

• displayMode

  DisplayMode 可选

  Chrome 52 及更高版本 browser.*（自 Chrome 148 起）

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

• displayZoomFactor

  number 可选

  Chrome 65 及更高版本 自 Chrome 148 起为 browser.*

  如果设置了此参数，则会更新与显示屏关联的缩放比例。这种缩放会执行重新布局和重新绘制，因此与仅执行逐像素拉伸放大相比，缩放质量更高。

• isPrimary

  布尔值 （可选）

  如果设为 true，则将显示屏设为主显示屏。如果设置为 false，则不执行任何操作。注意：如果设置了此属性，则对于所有其他属性，该显示屏会被视为主显示屏（即，可以设置 isUnified，但不能设置边界原点）。

• isUnified

  布尔值 （可选）

  Chrome 59 及更高版本 自 Chrome 148 起为 browser.*

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

• mirroringSourceId

  字符串 可选

  自 Chrome 68 起已弃用

  使用 setMirrorMode。

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

• 过扫描

  边衬区 （可选）

  如果设置，则会将显示屏的过扫描边衬区设置为提供的值。请注意，每个过扫描边衬区不得为负值，也不得大于屏幕尺寸的四分之一。无法在内部显示器上更改过扫描。

• 旋转

  number 可选

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

DisplayUnitInfo

属性

• activeState

  ActiveState

  Chrome 117+ browser.*（自 Chrome 148 起）

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

• availableDisplayZoomFactors

  number[]

  Chrome 67 及更高版本 browser.*（自 Chrome 148 起）

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

• bounds

  边界

  显示屏的逻辑边界。

• displayZoomFactor

  数值

  Chrome 65 及更高版本 自 Chrome 148 起为 browser.*

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

• dpiX

  数值

  沿 x 轴每英寸的像素数。

• dpiY

  数值

  沿 y 轴方向每英寸的像素数。

• edid

  Edid 可选

  Chrome 67 及更高版本 browser.*（自 Chrome 148 起）

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

• hasTouchSupport

  布尔值

  Chrome 57 及更高版本 browser.*（自 Chrome 148 起）

  如果此显示屏有关联的触控输入设备，则为 True。

• id

  字符串

  显示屏的唯一标识符。

• isEnabled

  布尔值

  如果此显示屏已启用，则为 True。

• isPrimary

  布尔值

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

• isUnified

  布尔值

  Chrome 59 及更高版本 自 Chrome 148 起为 browser.*

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

• mirroringDestinationIds

  字符串[]

  Chrome 64 及更高版本 browser.*（自 Chrome 148 起）

  仅限 ChromeOS。源显示屏镜像到的显示屏的标识符。如果未镜像任何显示屏，则为空。所有屏幕的此设置值都相同。此设置不得包含 mirroringSourceId。

• mirroringSourceId

  字符串

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

• 模式

  DisplayMode[]

  Chrome 52 及更高版本 browser.*（自 Chrome 148 起）

  可用显示模式的列表。当前模式的 isSelected 值为 true。仅适用于 ChromeOS。在其他平台上，此属性将设置为空数组。

• name

  字符串

  人性化名称（例如“HP LCD 显示器”）。

• 过扫描

  边衬区

  显示屏在其屏幕边界内的边衬区。目前仅在 ChromeOS 上公开。在其他平台上，此属性将设置为空边衬区。

• 旋转

  数值

  显示屏相对于垂直位置顺时针旋转的角度。目前仅在 ChromeOS 上公开。在其他平台上，此值将设为 0。当设备处于实体平板电脑状态时，值 -1 将被解读为自动旋转。

• workArea

  边界

  显示边界内显示屏的可用工作区。工作区不包括为操作系统预留的显示区域，例如任务栏和启动器。

Edid

Chrome 67 及更高版本 browser.*（自 Chrome 148 起）

属性

• 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 及更高版本 自 Chrome 148 起为 browser.*

属性

• singleUnified

  布尔值 （可选）

  如果设为 true，则在统一桌面模式下，getInfo 只会返回一个 DisplayUnitInfo（请参阅 enableUnifiedDesktop）。默认值为 false。

Insets

属性

• 底部

  数值

  与底边界的 y 轴距离。

• 向左

  数值

  与左边界的 x 轴距离。

• 向右

  数值

  与右边界的 x 轴距离。

• 顶部

  数值

  与上边界的 y 轴距离。

LayoutPosition

Chrome 53 及更高版本 browser.*（自 Chrome 148 起）

布局位置，即显示屏所连接的父级边缘。

枚举

"top"

"right"

"bottom"

"left"

MirrorMode

Chrome 65 及更高版本 自 Chrome 148 起为 browser.*

镜像模式，即显示屏镜像到其他显示屏的不同方式。

枚举

“off”
指定默认模式（扩展桌面或统一桌面）。

“normal”
指定将默认源显示屏镜像到所有其他显示屏。

"mixed"
指定将指定的源显示屏镜像到提供的目标显示屏。所有其他已连接的显示屏都将扩展。

MirrorModeInfo

Chrome 65 及更高版本 自 Chrome 148 起为 browser.*

属性

• mirroringDestinationIds

  string[] 可选

  镜像目标显示屏的 ID。此设置仅对“混合”有效。

• mirroringSourceId

  字符串 可选

  镜像源显示屏的 ID。此设置仅对“混合”有效。

• 模式

  MirrorMode

  应设置的镜像模式。

Point

Chrome 57 及更高版本 browser.*（自 Chrome 148 起）

属性

• x

  数值

  点的 X 坐标。

• y

  数值

  点的 y 坐标。

TouchCalibrationPair

Chrome 57 及更高版本 browser.*（自 Chrome 148 起）

属性

• displayPoint

  Point

  显示点的坐标。

• touchPoint

  Point

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

TouchCalibrationPairQuad

Chrome 57 及更高版本 browser.*（自 Chrome 148 起）

属性

• pair1

  TouchCalibrationPair

  需要第一对触摸点和显示点才能进行触摸校准。

• pair2

  TouchCalibrationPair

  需要第二对触摸点和显示点才能进行触摸校准。

• pair3

  TouchCalibrationPair

  需要第三对触摸点和显示点才能进行触摸校准。

• pair4

  TouchCalibrationPair

  触控校准所需的第四对触控点和显示点。

方法

clearTouchCalibration()

Chrome 57 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.clearTouchCalibration(
  id: string,
): void

注意：此功能仅适用于 ChromeOS 自助服务终端应用。重置显示屏的触控校准，并通过清除与显示屏关联的所有触控校准数据，使其恢复到默认状态。

参数

• id

  字符串

  显示屏的唯一标识符。

completeCustomTouchCalibration()

Chrome 57 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.completeCustomTouchCalibration(
  pairs: TouchCalibrationPairQuad,
  bounds: Bounds,
): void

注意：此功能仅适用于 ChromeOS 自助服务终端应用。为显示屏设置触控校准对。这些 pairs 将用于校准在 startCustomTouchCalibration() 中调用的 id 的触摸屏。请务必在调用此方法之前调用 startCustomTouchCalibration。如果另一项触控校准已在进行中，则会抛出错误。

参数

• 双

  TouchCalibrationPairQuad

  用于校准显示屏的点对。

• bounds

  边界

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

enableUnifiedDesktop()

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.enableUnifiedDesktop(
  enabled: boolean,
): void

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

参数

• 已启用

  布尔值

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

getDisplayLayout()

Chrome 53 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.getDisplayLayout(): Promise<DisplayLayout[]>

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

返回

• Promise<DisplayLayout[]>

  Chrome 91 及更高版本 browser.*（自 Chrome 148 起）

  使用结果进行解析的 Promise。

getInfo()

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

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

参数

• flags

  GetInfoFlags 可选

  Chrome 59 及更高版本 自 Chrome 148 起为 browser.*

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

返回

• Promise<DisplayUnitInfo[]>

  Chrome 91 及更高版本 browser.*（自 Chrome 148 起）

  使用结果进行解析的 Promise。

overscanCalibrationAdjust()

Chrome 53 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.overscanCalibrationAdjust(
  id: string,
  delta: Insets,
): void

注意：此功能仅适用于 ChromeOS 自助服务终端应用。调整显示屏的当前过扫描边衬区。通常，这应该会使显示屏沿某个轴移动（例如，左侧和右侧具有相同的值）或沿某个轴缩放（例如，顶部和底部具有相反的值）。每次 Adjust 调用都会与自 Start 以来之前的调用累积。

参数

• id

  字符串

  显示屏的唯一标识符。

• delta

  边衬区

  要更改过扫描边衬区的量。

overscanCalibrationComplete()

Chrome 53 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.overscanCalibrationComplete(
  id: string,
): void

注意：此功能仅适用于 ChromeOS 自助服务终端应用。通过保存当前值并隐藏叠加层，完成显示屏的过扫描调整。

参数

• id

  字符串

  显示屏的唯一标识符。

overscanCalibrationReset()

Chrome 53 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.overscanCalibrationReset(
  id: string,
): void

注意：此功能仅适用于 ChromeOS 自助服务终端应用。将显示屏的过扫描边衬区重置为上次保存的值（即调用 Start 之前的值）。

参数

• id

  字符串

  显示屏的唯一标识符。

overscanCalibrationStart()

Chrome 53 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.overscanCalibrationStart(
  id: string,
): void

注意：此功能仅适用于 ChromeOS 自助服务终端应用。启动显示屏的过扫描校准。这会在屏幕上显示一个叠加层，指示当前的过扫描边衬区。如果显示屏 id 的过扫描校准正在进行中，此操作将重置校准。

参数

• id

  字符串

  显示屏的唯一标识符。

setDisplayLayout()

Chrome 53 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.setDisplayLayout(
  layouts: DisplayLayout[],
): Promise<void>

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

参数

• 布局

  DisplayLayout[]

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

返回

• 承诺<void>

  Chrome 91 及更高版本 browser.*（自 Chrome 148 起）

  在函数完成时解析的 Promise。

setDisplayProperties()

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

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

参数

• id

  字符串

  显示屏的唯一标识符。

• 信息

  DisplayProperties

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

返回

• 承诺<void>

  Chrome 91 及更高版本 browser.*（自 Chrome 148 起）

  在函数完成时解析的 Promise。

setMirrorMode()

Chrome 65 及更高版本 自 Chrome 148 起为 browser.*

browser.system.display.setMirrorMode(
  info: MirrorModeInfo,
): Promise<void>

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

参数

• 信息

  MirrorModeInfo

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

返回

• 承诺<void>

  Chrome 91 及更高版本 browser.*（自 Chrome 148 起）

  在函数完成时解析的 Promise。

showNativeTouchCalibration()

Chrome 57 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.showNativeTouchCalibration(
  id: string,
): Promise<boolean>

注意：此功能仅适用于 ChromeOS 自助服务终端应用。显示显示屏 ID 为 id 的显示屏的原生触摸校准用户体验。此时，屏幕上会显示一个叠加层，其中包含有关如何继续操作的必要说明。仅当校准成功时，系统才会调用该回调。如果校准失败，则会抛出错误。

参数

• id

  字符串

  显示屏的唯一标识符。

返回

• Promise<boolean>

  Chrome 91 及更高版本 browser.*（自 Chrome 148 起）

  Promise，其解析结果会告知调用方触摸校准已结束。布尔值会告知校准是否成功。

startCustomTouchCalibration()

Chrome 57 及更高版本 browser.*（自 Chrome 148 起）

browser.system.display.startCustomTouchCalibration(
  id: string,
): void

注意：此功能仅适用于 ChromeOS 自助服务终端应用。为显示屏启动自定义触控校准。使用自定义用户体验收集校准数据时，应调用此方法。如果另一项触控校准已在进行中，则会抛出错误。

参数

• id

  字符串

  显示屏的唯一标识符。

事件

onDisplayChanged

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

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

参数

• callback

  函数

  callback 参数如下所示：

  () => void