chrome.system.display

说明

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

权限

system.display

类型

ActiveState

Chrome 117 及更高版本

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

枚举

"有效"

“无效”

Bounds

属性

  • 高度

    number

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

  • 左侧

    number

    左上角的 x 坐标。

  • 顶部

    number

    左上角的 y 坐标。

  • width

    number

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

DisplayLayout

Chrome 53 及更高版本

属性

  • id

    字符串

    显示屏的唯一标识符。

  • offset

    number

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

  • parentId

    字符串

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

  • position

    LayoutPosition

    此显示屏相对于父级的布局位置。对于根目录，将忽略此属性。

DisplayMode

Chrome 52 及更高版本

属性

  • deviceScaleFactor

    number

    显示模式设备缩放比例。

  • 高度

    number

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

  • heightInNativePixels

    number

    显示模式高度（以原生像素表示）。

  • isInterlaced

    布尔值（可选）

    Chrome 74 及更高版本

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

  • isNative

    布尔值

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

  • isSelected

    布尔值

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

  • refreshRate

    number

    Chrome 67 及更高版本

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

  • uiScale

    编号（选填）

    <ph type="x-smartling-placeholder"></ph> 自 Chrome 70 起弃用

    使用 displayZoomFactor

    显示模式界面缩放比例。

  • width

    number

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

  • widthInNativePixels

    number

    显示模式宽度（以原生像素表示）。

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

    字符串（可选）

    <ph type="x-smartling-placeholder"></ph> 自 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 及更高版本

    注意：此功能仅适用于 Chrome 操作系统的自助服务终端应用和网页界面。

  • 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

    字符串

    简单易懂的名称（例如“惠普 LCD 显示器”）。

  • 过扫描

    边衬区

    屏幕的边衬区屏幕的边界内。目前仅在 ChromeOS 上可用。在其他平台上将设为空边衬区。

  • 轮播

    number

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

  • workArea

    边界

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

Edid

Chrome 67 及更高版本

属性

  • manufacturerId

    字符串

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

  • productId

    字符串

    由制造商分配的 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 及更高版本

布局位置，即显示屏附加到的父级的边缘。

枚举

"top"

"right"

"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

    字符串

    显示屏的唯一标识符。

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,
)

启用/停用统一桌面功能。如果在镜像启用时启用，则在镜像关闭之前，桌面模式将不会发生变化。否则，桌面模式将立即切换到统一模式。注意：此功能仅适用于 Chrome 操作系统的自助服务终端应用和网页界面。

参数

  • 已启用

    布尔值

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

getDisplayLayout()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 53 及更高版本 
chrome.system.display.getDisplayLayout(
  callback?: function,
)

请求所有屏幕的布局信息。注意：此功能仅适用于 Chrome 操作系统的自助服务终端应用和网页界面。

参数

返回

  • Promise&lt;DisplayLayout[]&gt;

    Chrome 91 及更高版本

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

getInfo()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.system.display.getInfo(
  flags?: GetInfoFlags,
  callback?: function,
)

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

参数

  • flags

    GetInfoFlags（可选）

    Chrome 59 及更高版本

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (displayInfo: DisplayUnitInfo[]) => void

返回

  • Promise&lt;DisplayUnitInfo[]&gt;

    Chrome 91 及更高版本

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

overscanCalibrationAdjust()

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

调整显示屏的当前过扫描边衬区。通常情况下，这应沿着轴移动显示屏（例如，“向左+向右”的值相同）或沿轴缩放（例如，“顶部+底部”的值相反）。每次 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()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 53 及更高版本 
chrome.system.display.setDisplayLayout(
  layouts: DisplayLayout[],
  callback?: function,
)

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

参数

  • 布局

    DisplayLayout[]

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

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

setDisplayProperties()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.system.display.setDisplayProperties(
  id: string,
  info: DisplayProperties,
  callback?: function,
)

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

参数

  • id

    字符串

    显示屏的唯一标识符。

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

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

setMirrorMode()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 65 及更高版本 
chrome.system.display.setMirrorMode(
  info: MirrorModeInfo,
  callback?: function,
)

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

参数

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

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

showNativeTouchCalibration()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 57 及更高版本 
chrome.system.display.showNativeTouchCalibration(
  id: string,
  callback?: function,
)

显示屏幕的原生触摸校准用户体验，其中 id 作为屏幕 ID。屏幕上会显示一个叠加层，其中包含有关如何继续操作的必要说明。仅当校准成功时才会调用回调。如果校准失败，则会抛出错误。

参数

  • id

    字符串

    显示屏的唯一标识符。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (success: boolean) => void

    • 成功

      布尔值

返回

  • Promise&lt;boolean&gt;

    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