chrome.system.display

说明

使用 system.display API 查询屏幕元数据。

权限

system.display

类型

ActiveState

Chrome 117 及更高版本

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

枚举

Bounds

属性

  • 高度

    number

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

  • 左

    number

    左上角的 x 坐标。

  • 上

    number

    左上角的 y 坐标。

  • 宽度

    number

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

DisplayLayout

Chrome 53 及更高版本

属性

  • id

    string

    显示屏的唯一标识符。

  • offset

    number

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

  • parentId

    string

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

  • 此屏幕相对于父视图的布局位置。对于根，系统会忽略此属性。

DisplayMode

Chrome 52 及更高版本

属性

  • deviceScaleFactor

    number

    显示模式设备缩放比例。

  • 高度

    number

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

  • heightInNativePixels

    number

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

  • isInterlaced

    布尔值 选填

    Chrome 74 及更高版本

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

  • isNative

    boolean

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

  • isSelected

    boolean

    如果当前选择了显示模式，则为“true”。

  • refreshRate

    number

    Chrome 67 及更高版本

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

  • uiScale

    数字可选

    从 Chrome 70 开始已弃用

    使用 displayZoomFactor

    显示模式界面缩放比例。

  • 宽度

    number

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

  • widthInNativePixels

    number

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

DisplayProperties

属性

  • boundsOriginX

    数字可选

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

  • boundsOriginY

    数字可选

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

  • displayMode

    DisplayMode（可选）

    Chrome 52 及更高版本

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

  • displayZoomFactor

    数字可选

    Chrome 65 及更高版本

    如果设置了此字段，则会更新与显示内容相关联的缩放。这种缩放会执行重新布局和重新绘制，因此与仅执行 1 个像素的拉伸放大相比，这种缩放效果会更好。

  • isPrimary

    布尔值 选填

    如果设置为 true，则将显示屏设为主要显示屏。如果设为 false，则不执行任何操作。注意：如果设置了此属性，显示屏将被视为所有其他属性的主显示内容（例如，可以设置 isUnified，但不能设置边界出发地）。

  • isUnified

    布尔值 选填

    Chrome 59 及更高版本

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

  • mirroringSourceId

    字符串（可选）

    从 Chrome 68 开始已废弃

    使用 setMirrorMode。

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

  • 过扫描

    边衬区（可选）

    如果设置了此字段，则会将显示屏的过扫描边衬区设置为提供的值。请注意，过扫描值不能为负数，也不能大于屏幕大小的一半。无法在内部显示器上更改过扫描。

  • 旋转

    数字可选

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

DisplayUnitInfo

属性

  • activeState

    ActiveState

    Chrome 117 及更高版本

    如果系统检测到并使用显示屏，则为活跃状态。

  • availableDisplayZoomFactors

    数值 []

    Chrome 67 及更高版本

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

  • bounds

    边界

    显示屏的逻辑边界。

  • displayZoomFactor

    number

    Chrome 65 及更高版本

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

  • dpiX

    number

    沿 x 轴的每英寸像素数。

  • dpiY

    number

    沿 y 轴的每英寸像素数。

  • EDID

    Edid（可选）

    Chrome 67 及更高版本

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

  • hasTouchSupport

    boolean

    Chrome 57 及更高版本

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

  • id

    string

    显示屏的唯一标识符。

  • isEnabled

    boolean

    如果启用此显示屏，则为“true”。

  • isPrimary

    boolean

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

  • isUnified

    boolean

    Chrome 59 及更高版本

    在统一桌面模式下，适用于所有显示屏。请参阅 enableUnifiedDesktop 的文档。

  • mirroringDestinationIds

    字符串[]

    Chrome 64 及更高版本

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

  • mirroringSourceId

    string

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

  • modes

    DisplayMode[]

    Chrome 52 及更高版本

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

  • name

    string

    直观易懂的名称（例如“HP LCD 显示器”）。

  • 过扫描

    边衬区

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

  • 旋转

    number

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

  • workArea

    边界

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

Edid

Chrome 67 及更高版本

属性

  • manufacturerId

    string

    制造商代码由 3 个字符组成。请参阅第 3.4.1 节第 21 页。在 v1.4 中是必需的。

  • productId

    string

    2 字节制造商指定的代码，第 3.4.2 节，第 21 页。在 v1.4 中是必需的。

  • yearOfManufacture

    number

    制造商年份，第 3.4.4 页，第 22 页。在 v1.4 中是必需的。

GetInfoFlags

Chrome 59 及更高版本

属性

Insets

属性

  • 下

    number

    Y 轴与底部边界的距离。

  • 左

    number

    x 轴到左侧边界的距离。

  • 右

    number

    x 轴到右侧边界的距离。

  • 上

    number

    Y 轴上边界的距离。

LayoutPosition

Chrome 53 及更高版本

布局位置，即显示屏连接到的父视图的边缘。

枚举

"bottom"

MirrorMode

Chrome 65 及更高版本

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

枚举

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

"normal"
指定将默认源屏幕镜像到所有其他屏幕。

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

MirrorModeInfo

Chrome 65 及更高版本

属性

  • mirroringDestinationIds

    string[] 可选

    系统会显示镜像目的地的 ID。这仅适用于“混合”。

  • mirroringSourceId

    字符串（可选）

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

  • 模式

    MirrorMode

    应设置的镜像模式。

Point

Chrome 57 及更高版本

属性

  • x

    number

    点的 x 坐标。

  • y

    number

    点的 y 坐标。

TouchCalibrationPair

Chrome 57 及更高版本

属性

  • displayPoint

    点

    显示点的坐标。

  • touchPoint

    点

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

TouchCalibrationPairQuad

Chrome 57 及更高版本

属性

方法

clearTouchCalibration()

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

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

参数

  • id

    string

    显示屏的唯一标识符。

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 自助服务终端应用和网页界面。

参数

  • 已启用

    boolean

    如果应启用统一桌面，则为“true”。

getDisplayLayout()

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

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

参数

返回

  • Promise<DisplayLayout[]>

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getInfo()

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

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

参数

  • flags

    GetInfoFlags 可选

    Chrome 59 及更高版本

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

  • callback

    函数（可选）

    callback 参数如下所示：

    (displayInfo: DisplayUnitInfo[])=>void

返回

  • Promise<DisplayUnitInfo[]>

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

overscanCalibrationAdjust()

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

调整显示屏的当前过扫描边衬区。通常，此操作应沿轴移动显示内容（例如，左右值相同）或沿轴缩放（例如，顶部+底部具有相反的值）。每个 Adjust 调用都会累计自 Start 以来的调用。

参数

  • id

    string

    显示屏的唯一标识符。

  • delta

    边衬区

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

overscanCalibrationComplete()

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

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

参数

  • id

    string

    显示屏的唯一标识符。

overscanCalibrationReset()

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

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

参数

  • id

    string

    显示屏的唯一标识符。

overscanCalibrationStart()

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

启动显示屏的过扫描校准。这将在屏幕上显示叠加层，指示当前的过扫描边衬区。如果正在进行显示屏 id 的过扫描校准，则会重置校准。

参数

  • id

    string

    显示屏的唯一标识符。

setDisplayLayout()

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

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

参数

  • 布局

    DisplayLayout[]

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

setDisplayProperties()

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

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

参数

  • id

    string

    显示屏的唯一标识符。

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

setMirrorMode()

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

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

参数

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

showNativeTouchCalibration()

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

显示显示屏的原生触摸校准用户体验，显示屏 ID 为 id。屏幕上会显示一个叠加层，说明如何继续操作。只有在校准成功的情况下才会调用此回调函数。如果校准失败，则会引发错误。

参数

  • id

    string

    显示屏的唯一标识符。

  • callback

    函数（可选）

    callback 参数如下所示：

    (success: boolean)=>void

    • 成功

      boolean

返回

  • Promise<boolean>

    Chrome 91 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

startCustomTouchCalibration()

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

开始为显示屏进行自定义触摸校准。在使用自定义用户体验收集校准数据时应调用此方法。如果正在进行其他触摸校准，则会引发错误。

参数

  • id

    string

    显示屏的唯一标识符。

活动

onDisplayChanged

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

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

参数

  • callback

    功能

    callback 参数如下所示：

    ()=>void