真机交互鸿蒙 PC 实战:屏幕亮度改不了全局,能改的只有「本应用这个窗口」,还得挑前台有焦点的时候

想给商品详情页做个「看大图时把屏幕调亮」,我一开始以为 setWindowBrightness() 就是把整块屏幕提亮,结果切出应用亮度就弹回去了,投到扩展屏上更是纹丝不动。翻 @ohos.window.d.ts 那段注释才看清楚:这个 API 从名字就写死了是「window brightness」,只作用于本应用窗口所在的那块物理屏、只在窗口前台且有焦点时生效、窗口一进后台设置就失效,还特意劝你别在前后台切换时连着调。真正的全局亮度在 settings 的 systemapi 里,普通 normal 应用压根够不着。而 -1 这个特殊值、getWindowProperties().brightness 的读回、setWindowKeepScreenOn() 的常亮、setBrightness() 被 setWindowBrightness() 取代的废弃关系,又各自藏着一层边界。这篇文章用 tauri-hello「真机交互」页那 6 个亮度按钮从「切出去就打回原形」到读懂整套窗口级亮度语义的完整记录,把「窗口亮度 ≠ 系统亮度」、-1 为什么不是非法参数、前台焦点与物理屏的约束、常亮该在什么场景用、以及 1300002/1300003 这类窗口错误码怎么定位这几个问题一次讲透。

先交代这一篇在代码里的落点:

  • 亮度能力实现:tauri-hello/entry/src/main/ets/bridge/SystemCapability.ets(1951 行,brightness* 方法集中在 1771–1845 行,mainWindow() 在 1766 行)
  • 分发入口:SystemCapability.call() 的 519–522 行,interact.brightness.* 共 4 个 case
  • 状态字段:winBrightness: number = -1(415 行)、keepScreenOn: boolean = false(416 行)
  • 前端交互:www/js/app.js 的 capInteractBrightness*(1730–1762 行,6 个函数,其中 preset/follow/keepOn 复用 4 个 case)
  • 页面区块:www/index.html 1066–1084 行,6 个按钮 + 亮度输入
  • SDK 依据:@ohos.window.d.ts(setWindowBrightness 6504–6531、getWindowProperties 4159、setWindowKeepScreenOn 6746–6770)
  • 设备能力清单:ets/api/device-define/2in1.json(SystemCapability.WindowManager.WindowManager.Core)

这一系列四篇各讲一个真机交互能力,知识点不串台。这一篇只讲 window 的窗口级亮度与常亮;通知 notificationManager 放第一篇,日历 calendarManager 的 user_grant 授权时序放第二篇,声音 audio 的全局受限与 AudioRenderer 放第三篇。四篇里只有这一篇的能力是完全不需要任何权限、也不弹任何窗就能跑通的——它的难点不在「拿不拿得到权限」,而在「改的东西到底作用到哪一层」。


0. 环境与实测设备

项版本 / 型号
设备HarmonyOS PC(aarch64,API 26,2in1 形态)
DevEco Studio本机安装版,hvigor 7.26.11
鸿蒙 SDKAPI 26.0.0,compatibleSdkVersion 26.0.0,runtimeOS HarmonyOS
应用com.example.myapplication,versionCode 1000000
窗口 Kit@kit.ArkUI 的 window
主窗口 APIwindow.getLastWindow(ctx) → Promise<Window>(@ohos.window.d.ts:2097)
亮度 APIsetWindowBrightness(brightness: number): Promise<void>(6531,since 9)
读回 APIgetWindowProperties(): WindowProperties(4159),brightness 字段(1160)
常亮 APIsetWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void>(6770,since 9)
废弃关系setBrightness() deprecated since 9,@useinstead setWindowBrightness()(6460–6479)
设备 syscapSystemCapability.WindowManager.WindowManager.Core(2in1.json 确认在列)
承载方式ArkWeb + javaScriptProxy,注入名 MallBridge
应用上下文common.UIAbilityContext(getLastWindow 要它)
前端业务层原生 JS 无框架,www/js/app.js 104044 字节
页面规模www/index.html 82924 字节,104 个 onclick 入口
能力方法数SystemCapability.call() 分发 56 个 case,其中 interact.brightness.* 4 个
构建产物entry-default-signed.hap,748020 字节
构建结果BUILD SUCCESSFUL in 11 s 783 ms(仅 WARN,无 ERROR)

四个真机交互能力摆在一起看,边界特别整齐:日历是「弹窗能拿到的 user_grant 权限」,声音是「provisionEnable: False 拿不到的受限权限」,通知是「根本不是权限、是应用通知开关」,亮度则是「压根不需要权限」。我在亮度这 6 个按钮上一句 1007 都没回过——因为 setWindowBrightness() 是公开 API,@permission 那一栏是空的。它难的地方完全在另一处:作用范围。


1. 问题是怎么找上我的:我把窗口亮度当成了屏幕亮度

我一开始对「控制屏幕亮度」的理解,跟笔记本上按亮度快捷键一模一样:调一下,整块屏幕变了,切到别的应用也还是那个亮度。项目里 brightnessSet() 第一版就是奔着这个去的:

// SystemCapability.ets - brightnessSet()(最早一版,节选)
const win: window.Window = await window.getLastWindow(this.context);
await win.setWindowBrightness(0.9);   // 我以为这是「把屏幕调亮」

ArkTS 编译一次过,0.9 在 0~1 范围内,真机上点「设置亮度」也确实立刻亮了。我正准备收工,顺手切出去看了一眼系统设置,再切回来——亮度弹回去了。投到扩展显示器上试,那块屏更是完全没反应。当时的回包还是 ok:true,一点错误都没有:

{"ok":true,"code":0,"data":{"brightness":0.9,"mode":"应用自定义","api":"window.getLastWindow(ctx).setWindowBrightness(brightness: number)"},"message":"窗口亮度已设为 0.9(真机可直接看到变化)"}

没有报错,因为代码没写错——是我对 API 语义的理解错了。翻到 @ohos.window.d.ts:6505 那段注释,几行字把这事钉死了:

// @ohos.window.d.ts:6505-6516(节选)
Sets the window brightness for the main window. The window brightness takes effect only when the window is in the
foreground and has focus. ...
When the setting is valid, it affects only the physical screen where the window is displayed. It does not apply
to virtual displays (for example, casting/mirroring screens).
If the input parameter is -1, the window brightness reverts to the system brightness ...
When the window moves to the background, the setting becomes invalid ...
You are advised not to call this API consecutively or when the window transitions to the background. Otherwise,
timing issues may occur.

setWindowBrightness —— 名字里那个 Window 不是修饰,是限定。前台且有焦点才生效、只作用窗口所在物理屏、不作用虚拟屏/投屏、进后台就失效、别连着调。 全局亮度在 settings 的 systemapi 里,普通 normal 应用拿不到;能改的,从头到尾只是「本应用这个窗口叠在那块屏上的时候,看起来多亮」。

所以这个题目的边界很清楚:「屏幕亮度」这个词在应用开发里是个陷阱,真正能做的不是改系统亮度,而是给本应用窗口设一个前台期有效的亮度覆盖值;它随窗口焦点生死、不跨物理屏、-1 是撤销覆盖回到系统亮度,另外再配一个同样窗口级、同样只在必要场景该开的 setWindowKeepScreenOn() 常亮。 认清这层,那个「切出去就弹回去」就不是 bug,是文档写明的语义。

拆开之后要干的事就三件:

  • 把读、设、跟随系统、常亮四个动作做扎实,参数校验别把 -1 当非法值一刀切;
  • 把「窗口级 / 前台 / 物理屏」这些边界如实写进回包和页面说明,别让用户以为改了全局;
  • 把 1300002 / 1300003 这类窗口状态错误码翻成能定位的中文,别闷声失败。

下面是干完之后的完整记录,包括我踩的每一个坑。第 6 节会把开头那次「切出去就弹回」收回来,讲清楚它对应的到底是哪条文档约束。


2. 效果展示

按老规矩,先给效果再讲原理。「真机交互」页的亮度区块是 6 个按钮加一个亮度输入:

请添加图片描述

6 个按钮对应 4 个 case,UI 上每个都能映射回一次 window.Window 调用:

  • 读当前亮度 → interact.brightness.get → getWindowProperties().brightness,回包 mode 用 brightness < 0 ? '跟随系统' : '应用自定义' 判断。
  • 设置亮度 → interact.brightness.set → setWindowBrightness(0~1),真机应用窗口立刻变亮/暗。
  • 用快捷预设 → 前端 capInteractBrightnessPreset() 把 0.3/0.6/1.0 这类值喂给同一个 set case。
  • 跟随系统 → interact.brightness.followSystem → setWindowBrightness(-1),撤销应用自定义。
  • 开启常亮 / 关闭常亮 → interact.brightness.keepOn → setWindowKeepScreenOn(true/false)。

请添加图片描述
请添加图片描述

这里每一行都不是装饰:data.hint 会明写「只影响本应用窗口,无需权限;改全局亮度要 settings systemapi,普通应用做不到」,读回来的 data.api 是 window.getLastWindow(ctx).getWindowProperties().brightness。把「这不是全局」写进回包,比写在文档里管用——真机排查时用户看的就是这行字。

请添加图片描述
请添加图片描述

第二张图是「设置亮度 0.9」和「跟随系统」两次回包并排的样子,重点在 brightness 和 mode 两个字段:

{"ok":true,"code":0,"data":{"brightness":0.9,"mode":"应用自定义","api":"window.getLastWindow(ctx).setWindowBrightness(brightness: number)","hint":"只影响本应用窗口,无需权限;改全局亮度要 settings systemapi,普通应用做不到"},"message":"窗口亮度已设为 0.9(真机可直接看到变化)"}
{"ok":true,"code":0,"data":{"brightness":-1,"mode":"跟随系统","api":"window.getLastWindow(ctx).setWindowBrightness(-1)","hint":"-1 是文档约定的特殊值,表示撤销应用自定义亮度、回到系统亮度"},"message":"已恢复跟随系统亮度"}

请添加图片描述
请添加图片描述

-1 那次回包特意用了 mode: '跟随系统',就是为了把「特殊值」和「非法值」分开——第 5 节 5.4 会讲参数校验为什么不能一刀切拦掉负数。

主动交代边界:这 6 个按钮在浏览器预览里全部回 1004 needsDevice:

{"ok":false,"code":1004,"message":"「interact.brightness.set」是真机系统能力,浏览器预览无对应服务,请装 entry-default-signed.hap 到鸿蒙 PC 验证(Web 端不模拟、不伪造成功)","data":{"needsDevice":true,"method":"interact.brightness.set"}}

请添加图片描述
请添加图片描述

浏览器里当然能用 CSS filter: brightness() 把页面调亮,但那改的是 DOM 渲染,跟 window.Window 的窗口亮度是两码事。用它「模拟」只会把「窗口级 / 前台 / 物理屏」这条最要紧的边界糊掉,所以亮度在 Web 端一律不造结果。


3. 原理:窗口亮度是覆盖值,不是系统设置

把亮度这条链路按「API → 作用层 → 生命周期 → 失败码」摊开:

API作用层生不生效取决于典型错误码
getLastWindow(ctx)取本应用主窗口句柄传的是 UIAbilityContext—
getWindowProperties()读窗口属性快照窗口还活着1300002 / 1300003
setWindowBrightness(0~1)本应用窗口亮度覆盖前台 + 有焦点 + 物理屏401 / 1300002 / 1300003
setWindowBrightness(-1)撤销覆盖,回系统亮度同上同上
setWindowKeepScreenOn(bool)阻止本应用前台时自动熄屏前台、场景合规401 / 1300002 / 1300003
settings systemapi(未用)全局系统亮度普通应用够不着—

窗口亮度是「本应用窗口盖在某块物理屏上、且正处于前台焦点时」的一个临时覆盖值,窗口一走,覆盖就没了;它从来不是写进系统设置里的一个数。 这句话是这一篇最要紧的模型判断。我最早那次「切出去就弹回去」,恰恰是这个模型在按文档工作,不是哪里坏了。

三个细节决定了后面所有的写法:

第一,setWindowBrightness(brightness: number) 的 @syscap 是 SystemCapability.WindowManager.WindowManager.Core,@since 9,@permission 空。四能力里唯一一个连权限表都不用查的。它抛的是 401(参数错:必填没给 / 类型不对)、1300002(窗口状态异常:窗口没创建或已销毁、内部任务错)、1300003(窗口管理服务异常)——全是「窗口」层面的码,不是权限码。

第二,getWindowProperties().brightness 是 number(@ohos.window.d.ts:1160),-1 表示当前跟随系统、非负值表示应用自定义过。读回和设置用的是同一个量的两套语义,所以 brightnessGet() 里 brightness < 0 ? '跟随系统' : '应用自定义' 不是猜,是文档约定。

第三,setWindowKeepScreenOn() 的文档(6774–6777)特意圈了场景:只在导航、视频播放、绘图、游戏这类必要场景设 true,退出就得设回 false;系统一旦检测到「非标准用法」(比如没有屏幕交互、没有音频播放时一直常亮),可能反过来触发自动熄屏。常亮不是「免死金牌」,是有使用契约的。


4. 工程怎么搭

先给亮度链路相关的目录树:

tauri-hello/
├── entry/src/main/
│   ├── module.json5                          # 4 项权限,亮度不占任何一项
│   ├── ets/
│   │   ├── bridge/
│   │   │   ├── MallBridge.ets               # sysCall 唯一桥
│   │   │   └── SystemCapability.ets         # 4 个 brightness* + mainWindow() + winBrightness/keepScreenOn 状态
│   │   └── pages/Index.ets                  # methodList: ['sysCall']
│   └── resources/rawfile/www/
│       ├── index.html                       # 真机交互页亮度区块(6 按钮 + 亮度输入)
│       └── js/
│           ├── app.js                       # 6 个 capInteractBrightness* + CAP_INTERACT_MATRIX「屏幕亮度」条
│           └── platform/web.js             # interact.* 统一回 1004 needsDevice
└── entry/build/default/outputs/default/entry-default-signed.hap

这次整理最关键的变化,是把「调一下亮」拆成读、设、跟随、常亮四个能各自独立回包、又共享同一份窗口状态的动作。三条边界:

  • 窗口句柄统一走 mainWindow()。window.getLastWindow(this.context) 只写一处(1766 行),四个方法都调它,避免每个方法各自猜上下文。
  • 状态在 ArkTS 侧、且只是缓存。winBrightness / keepScreenOn 两个成员(415–416 行)记的是「上一次设了什么」,真正的当前值仍以 getWindowProperties() 为准;缓存只是让 keepOn 回包能带上 brightness。
  • 回包统一 { ok, code, data, message },亮度失败走 CODE_NATIVE_ERROR = 1003,data.hint 一律点明「窗口级、非全局」。

最小接入照例过 sysCall:

// www/js/app.js - capInteractBrightnessSet()(节选)
function capInteractBrightnessSet() {
  return capCall('interact.brightness.set', {
    brightness: Number(capVal('cap-br-value'))   // 0~1
  }, 'cap-out-interact-brightness');
}
// → Platform.syscap.call → MallBridge.sysCall → SystemCapability.call() case 'interact.brightness.set'

四个 case 在 call() 里的分发(519–522 行):

// SystemCapability.ets - call() 分发(节选)
case 'interact.brightness.get':           return await this.brightnessGet();
case 'interact.brightness.set':           return await this.brightnessSet(p);
case 'interact.brightness.followSystem':  return await this.brightnessFollow();
case 'interact.brightness.keepOn':        return await this.brightnessKeepOn(p);

这里有一个很容易被忽略的窗口期:文档明确劝「别在窗口前后台切换时连着调 setWindowBrightness(),否则 timing issues may occur」。所以我把「设置」和「跟随系统」做成两个独立按钮、各自一次调用,没有做「拖动滑块实时跟随」那种连续调用——不是做不了,是连续调用正好撞在文档点名的时序风险上。这个取舍在坑 4 里还要再算一次账。


5. 把代码讲透

5.1 拿主窗口:getLastWindow(ctx) 只写一处

mainWindow() 是四个方法共用的底座:

// SystemCapability.ets - mainWindow()(1765–1768 行,节选)
/** 拿主窗口:window.getLastWindow(context) → Promise<Window> */
private async mainWindow(): Promise<window.Window> {
  return await window.getLastWindow(this.context);
}

三个细节值得单独说:

第一,window.getLastWindow(ctx) 用的是返回 Promise<Window> 的重载(@ohos.window.d.ts:2097),不是 callback 版(2076 行)。ctx 传的是构造时存下的 common.UIAbilityContext。

第二,返回类型显式写 window.Window。ArkTS 严格模式下不能让返回值推断成 any,四个调用方都靠这个具体类型拿 setWindowBrightness 等方法。

第三,「getLastWindow」取的是「最近一次获得焦点的主窗口」。这也是为什么亮度天然和前台焦点绑在一起——句柄本身就是焦点窗口。

一个反直觉陷阱:getLastWindow() 在窗口还没创建、或已经销毁时会失败,对应 1300002。所以每次调用都重新取窗口、包在 try 里,不在成员里长期缓存 Window 对象。降级说明:2in1 形态下主窗口通常是唯一的,多窗口场景里 getLastWindow 取的是最后活跃那个,别假设一定是某个具体子窗口。

5.2 读亮度:getWindowProperties().brightness 和 -1 的两种语义

brightnessGet() 处理「读」这一侧:

// SystemCapability.ets - brightnessGet()(1771–1786 行,节选)
const win: window.Window = await this.mainWindow();
const props: window.WindowProperties = win.getWindowProperties();
this.winBrightness = props.brightness;
const d: BrightnessData = {
  brightness: props.brightness,
  mode: props.brightness < 0 ? '跟随系统' : '应用自定义',
  api: 'window.getLastWindow(ctx).getWindowProperties().brightness',
  hint: '这是本应用窗口的亮度,不是全局系统亮度;-1 表示跟随系统设置'
};
return this.ok(d, '当前窗口亮度 ' + props.brightness);

三个细节值得单独说:

第一,getWindowProperties() 是同步方法(4159 行返回 WindowProperties,不是 Promise),不用 await。我第一版顺手加了个 await,虽然不报错但纯属多余。

第二,props.brightness < 0 ? '跟随系统' : '应用自定义' 把数值翻成可读模式。-1 不是「亮度为负」,是「没设过应用自定义、跟随系统」这个状态标记。

第三,this.winBrightness = props.brightness 把读回值同步进缓存,让后面 keepOn 的回包能带上当前亮度。

反直觉陷阱:props.brightness 返回的是这个窗口的亮度覆盖值,不是系统全局亮度。系统设置里那个滑块的值,普通应用从这里读不到。读回的对象和「系统亮度」不是同一个量,别拿它去反推用户在控制面板设了几档。 降级说明:WindowProperties 里还有窗口 id、displayId 等字段,这一篇只用 brightness,不把整个属性对象塞回前端。

5.3 设亮度:0~1 参数校验,负数交给专门的 follow 方法

brightnessSet() 是「设」这一侧:

// SystemCapability.ets - brightnessSet()(1792–1810 行,节选)
const val: number = this.num(p, 'brightness', -99);
if (val < 0 || val > 1) {
  return this.err(SystemCapability.CODE_BAD_PARAM,
    'brightness 必须是 0~1(或点「跟随系统」传 -1)');
}
const win: window.Window = await this.mainWindow();
await win.setWindowBrightness(val);
this.winBrightness = val;
const d: BrightnessData = {
  brightness: val, mode: '应用自定义',
  api: 'window.getLastWindow(ctx).setWindowBrightness(brightness: number)',
  hint: '只影响本应用窗口,无需权限;改全局亮度要 settings systemapi,普通应用做不到'
};
return this.ok(d, '窗口亮度已设为 ' + val + '(真机可直接看到变化)');

三个细节值得单独说:

第一,val < 0 || val > 1 拦的是「设置」这个动作的非法输入。默认值给 -99(不是 -1),就是为了让「没传参数」和「传了 -1」区分开——-1 有专门语义,不能当缺省。

第二,校验里明确写了「或点『跟随系统』传 -1」。set 不接 -1,-1 走 brightnessFollow() 单独一个 case,两个动作不混在一个方法里靠 if 分叉。

第三,hint 把「只影响本应用窗口 / 全局要 settings systemapi」写进回包,是这一篇最想让人看到的一句话。

反直觉陷阱:setWindowBrightness() 的 @throws 里有 401 Parameter error,但应用侧已经先做了 0~1 校验,等于把 401 大半挡在前面了。真正会漏到原生的是 1300002(窗口状态异常)这类运行时错误——catch 统一回 CODE_NATIVE_ERROR = 1003,如实透传。降级说明:brightness 是 number,this.num()(1866 行)用 Number(v) + isFinite 兜底,非数字入参不会把 NaN 传进原生。

5.4 跟随系统:-1 是撤销覆盖,不是非法参数

brightnessFollow() 单独处理那个特殊值:

// SystemCapability.ets - brightnessFollow()(1813–1827 行,节选)
const win: window.Window = await this.mainWindow();
await win.setWindowBrightness(-1);
this.winBrightness = -1;
const d: BrightnessData = {
  brightness: -1, mode: '跟随系统',
  api: 'window.getLastWindow(ctx).setWindowBrightness(-1)',
  hint: '-1 是文档约定的特殊值,表示撤销应用自定义亮度、回到系统亮度'
};
return this.ok(d, '已恢复跟随系统亮度');

三个细节值得单独说:

第一,-1 的语义来自 @ohos.window.d.ts:6511 原文:If the input parameter is -1, the window brightness reverts to the system brightness。它是「撤销应用自定义」的指令,不是「把亮度设成 -1」。

第二,this.winBrightness = -1 把缓存也复位,mode 写死 '跟随系统',和 5.2 读回的判断口径一致。

第三,这个方法和 set 分开成两个 case,前端是两个按钮,回包 data.api 也不同,真机排查时一眼能分出「设了值」还是「撤销了值」。

反直觉陷阱:正因为 -1 是合法特殊值,set 里的 val < 0 校验绝不能图省事改成 val < -1 || val > 1 把 -1 也放进来——那会让「跟随系统」这个有明确语义的动作,退化成「设亮度」分支里的一个魔数。降级说明:文档说 -1 回到的系统亮度「可通过控制面板或快捷键调整」,应用改不了那个值,只能选择「跟不跟」。

5.5 常亮:setWindowKeepScreenOn 与它的使用契约

brightnessKeepOn() 收尾,管的是「别自动熄屏」:

// SystemCapability.ets - brightnessKeepOn()(1830–1845 行,节选)
const on: boolean = this.bool(p, 'on');
const win: window.Window = await this.mainWindow();
await win.setWindowKeepScreenOn(on);
this.keepScreenOn = on;
const d: BrightnessData = {
  brightness: this.winBrightness, mode: on ? '常亮开启' : '常亮关闭',
  api: 'window.getLastWindow(ctx).setWindowKeepScreenOn(boolean)',
  hint: '阻止本应用前台时系统自动熄屏,无需权限;窗口进后台后设置失效'
};
return this.ok(d, on ? '已开启屏幕常亮' : '已关闭屏幕常亮');

三个细节值得单独说:

第一,this.bool(p, 'on')(1873 行)只把 true 或字符串 'true' 判为真,其它一律 false。前端 keepOn(true) / keepOn(false) 两个按钮传的是布尔,稳。

第二,mode 用 on ? '常亮开启' : '常亮关闭',brightness 带的是缓存里的当前亮度——常亮和亮度是两个独立开关,但回包放一起方便对照。

第三,hint 明写「窗口进后台后设置失效」,和 setWindowBrightness 一样是窗口级、前台期有效。

反直觉陷阱:文档(6774–6777)把常亮的适用场景圈得很死——导航、视频、绘图、游戏,退出要设回 false;系统检测到「无屏幕交互、无音频播放却一直常亮」这类非标准用法,可能主动触发自动熄屏。所以「开启常亮」不是一劳永逸,更不是拿它绕过系统电源策略。降级说明:常亮和亮度都不需要权限,但也都不改变系统全局设置,1300002/1300003 这类窗口错误仍要 catch 如实回 1003。


6. 我踩过的坑(每一条都有真实报错)

这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。

坑 1:把 setWindowBrightness() 当成改系统亮度,切出去就打回原形。 就是开头那一幕:

{"ok":true,"code":0,"data":{"brightness":0.9,"mode":"应用自定义",...},"message":"窗口亮度已设为 0.9(真机可直接看到变化)"}

回包 ok:true,可切到别的应用再回来,亮度弹回系统值;投到扩展屏,那块屏完全不变。一开始以为是设置没生效、是不是要加权限,翻 @ohos.window.d.ts:6505 才看清「前台且有焦点才生效、只作用物理屏、进后台失效」。API 名字里的 Window 是作用范围的限定词,不是可省略的修饰;ok:true 只说明覆盖值设上了,不说明整块屏幕被改了。 这条把第 1 节那次「切出去就弹回」收回来。

坑 2:差点把改全局亮度接到 settings systemapi 上去。 发现切出去失效后,我的第一反应是「那一定有另一个改全局亮度的 API」,去翻 settings:

settings 里全局亮度相关是 systemapi,普通 normal 应用无调用资格

对照一下日历(user_grant 弹窗能拿)、声音(provisionEnable: False 拿不到),亮度这条是第三种:全局能力压根不在三方应用的可用面上。一开始以为「又是权限没申请对」,后来才反应过来这是 API 可见性边界,跟 requestPermissions 无关。不是所有「做不到」都是权限问题,有些是能力根本没对三方开放。 想通之后,hint 里才老老实实写下「改全局亮度要 settings systemapi,普通应用做不到」。

坑 3:-1 被当成非法参数一刀切。 brightnessSet() 第一版校验写的是 val < 0 || val > 1,顺手把「跟随系统」也打算塞进同一个方法,结果 -1 直接被 CODE_BAD_PARAM 挡掉:

调用失败(1001):brightness 必须是 0~1(或点「跟随系统」传 -1)

-1 在 @ohos.window.d.ts:6511 是「撤销覆盖、回系统亮度」的合法特殊值,不是负数亮度。一开始想改成 val < -1 || val > 1 放行它,后来改成干脆拆出 brightnessFollow() 单独一个 case。有特殊语义的值,别塞进通用参数校验里靠边界放宽,给它一个独立入口更清楚。

坑 4:想做「拖动滑块实时调亮」,撞上文档点名的时序风险。 亮度输入我一度想绑 oninput 连续调 setWindowBrightness(),文档那句劝告把我拦下了:

// @ohos.window.d.ts:6515-6516
You are advised not to call this API consecutively or when the window transitions to the background.
Otherwise, timing issues may occur.

一开始以为是「调用太频繁会卡」这种性能问题,后来才反应过来是前台焦点切换时的时序竞态——窗口正在进退后台,你连着改覆盖值,生效时机不可控。改成「点按钮设一次」「跟随系统设一次」的离散动作,不追实时。文档主动点名的 timing issues,比自己压测出来的偶现问题更该当真。

坑 5:setBrightness() 是废弃 API,别照着老例子抄。 找亮度 API 时先翻到的是 setBrightness():

// @ohos.window.d.ts:6460-6463
* @deprecated since 9
* @useinstead window.Window.setWindowBrightness(brightness: double)
setBrightness(brightness: number): Promise<void>;

since 9 就废弃,SDK 直接给了 @useinstead。一开始差点照着旧博客里的 setBrightness(0.9) 写下去。遇到 @useinstead 就照它换,别把废弃 API 带进新代码;setWindowKeepScreenOn() 同理,它取代的是 setKeepScreenOn()(6734–6747 的 @useinstead)。

坑 6:1300002 窗口状态异常,不是权限也不是参数。 有次趁窗口刚创建就点「读当前亮度」,回包是:

调用失败(1003):读取窗口亮度失败:{"code":1300002,"message":"This window state is abnormal."}

@ohos.window.d.ts:6522 写明 1300002 是「窗口没创建或已销毁、内部任务错」,1300003 是「窗口管理服务异常」。一开始以为又是 401 参数错,把 brightness 值翻来覆去换,没用。窗口类 API 的错误码要看窗口生命周期,别套权限/参数那套排查顺序。 修法是每次 mainWindow() 重新取句柄、全包 try,如实透传原生码。

坑 7:以为常亮开了就永远不熄屏。 「开启常亮」点了之后,我一度以为屏幕会一直亮着,直到看见文档 6774–6777:

Set isKeepScreenOn to true only in necessary scenarios (such as navigation, video playback, drawing, and
gaming scenarios). After exiting these scenarios, set the parameter to false. ...
When the system detects that the API is used in a non-standard manner, automatic screen-off may be invoked.

系统检测到「没有屏幕交互、没有音频播放却常亮」这种非标准用法,可能反过来触发自动熄屏。一开始把常亮当成免死金牌,后来才明白它是带使用契约的:必要场景开、退出就关。能力给了不代表可以随便用,系统对滥用有反制。

坑 8:能调不等于改了全局——四能力边界收口时差点写成「亮度需要权限」。 整理 CAP_INTERACT_MATRIX 那四条说明时,我顺手差点给「屏幕亮度」也标个 err: 1007:

// 一开始的错误归类
{ name: '屏幕亮度', ..., err: '1004 / 1007' }   // 1007 是权限被拒,亮度根本用不上

四个能力摆一起才看清:日历是 user_grant 弹窗、声音是 provisionEnable: False 受限、通知是应用开关、亮度是完全无需权限的公开 API。亮度的 err 实际是 1004 needsDevice(Web 端)和 1001(参数错),一次 1007 都没回过。别把「相邻能力的错误码」顺手抄过来,边界是逐个能力核出来的,不是套模板套出来的。


7. 现在怎么用:从 Demo 到真机

构建命令(本机验证过的那条):

cd /storage/Users/currentUser/Documents/DevEcoStudioProjects/tauri-hello
export DEVECO_SDK_HOME=/storage/Users/currentUser/WorkBuddy/2026-11-21-17-24-54/harmony-sdk-home
node /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/hvigor/bin/hvigorw.js \
  --mode module -p product=default assembleHap --no-daemon
# BUILD SUCCESSFUL in 11 s 783 ms(仅 WARN,无 ERROR)
# 产物:entry/build/default/outputs/default/entry-default-signed.hap(748020 字节)

签名用 DevEco 自动生成的调试材料(build-profile.json5 的 signingConfigs[0]),不进仓库。自测交代:7 个 JS node --check 全过、104 个 onclick 全导出、HTML 无重复 id;HAP 里 ets/modules.abc 校验过 4 个 interact.brightness.* 全在包、setWindowBrightness / getWindowProperties / setWindowKeepScreenOn 相关符号命中。真机验证顺序:保持应用窗口在前台有焦点,先点「读当前亮度」看 brightness: -1 / mode: 跟随系统,再点「设置亮度」输 0.9 直接看窗口变亮,然后「跟随系统」看它弹回、切出应用再切回验证覆盖失效,最后试「开启/关闭常亮」;DevEco 过滤 hilog DOMAIN 0x5504 看原生侧打印。

免得读者踩到同一堵墙,硬限制清单:

  • setWindowBrightness() 改的是本应用窗口,不是系统全局亮度;全局在 settings systemapi,普通 normal 应用够不着。
  • 只在窗口前台且有焦点时生效,只作用窗口所在的物理屏,不作用虚拟屏/投屏;窗口进后台设置失效。
  • -1 是「撤销覆盖、回系统亮度」的合法特殊值,不是负数亮度;它走独立的 followSystem case,不进 0~1 参数校验。
  • setBrightness() / setKeepScreenOn() 自 API 9 废弃,用 @useinstead 指向的 setWindowBrightness() / setWindowKeepScreenOn()。
  • 别在前后台切换时连着调 setWindowBrightness(),文档点名会出 timing issues。
  • 常亮只在导航/视频/绘图/游戏等必要场景开,退出设回 false,系统对非标准用法可能主动熄屏。
  • 窗口类错误看生命周期:1300002 窗口状态异常、1300003 窗口服务异常、401 参数错,都不是权限问题。
  • 浏览器预览改不了窗口亮度,interact.brightness.* 一律回 1004 needsDevice。

最开始我以为它是笔记本上那两个亮度键,一调整块屏幕都变、切到哪都跟着;现在我知道普通应用能碰的只是「自己这个窗口盖在某块物理屏上、正前台有焦点时」的一个临时覆盖值,窗口一走就还给系统,-1 是主动撤销,常亮还得守着使用场景的契约。四个真机交互能力里,亮度是唯一一个连权限表都不用查的,却也是最容易因为「名字像全局」而被误用的——它教我的不是怎么申请权限,而是先问清楚「这个 API 到底作用在哪一层」。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐