UIScreen
UIScreen 表示一块屏幕:它的大小、像素密度、亮度、刷新率,以及此刻有没有被录制。
屏幕从场景读:scene.screen。iPhone 上只有一块屏幕,所有场景读到的是它。接了外接显示器时,显示在那块显示器上的场景读到的是另一块屏幕。外接显示器未在模拟器验证。
屏幕的大小是整块屏幕的范围,包括状态栏和底部横条占住的地方。摆放内容用视图的安全区,不用屏幕的大小去算。
继承关系:EventTarget → NSObject → UIScreen
构造函数
不能用 new 创建。new UIScreen() 抛 TypeError: Illegal constructor: UIScreen is created by the runtime, not by new。屏幕从场景的 screen 读。
实例属性
还继承 NSObject 的属性。
大小和像素密度:
| 属性 | 说明 |
|---|---|
bounds 只读 | 整块屏幕的范围,单位 pt |
scale 只读 | 一个 pt 对应几个像素 |
nativeBounds 只读 | 物理屏幕的范围,单位是像素 |
nativeScale 只读 | 物理屏幕上一个 pt 对应几个像素 |
traitCollection 只读 | 屏幕的外观特征 |
亮度:
| 属性 | 说明 |
|---|---|
brightness | 屏幕亮度,0 到 1 |
wantsSoftwareDimming | 亮度低于硬件下限时,要不要用软件再压暗 |
刷新和显示:
| 属性 | 说明 |
|---|---|
maximumFramesPerSecond 只读 | 每秒最多刷新几帧 |
calibratedLatency 只读 | 显示硬件的延迟,单位秒 |
currentEDRHeadroom 只读 | 此刻能显示的最亮白色比普通白色亮几倍 |
potentialEDRHeadroom 只读 | 最多能显示的最亮白色比普通白色亮几倍 |
referenceDisplayModeStatus 只读 | 参考显示模式的状态 |
录屏和镜像:
| 属性 | 说明 |
|---|---|
isCaptured 只读 | 此刻是否正在被录屏、投屏或镜像 |
mirroredScreen 只读 | 这块屏幕在镜像哪块屏幕 |
显示模式(外接显示器用):
| 属性 | 说明 |
|---|---|
availableModes 只读 | 支持的全部显示模式 |
preferredMode 只读 | 最合适的显示模式 |
currentMode | 此刻用的显示模式 |
实例方法
| 方法 | 说明 |
|---|---|
snapshotViewAfterScreenUpdates() | 把屏幕此刻的内容拍成一个视图 |
事件
| 事件 | 什么时候派发 |
|---|---|
brightnesschange | 屏幕亮度变了 |
capturedchange | 开始或停止被录屏、投屏、镜像 |
modechange | 显示模式变了 |
referencedisplaymodestatuschange | 参考显示模式的状态变了 |
keyboardshow | 键盘要弹出 |
keyboardhide | 键盘要收起 |
keyboardchange | 键盘的位置或大小要变:弹出、收起、换输入法 |
- 事件不能取消。
- 前四个事件的回调不是在变化的那一刻同步执行,而是稍后执行,见运行时怎么工作。
- 键盘的三个事件是当场派发的:监听器在键盘的动画里执行,这时候改的布局跟着键盘一起动。
- 屏幕上也可以监听和派发自定义名字的事件。
示例
读屏幕的大小
js
application.addEventListener('sceneconnect', (e) => {
const screen = e.scene.screen;
console.log(screen.bounds.width, screen.bounds.height, screen.scale);
console.log(screen.nativeBounds.width, screen.nativeBounds.height);
});结果:在 iPhone Air 模拟器(iOS 27.2)上输出两行:
420 912 3
1260 2736出示二维码时调到最亮
js
application.addEventListener('sceneconnect', (e) => {
const screen = e.scene.screen;
const before = screen.brightness;
screen.brightness = 1;
// 离开这个页面时写回去
// screen.brightness = before;
console.log(before);
});效果:屏幕调到最亮,控制台输出原来的亮度。按 iOS 的说明,锁屏之后亮度恢复成系统的设置。屏幕变亮未在模拟器验证。
录屏时遮住敏感内容的例子在 capturedchange。
对应的 iOS API
| ObjC | JS |
|---|---|
UIScreen.mainScreen | scene.screen |
view.window.windowScene.screen | view.window.windowScene.screen |
screen.bounds.size.width | screen.bounds.width |
screen.brightness = 1.0 | screen.brightness = 1 |
screen.isCaptured | screen.isCaptured |
UIScreenCapturedDidChangeNotification | screen.addEventListener('capturedchange', …) |
UIScreenBrightnessDidChangeNotification | screen.addEventListener('brightnesschange', …) |
UIScreenModeDidChangeNotification | screen.addEventListener('modechange', …) |
UIScreenReferenceDisplayModeStatusDidChangeNotification | screen.addEventListener('referencedisplaymodestatuschange', …) |
UIKeyboardWillShowNotification | screen.addEventListener('keyboardshow', …) |
UIKeyboardWillHideNotification | screen.addEventListener('keyboardhide', …) |
UIKeyboardWillChangeFrameNotification | screen.addEventListener('keyboardchange', …) |
参见
UIWindowScene:屏幕从场景读UIScreenMode:显示模式- 外观特征:深色还是浅色、几倍屏
- 单位:pt 和像素
UIDevice:设备和系统的信息