说明
使用 system.display API 查询展示元数据。
权限
system.display类型
ActiveState
一个枚举，用于指示显示屏是否被系统检测到并使用。如果显示屏未被系统检测到（可能已断开连接，或因休眠模式等原因而被视为已断开连接），则会被视为“不活跃”。此状态用于在所有显示屏断开连接时保留现有显示屏，例如。
枚举
“有效”
“inactive”
Bounds
属性
-
高度
数值
显示屏的高度（以像素为单位）。
-
向左
数值
左上角的 x 坐标。
-
顶部
数值
左上角的 y 坐标。
-
width
数值
显示屏的宽度（以像素为单位）。
DisplayLayout
属性
-
id
字符串
显示屏的唯一标识符。
-
offset
数值
显示屏沿连接边缘的偏移量。0 表示最上角或最左角对齐。
-
parentId
字符串
父显示屏的唯一标识符。如果这是根，则为空。
-
position
此显示相对于父级的布局位置。对于根，此属性将被忽略。
DisplayMode
属性
-
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，则不得提供 sourceId，并且系统会忽略其他属性。如果未提供，则不会产生任何影响。 -
mirroringSourceId
字符串（选填）
自 Chrome 68 起已弃用使用
setMirrorMode。仅限 ChromeOS。如果已设置且不为空，则仅为此显示屏启用镜像。否则，会针对所有显示屏停用镜像功能。此值应指明要镜像的源显示屏的 ID，不得与传递给 setDisplayProperties 的 ID 相同。如果设置了该属性，则不得设置任何其他属性。
-
过扫描
边衬区（可选）
如果设置，则将显示屏的过扫描边衬区设置为提供的值。请注意，过扫描值不得为负数，也不得大于屏幕尺寸的一半。无法在内置显示器上更改过扫描。
-
旋转
number 可选
如果已设置，则更新显示屏的旋转。合法值为 [0, 90, 180, 270]。旋转方向设置为顺时针，相对于显示屏的竖屏位置。
DisplayUnitInfo
属性
-
activeStateChrome 117 及更高版本
如果系统检测到显示屏并使用它，则为有效。
-
availableDisplayZoomFactors
number[]
Chrome 67 及更高版本可为显示屏设置的缩放比例值列表。
-
bounds
显示屏的逻辑边界。
-
displayZoomFactor
数值
Chrome 65 及更高版本显示屏的当前缩放比例与默认缩放比例之间的比率。例如，值 1 相当于 100% 缩放，值 1.5 相当于 150% 缩放。
-
dpiX
数值
沿 x 轴方向每英寸的像素数。
-
dpiY
数值
沿 y 轴方向每英寸的像素数。
-
edid
Edid 可选
Chrome 67 及更高版本注意：此功能仅适用于 ChromeOS Kiosk 应用和 Web 界面。
-
hasTouchSupport
布尔值
Chrome 57 及更高版本如果此显示屏关联了触摸输入设备，则为 True。
-
id
字符串
显示屏的唯一标识符。
-
isEnabled
布尔值
如果相应显示处于启用状态，则为 true。
-
isPrimary
布尔值
如果这是主显示屏，则为 True。
-
isUnified
布尔值
Chrome 59 及更高版本在统一桌面模式下，所有显示屏均为 true。请参阅
enableUnifiedDesktop的文档。 -
mirroringDestinationIds
字符串[]
Chrome 64+仅限 ChromeOS。来源显示屏所镜像到的显示屏的标识符。如果未镜像任何显示屏，则为空。所有显示屏的此属性都将设置为相同的值。不得包含
mirroringSourceId。 -
mirroringSourceId
字符串
仅限 ChromeOS。如果启用了镜像，则为正在镜像的显示屏的标识符；否则为空。此设置将应用于所有显示屏（包括正在镜像的显示屏）。
-
模式Chrome 52 及更高版本
可用显示模式的列表。当前模式的 isSelected 将为 true。仅适用于 ChromeOS。在其他平台上，此属性将设置为一个空数组。
-
name
字符串
易记名称（例如“HP LCD 显示器”）。
-
过扫描
显示屏在其屏幕边界内的边衬区。目前仅在 ChromeOS 上公开。在其他平台上将设置为空边衬区。
-
旋转
数值
显示屏相对于竖屏位置的顺时针旋转角度（以度为单位）。目前仅在 ChromeOS 上公开。在其他平台上将设置为 0。如果值为 -1，则表示当设备处于实体平板电脑状态时，自动旋转屏幕。
-
workArea
显示屏边界内的可用工作区。工作区不包括为操作系统预留的显示区域，例如任务栏和启动器。
Edid
属性
-
manufacturerId
字符串
3 字符制造商代码。请参阅第 3.4.1 节第 21 页。在 v1.4 中为必需。
-
productId
字符串
2 字节制造商分配的代码，第 3.4.2 节，第 21 页。在 v1.4 中为必需。
-
yearOfManufacture
数值
制造商年份，第 3.4.4 条，第 22 页。在 v1.4 中为必需。
GetInfoFlags
属性
-
singleUnified
布尔值（可选）
如果设置为 true，则在统一桌面模式下，
getInfo将仅返回一个DisplayUnitInfo（请参阅enableUnifiedDesktop）。默认值为 false。
Insets
属性
-
底部
数值
与底部边界的 y 轴距离。
-
向左
数值
与左边界的 x 轴距离。
-
向右
数值
与右边界的 x 轴距离。
-
顶部
数值
与顶部边界的 y 轴距离。
LayoutPosition
布局位置，即显示屏所连接到的父元素的边缘。
枚举
“顶部”
“右”
“底部”
“left”
MirrorMode
镜像模式，即显示屏镜像到其他显示屏的不同方式。
枚举
“关闭”
指定默认模式（扩展桌面或统一桌面）。
“normal”
指定默认来源显示将镜像到所有其他显示屏。
“混合”
指定将指定的来源显示屏镜像到所提供的目标显示屏。所有其他已连接的显示屏将显示扩展内容。
MirrorModeInfo
属性
-
mirroringDestinationIds
string[] 可选
镜像目标显示屏的 ID。此值仅适用于“混合”。
-
mirroringSourceId
字符串（选填）
镜像源显示屏的 ID。此值仅适用于“混合”。
-
模式
应设置的镜像模式。
Point
属性
-
x
数值
点的 x 坐标。
-
y
数值
点的 y 坐标。
TouchCalibrationPair
TouchCalibrationPairQuad
属性
-
pair1
触摸校准所需的第一对触摸点和显示点。
-
pair2
需要第二组触控和显示点才能进行触控校准。
-
pair3
触控校准需要第三组触控点和显示点。
-
pair4
触控校准需要第四组触控点和显示点。
方法
clearTouchCalibration()
chrome.system.display.clearTouchCalibration(
id: string,
): void
通过清除与显示屏关联的所有触控校准数据，重置显示屏的触控校准并将其恢复为默认状态。
参数
-
id
字符串
显示屏的唯一标识符。
completeCustomTouchCalibration()
chrome.system.display.completeCustomTouchCalibration(
pairs: TouchCalibrationPairQuad,
bounds: Bounds,
): void
为显示屏设置触控校准对。这些 pairs 将用于校准触摸屏，以在 startCustomTouchCalibration() 中调用 id 时进行显示。请务必在调用此方法之前调用 startCustomTouchCalibration。如果已在进行其他触控校准，则会抛出错误。
参数
-
pairs
用于校准显示屏的点对。
-
bounds
执行触控校准时的显示屏边界。系统会忽略
bounds.left和bounds.top值。
enableUnifiedDesktop()
chrome.system.display.enableUnifiedDesktop(
enabled: boolean,
): void
启用/停用统一桌面功能。如果在镜像处于有效状态时启用，桌面模式将不会更改，直到镜像关闭。否则，桌面模式将立即切换到统一模式。注意：此功能仅适用于 ChromeOS Kiosk 应用和 Web 界面。
参数
-
已启用
布尔值
如果应启用统一桌面，则为 True。
getDisplayLayout()
chrome.system.display.getDisplayLayout(): Promise<DisplayLayout[]>
请求所有显示屏的布局信息。注意：此功能仅适用于 ChromeOS Kiosk 应用和 Web 界面。
返回
-
Promise<DisplayLayout[]>
Chrome 91 及更高版本
getInfo()
chrome.system.display.getInfo(
flags?: GetInfoFlags,
): Promise<DisplayUnitInfo[]>
请求所有已连接的显示设备的信息。
参数
-
flags
GetInfoFlags 可选
Chrome 59 及更高版本影响信息返回方式的选项。
返回
-
Promise<DisplayUnitInfo[]>
Chrome 91 及更高版本
overscanCalibrationAdjust()
chrome.system.display.overscanCalibrationAdjust(
id: string,
delta: Insets,
): void
调整显示器的当前过扫描边衬区。通常，这应该会使显示沿某个轴移动（例如，左侧和右侧具有相同的值），或者沿某个轴缩放（例如，顶部和底部具有相反的值）。自开始以来，每次 Adjust 调用都会累积之前调用的结果。
参数
-
id
字符串
显示屏的唯一标识符。
-
delta
用于更改过扫描边衬区的量。
overscanCalibrationComplete()
chrome.system.display.overscanCalibrationComplete(
id: string,
): void
通过保存当前值并隐藏叠加层，完成显示屏的过扫描调整。
参数
-
id
字符串
显示屏的唯一标识符。
overscanCalibrationReset()
chrome.system.display.overscanCalibrationReset(
id: string,
): void
将显示屏的过扫描边衬区重置为上次保存的值（即在调用 Start 之前的值）。
参数
-
id
字符串
显示屏的唯一标识符。
overscanCalibrationStart()
chrome.system.display.overscanCalibrationStart(
id: string,
): void
为显示屏启动过扫描校准。这会在屏幕上显示一个叠加层，指示当前过扫描边衬区。如果显示屏 id 的过扫描校准正在进行，此方法将重置校准。
参数
-
id
字符串
显示屏的唯一标识符。
setDisplayLayout()
chrome.system.display.setDisplayLayout(
layouts: DisplayLayout[],
): Promise<void>
为所有显示屏设置布局。未包含的任何显示屏都将使用默认布局。如果布局会重叠或以其他方式无效，系统会将其调整为有效布局。布局解析完毕后，系统会触发 onDisplayChanged 事件。注意：此功能仅适用于 ChromeOS Kiosk 应用和 Web 界面。
参数
-
布局
布局信息，除主显示屏之外的所有显示屏都需要此信息。
返回
-
Promise<void>
Chrome 91 及更高版本
setDisplayProperties()
chrome.system.display.setDisplayProperties(
id: string,
info: DisplayProperties,
): Promise<void>
根据 info 中提供的信息，更新 id 指定的显示屏的属性。如果失败，系统会设置 runtime.lastError。注意：此功能仅适用于 ChromeOS Kiosk 应用和 Web 界面。
参数
-
id
字符串
显示屏的唯一标识符。
-
应更改的显示属性的相关信息。只有当
info中指定了属性的新值时，该属性才会发生变化。
返回
-
Promise<void>
Chrome 91 及更高版本
setMirrorMode()
chrome.system.display.setMirrorMode(
info: MirrorModeInfo,
): Promise<void>
将显示模式设置为指定的镜像模式。每次调用都会重置之前调用中的状态。对于镜像目标显示屏，调用 setDisplayProperties() 将会失败。注意：此功能仅适用于 ChromeOS Kiosk 应用和 Web 界面。
参数
-
应应用于显示模式的镜像模式信息。
返回
-
Promise<void>
Chrome 91 及更高版本
showNativeTouchCalibration()
chrome.system.display.showNativeTouchCalibration(
id: string,
): Promise<boolean>
显示以 id 为显示屏 ID 的显示屏的原生触控校准用户体验。屏幕上会显示一个叠加层，其中包含有关如何继续操作的必要说明。只有在校准成功时才会调用回调。如果校准失败，则会抛出错误。
参数
-
id
字符串
显示屏的唯一标识符。
返回
-
Promise<boolean>
Chrome 91 及更高版本
startCustomTouchCalibration()
chrome.system.display.startCustomTouchCalibration(
id: string,
): void
为显示屏启动自定义触控校准。当使用自定义用户体验来收集校准数据时，应调用此方法。如果已在进行其他触控校准，则会抛出错误。
参数
-
id
字符串
显示屏的唯一标识符。
事件
onDisplayChanged
chrome.system.display.onDisplayChanged.addListener(
callback: function,
)
当显示配置发生任何变化时触发。
参数
-
callback
函数
callback参数如下所示：() => void