Skip to content

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 ​

ObjCJS
UIScreen.mainScreenscene.screen
view.window.windowScene.screenview.window.windowScene.screen
screen.bounds.size.widthscreen.bounds.width
screen.brightness = 1.0screen.brightness = 1
screen.isCapturedscreen.isCaptured
UIScreenCapturedDidChangeNotificationscreen.addEventListener('capturedchange', …)
UIScreenBrightnessDidChangeNotificationscreen.addEventListener('brightnesschange', …)
UIScreenModeDidChangeNotificationscreen.addEventListener('modechange', …)
UIScreenReferenceDisplayModeStatusDidChangeNotificationscreen.addEventListener('referencedisplaymodestatuschange', …)
UIKeyboardWillShowNotificationscreen.addEventListener('keyboardshow', …)
UIKeyboardWillHideNotificationscreen.addEventListener('keyboardhide', …)
UIKeyboardWillChangeFrameNotificationscreen.addEventListener('keyboardchange', …)

参见 ​