说明
使用 system.display
API 查询展示元数据。
权限
system.display
类型
ActiveState
用于指示系统是否检测到和使用显示屏的枚举。如果系统未检测到显示屏(可能断开连接,或因睡眠模式等原因而被视为断开连接),则显示屏将被视为“非活动状态”。例如,此状态用于在所有显示屏断开连接时保留现有显示屏。
枚举
"有效"
“无效”
Bounds
属性
-
高度
number
显示屏的高度(以像素为单位)。
-
左侧
number
左上角的 x 坐标。
-
顶部
number
左上角的 y 坐标。
-
width
number
显示屏的宽度(以像素为单位)。
DisplayLayout
属性
-
id
字符串
显示屏的唯一标识符。
-
offset
number
显示屏沿连接边缘的偏移量。0 表示最顶部或最左边对齐。
-
parentId
字符串
父级显示屏的唯一标识符。如果这是根目录,则为空。
-
position
此显示屏相对于父级的布局位置。对于根目录,将忽略此属性。
DisplayMode
属性
-
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
属性
-
activeStateChrome 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。正在镜像的屏幕的标识符(如果已启用镜像),否则为空。这将为所有屏幕(包括正在镜像的屏幕)设置。
-
模式Chrome 52 及更高版本
可用显示模式的列表。当前模式会设为 isSelected=true。仅适用于 ChromeOS。在其他平台上将设置为空数组。
-
name
字符串
简单易懂的名称(例如“惠普 LCD 显示器”)。
-
过扫描
屏幕的边衬区屏幕的边界内。目前仅在 ChromeOS 上可用。在其他平台上将设为空边衬区。
-
轮播
number
显示屏相对于垂直位置顺时针旋转的角度(以度为单位)。目前仅在 ChromeOS 上可用。在其他平台上将设置为 0。当设备处于实体平板电脑状态时,值 -1 将被解读为自动屏幕旋转。
-
workArea
显示边界内的可用工作区。工作区不包括为操作系统预留的显示屏区域,例如任务栏和启动器。
Edid
属性
-
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
属性
-
singleUnified
布尔值(可选)
如果此政策设为 true,当处于统一桌面模式时,
getInfo
将仅返回单个DisplayUnitInfo
(请参阅enableUnifiedDesktop
)。默认值为 false。
Insets
属性
-
底部
number
y 轴与下边界的距离。
-
左侧
number
x 轴与左侧边界的距离。
-
右侧
number
x 轴与右侧边界的距离。
-
顶部
number
y 轴与上边界的距离。
LayoutPosition
布局位置,即显示屏附加到的父级的边缘。
枚举
"top"
"right"
"bottom"
“左”
MirrorMode
镜像模式,即显示屏以不同方式镜像到其他显示屏的方式。
枚举
"off"
指定默认模式(扩展桌面或统一桌面)。
"normal"
指定将默认源显示屏镜像到所有其他显示屏。
"mixed"
指定将指定的源屏幕镜像到提供的目标屏幕。所有其他连接的显示屏将会展开。
MirrorModeInfo
属性
-
mirroringDestinationIds
string[] 选填
系统会显示镜像目标的 ID。此字段仅对“混合”有效。
-
mirroringSourceId
字符串(可选)
镜像来源显示的 ID。此字段仅对“混合”有效。
-
模式
应设置的镜像模式。
Point
属性
-
x
number
点的 x 坐标。
-
y
number
点的 y 坐标。
TouchCalibrationPair
TouchCalibrationPairQuad
属性
-
pair1
进行触摸校准所需的第一对触摸点和显示点。
-
pair2
进行触摸校准所需的第二对触摸点和显示点。
-
pair3
进行触摸校准所需的第三对触摸点和显示点。
-
pair4
进行触摸校准所需的第四对触摸点和显示点。
方法
clearTouchCalibration()
chrome.system.display.clearTouchCalibration(
id: string,
)
通过清除与显示屏相关联的所有触摸校准数据,重置显示屏的触摸校准,并将其恢复为默认状态。
参数
-
id
字符串
显示屏的唯一标识符。
completeCustomTouchCalibration()
chrome.system.display.completeCustomTouchCalibration(
pairs: TouchCalibrationPairQuad,
bounds: Bounds,
)
设置显示屏的触摸校准对。这些 pairs
将用于通过在 startCustomTouchCalibration() 中调用 id
来校准要显示的触摸屏。始终在调用此方法之前调用 startCustomTouchCalibration
。如果已在进行另一触摸校准,则会引发错误。
参数
-
pairs
用于校准显示屏的点对。
-
bounds
执行触摸校准时的显示屏边界。系统会忽略
bounds.left
和bounds.top
值。
enableUnifiedDesktop()
chrome.system.display.enableUnifiedDesktop(
enabled: boolean,
)
启用/停用统一桌面功能。如果在镜像启用时启用,则在镜像关闭之前,桌面模式将不会发生变化。否则,桌面模式将立即切换到统一模式。注意:此功能仅适用于 Chrome 操作系统的自助服务终端应用和网页界面。
参数
-
已启用
布尔值
如果应启用统一桌面,则为“true”。
getDisplayLayout()
chrome.system.display.getDisplayLayout(
callback?: function,
)
请求所有屏幕的布局信息。注意:此功能仅适用于 Chrome 操作系统的自助服务终端应用和网页界面。
参数
-
callback
函数(可选)
callback
参数如下所示:(layouts: DisplayLayout[]) => void
-
布局
-
返回
-
Promise<DisplayLayout[]>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getInfo()
chrome.system.display.getInfo(
flags?: GetInfoFlags,
callback?: function,
)
请求所有连接的显示设备的信息。
参数
-
flags
GetInfoFlags(可选)
Chrome 59 及更高版本影响信息返回方式的选项。
-
callback
函数(可选)
callback
参数如下所示:(displayInfo: DisplayUnitInfo[]) => void
-
displayInfo
-
返回
-
Promise<DisplayUnitInfo[]>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
overscanCalibrationAdjust()
chrome.system.display.overscanCalibrationAdjust(
id: string,
delta: Insets,
)
调整显示屏的当前过扫描边衬区。通常情况下,这应沿着轴移动显示屏(例如,“向左+向右”的值相同)或沿轴缩放(例如,“顶部+底部”的值相反)。每次 Adjust 调用都会累计自开始以来之前的通话。
参数
-
id
字符串
显示屏的唯一标识符。
-
delta
可更改过扫描边衬区的数值。
overscanCalibrationComplete()
chrome.system.display.overscanCalibrationComplete(
id: string,
)
通过保存当前值并隐藏叠加层来完成显示屏的过扫描调整。
参数
-
id
字符串
显示屏的唯一标识符。
overscanCalibrationReset()
chrome.system.display.overscanCalibrationReset(
id: string,
)
将显示屏的过扫描边衬区重置为上次保存的值(即调用 Start 之前)。
参数
-
id
字符串
显示屏的唯一标识符。
overscanCalibrationStart()
chrome.system.display.overscanCalibrationStart(
id: string,
)
开始屏幕的过扫描校准。屏幕上会显示一个叠加层,指示当前的过扫描边衬区。如果正在对显示屏 id
进行过扫描校准,则会重置校准。
参数
-
id
字符串
显示屏的唯一标识符。
setDisplayLayout()
chrome.system.display.setDisplayLayout(
layouts: DisplayLayout[],
callback?: function,
)
设置所有显示屏的布局。未添加的任何显示屏都将使用默认布局。如果布局重叠或因其他原因而无效,则会将其调整为有效布局。解析布局后,将触发 onDisplayChanged 事件。注意:此功能仅适用于 Chrome 操作系统的自助服务终端应用和网页界面。
参数
-
布局
除主显示屏之外的所有显示屏都需要的布局信息。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
setDisplayProperties()
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,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
setMirrorMode()
chrome.system.display.setMirrorMode(
info: MirrorModeInfo,
callback?: function,
)
将显示模式设置为指定的镜像模式。每次调用都会重置之前调用的状态。对于镜像目标屏幕,调用 setDisplayProperties() 将失败。注意:此功能仅适用于 Chrome 操作系统的自助服务终端应用和网页界面。
参数
-
应该应用于显示模式的镜像模式的信息。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
showNativeTouchCalibration()
chrome.system.display.showNativeTouchCalibration(
id: string,
callback?: function,
)
显示屏幕的原生触摸校准用户体验,其中 id
作为屏幕 ID。屏幕上会显示一个叠加层,其中包含有关如何继续操作的必要说明。仅当校准成功时才会调用回调。如果校准失败,则会抛出错误。
参数
-
id
字符串
显示屏的唯一标识符。
-
callback
函数(可选)
callback
参数如下所示:(success: boolean) => void
-
成功
布尔值
-
返回
-
Promise<boolean>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
startCustomTouchCalibration()
chrome.system.display.startCustomTouchCalibration(
id: string,
)
启动显示屏的自定义触摸校准。在使用自定义用户体验收集校准数据时应调用此方法。如果已在进行另一触摸校准,则会引发错误。
参数
-
id
字符串
显示屏的唯一标识符。
事件
onDisplayChanged
chrome.system.display.onDisplayChanged.addListener(
callback: function,
)
在显示配置发生任何变化时触发。
参数
-
callback
函数
callback
参数如下所示:() => void