2026/9/16 7:18:22
FEATURED · 精选文章 
晚上关灯刷手机屏幕亮得刺眼——这个问题是能靠硬件解决的设备自带环境光传感器读出光照度界面跟着调主题和亮度就行。本文用一个真实可跑的示例工程把这个交互从头做一遍。用到的三方库是light_sensor3.0.2 的鸿蒙适配版它只有两个 API小到能一次讲完但足够撑起一个真正有价值的界面效果。环境准备本文不重复环境搭建步骤。Flutter for OpenHarmony SDK、DevEco Studio、模拟器/真机的完整配置见官方指引https://atomgit.com/CPF-Flutter/flutter_samples/blob/master/docs/ohos/getting-started/flutter-oh-env-setup.md一、接入按 TAG 引入适配版light_sensor的鸿蒙实现在 CPF-Flutter 组织下维护按 git TAG 引入即可。务必写死 TAG不要跟分支走否则上游一更新就可能把已验证过的组合冲掉dependencies:light_sensor:git:url:https://atomgit.com/CPF-Flutter/fluttertpc_light_sensor.gitref:3.0.2-ohos-1.0.0-beta.1flutter pub get这个库不需要任何权限。环境光传感器在鸿蒙上不涉及隐私数据宿主应用的module.json5里不用声明requestPermissions装完就能读。二、API 只有两个方法整个 Dart 层的对外接口就这些方法返回用途LightSensor.hasSensor()Futurebool设备有没有光线传感器LightSensor.luxStream()Streamint环境光照度数据流单位 LuxluxStream()推的是整数Lux不是小数——原生侧做了取整再上报所以 Dart 层的Streamint拿着就能直接用不用自己再转类型。三、先探针再订阅hasSensor()这一步别省。不是所有设备都有环境光传感器部分平板、车机、模拟器镜像就没有不检测直接listen的话拿到的就是一个永远不吐数据的流界面上表现为一直转圈很难查。Futurevoid_bootstrap()async{finalbool hasSensorawaitLightSensor.hasSensor();if(!mounted){return;}setState(()_hasSensorhasSensor);if(!hasSensor){return;// 没传感器就别订阅直接给提示}_subscriptionLightSensor.luxStream().listen(_onLux);}hasSensor()和下面要订阅的luxStream()是两条独立的通道前者走 MethodChannel、后者走 EventChannel互不影响——所以能检测到传感器和能收到数据要分别验证不能拿其中一个的成败去推断另一个。四、把 Lux 变成界面先分档原始的光照度是个连续整数从 0 到几万直接拿来做 UI 判断会很难写。中间加一层档位代码就清爽了enumLightLevel{pitchDark(漆黑,0,10),dim(昏暗,10,100),indoor(室内,100,1000),bright(明亮,1000,10000),glaring(强光,10000,130);constLightLevel(this.label,this.min,this.max);finalStringlabel;finalint min;finalint max;staticLightLevelof(int lux){for(finallevelinvalues){if(luxlevel.minluxlevel.max){returnlevel;}}returnglaring;}}档位区间不用纠结精确数值参考量级就够10 Lux 以下是几乎全黑100 左右是昏暗的室内几百到一千是普通室内照明一万以上是户外强光或直射灯下。分完档再给每档挂一套配色和一个建议屏幕亮度_LevelStylegetstyle{switch(this){caseLightLevel.pitchDark:returnconst_LevelStyle(pageBackground:Color(0xFF0B0B0D),foreground:Color(0xFFE8E8EA),suggestedBrightness:0.12,tip:环境很暗界面转深色并压低亮度减少刺眼,);caseLightLevel.indoor:returnconst_LevelStyle(pageBackground:Color(0xFFF3F4F7),foreground:Color(0xFF1B1D21),suggestedBrightness:0.55,tip:常见室内光用浅色主题、正常亮度即可,);// …其余三档同理}}五、订阅与释放订阅本身没什么特别的但有两处必须写全。第一回调里要判mounted。传感器的回调来自原生侧到达时机不受页面控制_subscriptionLightSensor.luxStream().listen((int lux){if(!mounted){return;}setState((){_luxlux;_history.add(lux);if(_history.length48){_history.removeAt(0);// 只留最近 48 个采样用来画趋势}});},onError:(Objecterror,StackTrace_){if(!mounted){return;}setState(()_error光照数据流中断$error);},);第二dispose里必须cancel()。传感器是长连接不取消的话页面销毁后回调继续打过来setState直接抛异常overridevoiddispose(){_subscription?.cancel();super.dispose();}onError也建议带上。原生侧读传感器失败时会往流里发错误不接的话就是一个未处理的异步异常。顺带一提这个流的上报间隔大约是 100 ms也就是每秒十次重建。对一个只显示读数的界面完全够用如果要在回调里做重活比如实时算平均值、写日志建议自己加一层节流别在每个事件里都干重活。六、实测模拟器上注入光照看界面反应鸿蒙模拟器支持直接注入光照度所以这个库的自适应效果在模拟器上就能完整验证不依赖真机的物理传感器。验证环境是 Flutter for OpenHarmony SDK3.44.9ohos-0.0.1-canary1 DevEco Studio 26.0.0.621API 26Pura X View模拟器HarmonyOS 7.0.0(26.0.0) Beta2ohos-x64。devecocli emulator sensor--targetPura X View--light-intensity320分别在三个档位注入界面给出的判定和建议亮度如下注入光照度界面读数判定档位建议屏幕亮度页面配色4242 Lux昏暗30%深色R21 G22 B26320320 Lux室内55%浅色R243 G244 B2473000030000 Lux强光100%暖白R255 G248 B230配色那一列是截屏后采样页面背景得到的实际像素值——深色和暖白差了非常多说明主题确实跟着环境光换了不是只改了个文案。顺带说一句模拟器里这个传感器默认读数是 0。第一次跑起来看到界面直接进漆黑档会以为是渲染坏了其实是环境光没注入——用上面那条命令给个值就正常了。七、已知限制档位阈值是主观的。上面那张表是按常见场景定的不同应用该有自己的标准比如阅读类可以更保守工具类可以更激进。插件只负责给 Lux怎么用是应用的事。光照度变化是异步的。从关灯到界面变色有一次传感器上报的延迟别指望零延迟响应。示例里的界面切换都加了 300 ms 的动画过渡避免忽明忽暗闪一下。不是所有设备都有这个传感器。所以第三节那个hasSensor()探针必须有并且要给没有传感器的降级路径——没有光感就退回到用户手动设置的主题。示例不会真的改系统亮度。界面上显示的建议屏幕亮度是按档位算出来的展示值没有去调系统背光——真去改要走窗口/背光相关接口属于另一个库的职责。八、常见问题Q怎么证明主题真的变了而不是换个文案糊弄A截屏后直接采样页面背景像素。三档分别是R21 G22 B26深色、R243 G244 B247浅色、R255 G248 B230暖白——这是像素级的证据文案改了但颜色没改是做不出这个差别的。Q为什么第一次跑起来界面直接是漆黑色A模拟器的光感默认读数为 00 Lux正好落在漆黑档0–10。这不是渲染坏了注入一个光照度就正常devecocli emulator sensor --target Pura X View --light-intensity 320。Q能不能不要hasSensor()直接订阅A可以跑但会留一个很难查的坑。没有传感器时luxStream()既不报错也不吐数据界面表现是一直转圈而且没有任何日志能告诉你原因。hasSensor()就是用来把这种情况提前分流的。Q100 ms 一次太频繁了吗会不会掉帧A只显示读数不掉帧。但要注意每次事件都会触发一次setState也就是每秒十次重建。如果这一屏结构很重要么把 UI 抽成独立的小 widget 缩小重建范围要么自己加节流。QsuggestedBrightness显示的 30% / 55% / 100% 会真的调屏幕背光吗A不会。它只是示例算出来的建议值。真要调背光得用窗口/背光相关接口跟读光感是两件事。Q这个库需要申请权限吗真机上会不会弹授权框A不需要。环境光不属于隐私数据module.json5里不用声明requestPermissions真机上也不会弹框。Q模拟器验证过就够了还需要真机吗A建议补真机。模拟器是注入什么就读什么能验证通道和映射逻辑真机能验证物理传感器的响应速度、量程和实际手感比如傍晚开灯时的过渡是否自然。小结这个库只有两个方法但把如何用好一个传感器插件的要点都覆盖到了先探针再订阅——hasSensor()确认设备真的有能力再开流分档再映射——连续值直接驱动 UI 会很难维护中间加一层档位订阅要成套——回调判mounted、流带onError、dispose里cancel模拟器能验——鸿蒙模拟器可注入光照度自适应效果不用等真机。示例工程light_adaptive_demo完整实现了上面这套一个自适应阅读页当前光照度卡片 自适应预览 建议亮度条 最近采样趋势条。本篇用到的库项内容三方库light_sensor上游 3.0.2 的鸿蒙适配版适配仓库https://atomgit.com/CPF-Flutter/fluttertpc_light_sensor适配 TAG3.0.2-ohos-1.0.0-beta.1示例工程light_adaptive_demodependencies:light_sensor:git:url:https://atomgit.com/CPF-Flutter/fluttertpc_light_sensor.gitref:3.0.2-ohos-1.0.0-beta.1验证环境项版本Flutter for OpenHarmony SDK3.44.9ohos-0.0.1-canary1Dart3.12.2DevEco Studio26.0.0.621API 26设备HarmonyOS 7.0.0(26.0.0) Beta2 模拟器Pura X Viewohos-x64欢迎加入 CPF-Flutter 鸿蒙社区https://atomgit.com/CPF-FlutterFlutter 三方库鸿蒙适配清单https://atomgit.com/oh-flutter/flutter-ohos-adaptation-checklist
Flutter for OpenHarmony 实战：用 light_sensor 做随环境光变化的自适应界面
晚上关灯刷手机屏幕亮得刺眼——这个问题是能靠硬件解决的设备自带环境光传感器读出光照度界面跟着调主题和亮度就行。本文用一个真实可跑的示例工程把这个交互从头做一遍。用到的三方库是light_sensor3.0.2 的鸿蒙适配版它只有两个 API小到能一次讲完但足够撑起一个真正有价值的界面效果。环境准备本文不重复环境搭建步骤。Flutter for OpenHarmony SDK、DevEco Studio、模拟器/真机的完整配置见官方指引https://atomgit.com/CPF-Flutter/flutter_samples/blob/master/docs/ohos/getting-started/flutter-oh-env-setup.md一、接入按 TAG 引入适配版light_sensor的鸿蒙实现在 CPF-Flutter 组织下维护按 git TAG 引入即可。务必写死 TAG不要跟分支走否则上游一更新就可能把已验证过的组合冲掉dependencies:light_sensor:git:url:https://atomgit.com/CPF-Flutter/fluttertpc_light_sensor.gitref:3.0.2-ohos-1.0.0-beta.1flutter pub get这个库不需要任何权限。环境光传感器在鸿蒙上不涉及隐私数据宿主应用的module.json5里不用声明requestPermissions装完就能读。二、API 只有两个方法整个 Dart 层的对外接口就这些方法返回用途LightSensor.hasSensor()Futurebool设备有没有光线传感器LightSensor.luxStream()Streamint环境光照度数据流单位 LuxluxStream()推的是整数Lux不是小数——原生侧做了取整再上报所以 Dart 层的Streamint拿着就能直接用不用自己再转类型。三、先探针再订阅hasSensor()这一步别省。不是所有设备都有环境光传感器部分平板、车机、模拟器镜像就没有不检测直接listen的话拿到的就是一个永远不吐数据的流界面上表现为一直转圈很难查。Futurevoid_bootstrap()async{finalbool hasSensorawaitLightSensor.hasSensor();if(!mounted){return;}setState(()_hasSensorhasSensor);if(!hasSensor){return;// 没传感器就别订阅直接给提示}_subscriptionLightSensor.luxStream().listen(_onLux);}hasSensor()和下面要订阅的luxStream()是两条独立的通道前者走 MethodChannel、后者走 EventChannel互不影响——所以能检测到传感器和能收到数据要分别验证不能拿其中一个的成败去推断另一个。四、把 Lux 变成界面先分档原始的光照度是个连续整数从 0 到几万直接拿来做 UI 判断会很难写。中间加一层档位代码就清爽了enumLightLevel{pitchDark(漆黑,0,10),dim(昏暗,10,100),indoor(室内,100,1000),bright(明亮,1000,10000),glaring(强光,10000,130);constLightLevel(this.label,this.min,this.max);finalStringlabel;finalint min;finalint max;staticLightLevelof(int lux){for(finallevelinvalues){if(luxlevel.minluxlevel.max){returnlevel;}}returnglaring;}}档位区间不用纠结精确数值参考量级就够10 Lux 以下是几乎全黑100 左右是昏暗的室内几百到一千是普通室内照明一万以上是户外强光或直射灯下。分完档再给每档挂一套配色和一个建议屏幕亮度_LevelStylegetstyle{switch(this){caseLightLevel.pitchDark:returnconst_LevelStyle(pageBackground:Color(0xFF0B0B0D),foreground:Color(0xFFE8E8EA),suggestedBrightness:0.12,tip:环境很暗界面转深色并压低亮度减少刺眼,);caseLightLevel.indoor:returnconst_LevelStyle(pageBackground:Color(0xFFF3F4F7),foreground:Color(0xFF1B1D21),suggestedBrightness:0.55,tip:常见室内光用浅色主题、正常亮度即可,);// …其余三档同理}}五、订阅与释放订阅本身没什么特别的但有两处必须写全。第一回调里要判mounted。传感器的回调来自原生侧到达时机不受页面控制_subscriptionLightSensor.luxStream().listen((int lux){if(!mounted){return;}setState((){_luxlux;_history.add(lux);if(_history.length48){_history.removeAt(0);// 只留最近 48 个采样用来画趋势}});},onError:(Objecterror,StackTrace_){if(!mounted){return;}setState(()_error光照数据流中断$error);},);第二dispose里必须cancel()。传感器是长连接不取消的话页面销毁后回调继续打过来setState直接抛异常overridevoiddispose(){_subscription?.cancel();super.dispose();}onError也建议带上。原生侧读传感器失败时会往流里发错误不接的话就是一个未处理的异步异常。顺带一提这个流的上报间隔大约是 100 ms也就是每秒十次重建。对一个只显示读数的界面完全够用如果要在回调里做重活比如实时算平均值、写日志建议自己加一层节流别在每个事件里都干重活。六、实测模拟器上注入光照看界面反应鸿蒙模拟器支持直接注入光照度所以这个库的自适应效果在模拟器上就能完整验证不依赖真机的物理传感器。验证环境是 Flutter for OpenHarmony SDK3.44.9ohos-0.0.1-canary1 DevEco Studio 26.0.0.621API 26Pura X View模拟器HarmonyOS 7.0.0(26.0.0) Beta2ohos-x64。devecocli emulator sensor--targetPura X View--light-intensity320分别在三个档位注入界面给出的判定和建议亮度如下注入光照度界面读数判定档位建议屏幕亮度页面配色4242 Lux昏暗30%深色R21 G22 B26320320 Lux室内55%浅色R243 G244 B2473000030000 Lux强光100%暖白R255 G248 B230配色那一列是截屏后采样页面背景得到的实际像素值——深色和暖白差了非常多说明主题确实跟着环境光换了不是只改了个文案。顺带说一句模拟器里这个传感器默认读数是 0。第一次跑起来看到界面直接进漆黑档会以为是渲染坏了其实是环境光没注入——用上面那条命令给个值就正常了。七、已知限制档位阈值是主观的。上面那张表是按常见场景定的不同应用该有自己的标准比如阅读类可以更保守工具类可以更激进。插件只负责给 Lux怎么用是应用的事。光照度变化是异步的。从关灯到界面变色有一次传感器上报的延迟别指望零延迟响应。示例里的界面切换都加了 300 ms 的动画过渡避免忽明忽暗闪一下。不是所有设备都有这个传感器。所以第三节那个hasSensor()探针必须有并且要给没有传感器的降级路径——没有光感就退回到用户手动设置的主题。示例不会真的改系统亮度。界面上显示的建议屏幕亮度是按档位算出来的展示值没有去调系统背光——真去改要走窗口/背光相关接口属于另一个库的职责。八、常见问题Q怎么证明主题真的变了而不是换个文案糊弄A截屏后直接采样页面背景像素。三档分别是R21 G22 B26深色、R243 G244 B247浅色、R255 G248 B230暖白——这是像素级的证据文案改了但颜色没改是做不出这个差别的。Q为什么第一次跑起来界面直接是漆黑色A模拟器的光感默认读数为 00 Lux正好落在漆黑档0–10。这不是渲染坏了注入一个光照度就正常devecocli emulator sensor --target Pura X View --light-intensity 320。Q能不能不要hasSensor()直接订阅A可以跑但会留一个很难查的坑。没有传感器时luxStream()既不报错也不吐数据界面表现是一直转圈而且没有任何日志能告诉你原因。hasSensor()就是用来把这种情况提前分流的。Q100 ms 一次太频繁了吗会不会掉帧A只显示读数不掉帧。但要注意每次事件都会触发一次setState也就是每秒十次重建。如果这一屏结构很重要么把 UI 抽成独立的小 widget 缩小重建范围要么自己加节流。QsuggestedBrightness显示的 30% / 55% / 100% 会真的调屏幕背光吗A不会。它只是示例算出来的建议值。真要调背光得用窗口/背光相关接口跟读光感是两件事。Q这个库需要申请权限吗真机上会不会弹授权框A不需要。环境光不属于隐私数据module.json5里不用声明requestPermissions真机上也不会弹框。Q模拟器验证过就够了还需要真机吗A建议补真机。模拟器是注入什么就读什么能验证通道和映射逻辑真机能验证物理传感器的响应速度、量程和实际手感比如傍晚开灯时的过渡是否自然。小结这个库只有两个方法但把如何用好一个传感器插件的要点都覆盖到了先探针再订阅——hasSensor()确认设备真的有能力再开流分档再映射——连续值直接驱动 UI 会很难维护中间加一层档位订阅要成套——回调判mounted、流带onError、dispose里cancel模拟器能验——鸿蒙模拟器可注入光照度自适应效果不用等真机。示例工程light_adaptive_demo完整实现了上面这套一个自适应阅读页当前光照度卡片 自适应预览 建议亮度条 最近采样趋势条。本篇用到的库项内容三方库light_sensor上游 3.0.2 的鸿蒙适配版适配仓库https://atomgit.com/CPF-Flutter/fluttertpc_light_sensor适配 TAG3.0.2-ohos-1.0.0-beta.1示例工程light_adaptive_demodependencies:light_sensor:git:url:https://atomgit.com/CPF-Flutter/fluttertpc_light_sensor.gitref:3.0.2-ohos-1.0.0-beta.1验证环境项版本Flutter for OpenHarmony SDK3.44.9ohos-0.0.1-canary1Dart3.12.2DevEco Studio26.0.0.621API 26设备HarmonyOS 7.0.0(26.0.0) Beta2 模拟器Pura X Viewohos-x64欢迎加入 CPF-Flutter 鸿蒙社区https://atomgit.com/CPF-FlutterFlutter 三方库鸿蒙适配清单https://atomgit.com/oh-flutter/flutter-ohos-adaptation-checklist 
