更新记录

1.0.0（2026-10-18）

兼容蒸汽模式

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

亮度常亮 X

适合阅读、扫码、视频、导航等前台页面。统一控制屏幕亮度与常亮，附带可直接复制的演示页。

• 调亮度：0～100%，读取当前状态，恢复修改前的亮度。
• 防息屏：开启或关闭屏幕常亮，页面退出时可恢复原状态。
• 直接接入：.uvue 与 .vue 示例、操作结果和错误码、系统设置入口。

使用 HBuilderX 5.26 或以上。这是 UTS API 插件，不包含原生视图组件。Web、小程序、鸿蒙不提供屏幕控制能力。

4 步运行演示

1. 导入插件

从插件市场导入项目，确认目录存在：

uni_modules/austin-screen-x/

2. 制作并选择自定义基座

在 HBuilderX 选择目标项目，制作 Android 或 iOS 自定义调试基座。打包完成后安装基座，在“运行到手机或模拟器”中选择自定义基座。

首次导入、升级插件原生代码后需要重新制作基座；只修改演示页面不需要重新制作。iOS 真机基座使用该 App 对应的 .p12 与 .mobileprovision，本插件不需要额外证书或 .p8。

3. 复制页面

按自己的项目类型选择一个文件，复制完整内容：

页面内部已使用 @/uni_modules/austin-screen-x，复制后无需修改 import。

4. 注册并打开页面

在项目 pages.json 的 pages 数组内添加：

{
  "path": "pages/screen/index",
  "style": { "navigationBarTitleText": "亮度与常亮", "disableScroll": true }
}

uni-app x 页面内部使用 scroll-view，保留 disableScroll: true；普通 uni-app 项目可省略此项。

从已有页面打开：

uni.navigateTo({ url: '/pages/screen/index' })

先点 25%、75% 观察亮度，再打开常亮。返回上一页后，演示页会恢复自己改动过的亮度与进入时的常亮状态。

项目权限

无需在 manifest.json 增加本插件专用权限。 不需要麦克风、录音、相机或定位权限，也不需要 Android WRITE_SETTINGS 授权弹窗。

常亮用于防止前台自动息屏，不能阻止用户按电源键锁屏，也不用于后台保活。iOS 不提供通过本接口直接打开系统“显示与亮度”页的入口。

在自己的页面调用

下面代码放入 uni-app x 页面的 <script setup lang="uts">：进入页面设置 75% 亮度并开启常亮，退出时恢复原状态。

import { getScreenState, setBrightness, resetBrightness, setKeepScreenOn, ScreenState, BrightnessOptions } from '@/uni_modules/austin-screen-x'

let initial: ScreenState | null = null
let brightnessChanged = false
let keepChanged = false

onLoad(() => {
  initial = getScreenState()
  const options: BrightnessOptions = { value: 0.75 }
  const brightnessResult = setBrightness(options)
  const keepResult = setKeepScreenOn(true)
  brightnessChanged = brightnessResult.ok
  keepChanged = keepResult.ok
  console.log(brightnessResult, keepResult)
})

onUnload(() => {
  const original = initial
  if (original == null) return
  if (brightnessChanged) {
    if (original.usingCustomBrightness) {
      const options: BrightnessOptions = { value: original.brightness }
      setBrightness(options)
    } else resetBrightness()
  }
  if (keepChanged) setKeepScreenOn(original.keepScreenOn)
})

uni-app Vue3 使用相同 API，删除 ScreenState、BrightnessOptions 类型导入及相应类型标注，并从 @dcloudio/uni-app 导入 onLoad、onUnload。

每次操作可检查返回值的 ok、errCode、errMsg。openSystemSettings() 请只在用户点击设置按钮时调用。

页面退出时恢复

插件本身不会自动恢复。演示页在 onUnload / onBeforeUnmount 时恢复；切到后台触发的 onHide 不等于页面销毁。完整演示页已经处理以下规则，推荐直接复制演示页中的 enterPage() 与 leavePage()：

1. 进入页面时记录一次亮度、是否自定义亮度、常亮状态。
2. 仅记录调用成功的改动；刷新状态、从系统设置返回不会覆盖初始记录。
3. 页面卸载时，仅恢复本页改动过的项；原本开启常亮的页面不会被强制关闭。

需要在后台也立即停止常亮时，可在自己的 onHide 中恢复常亮，并在 onShow 中根据业务重新开启。示例在页面卸载时恢复，跳转系统设置不会重建初始记录。

API

以下接口均同步返回；请在 App 前台页面中调用。

setBrightness() 不传参数时使用 50%；有限数值超出 0～1 会截取到范围内，value: null、NaN / Infinity 返回失败且不改变亮度。

resetBrightness() 的含义： 恢复本轮第一次 setBrightness() 前记录的亮度，并清除这次记录。Android 恢复窗口原值（原先跟随系统时恢复跟随系统）；iOS 恢复当时记录的屏幕亮度。它不会关闭常亮，也不保证恢复为某个固定百分比。多个页面共同使用时，请由业务统一管理恢复时机。

操作结果 ScreenOperationResult

状态 ScreenState

常见问题

错误码：11001 为平台不支持，34001 为当前页面或亮度/常亮操作不可用，34002 为打开设置失败，34003 为非法亮度值。以 ok 和 errMsg 判断本次操作结果。