uni-app实现App端的屏幕亮度调节 uni-app系统API调用教程-uni-app-PHP中文网

uni-app屏幕亮度调节需分平台：iOS设系统级亮度且退出后保留，Android默认仅应用内生效；须避onShow死循环，用onReady+防抖或标记位；临时提亮需存旧值并在onUnload恢复，Android建议value: -1同步系统；setKeepScreenOn仅防休眠不控亮度，部分安卓厂商需手动授权。

uni-app实现app端的屏幕亮度调节 uni-app系统api调用教程

uni-app 的屏幕亮度调节在 App 端基本可用，但必须区分平台行为、避免 onShow 死循环、且不能直接“黑屏/亮屏”——只能调亮度值或常亮。

uni.setScreenBrightness() 在 App 端的实际表现

这个 API 在 iOS 和 Android 上都能调用成功，但底层逻辑完全不同：

iOS：设置的是系统级亮度，uni.setScreenBrightness({value: 0.8}) 会真实改变用户设备的全局亮度，退出 App 后仍保持
Android（5.0+）：默认只影响当前应用的窗口亮度，不影响系统设置；若想同步系统亮度，需传 value: -1（仅 Android 支持，HBuilderX 3.2.11+）
值范围是 0（最暗）到 1（最亮），传非数字或超范围不会报错，但无效
某些 Android 厂商（如华为 EMUI、小米 MIUI）可能拦截该调用，尤其在后台或省电模式下，fail 回调会触发

为什么不能在 onShow 里直接 setScreenBrightness()

因为部分 Android 设备在亮度变化时会触发页面重载或 onShow 再次执行，形成无限回调。官方明确提示要避开：

不要在 onShow、onLoad 中无条件调用 uni.setScreenBrightness()
推荐改用 onReady + 防抖，或绑定用户显式操作（如按钮点击）
若必须进页即调，加个标记位：if (!this._brightnessSet) { uni.setScreenBrightness(...); this._brightnessSet = true; }

如何安全地“临时提亮 + 恢复”（比如扫码页）

典型场景是二维码展示页需要最高亮度，离开时还原。关键点不是“记住旧值”，而是处理平台差异：

uni-app

uni-app 是基于 Vue 的跨端开发框架，适合开发 H5、App、小程序、鸿蒙和多端业务应用。

下载

进入前先用 uni.getScreenBrightness() 获取当前值，存入 uni.setStorageSync（注意：iOS 存的是系统值，Android 存的是当前应用值）
设置亮度后，**必须在 onUnload 或 onBackPress 里恢复**，不能等 onHide —— 它可能不触发
iOS 恢复时直接写回存储的值；Android 建议写 -1（同步系统）或原值（若确定未被厂商拦截）

示例恢复逻辑：

onUnload() {
  const saved = uni.getStorageSync('saved_brightness');
  const platform = uni.getSystemInfoSync().platform;
  if (platform === 'ios') {
    uni.setScreenBrightness({ value: Number(saved) });
  } else {
    uni.setScreenBrightness({ value: -1 }); // 交还给系统
  }
}

uni.setKeepScreenOn() 的生效边界

它和亮度 API 是两回事，但常被一起用。注意三点：

keepScreenOn: true 只在当前页面前台时有效，切到后台或锁屏后自动失效
H5 和小程序平台多数不支持（文档标为 ×），仅 App（含 HarmonyOS Next）可用
不要和 setScreenBrightness 混用做“强制亮屏”——它不控制亮度，只阻止休眠；若用户手动调低亮度，setKeepScreenOn 不会拉高它

真正难处理的不是 API 调用本身，而是 Android 厂商对 PowerManager 的限制越来越严，连 setKeepScreenOn 在某些 MIUI 版本上都需要手动开启“允许保持唤醒”权限。这时候必须引导用户去设置页，而不是指望 JS 单方面生效。