Flutter for OpenHarmony 实战：用 light_sensor 做随环境光变化的自适应界面

晚上关灯刷手机，屏幕亮得刺眼——这个问题是能靠硬件解决的：设备自带环境光传感器，读出光照度，界面跟着调主题和亮度就行。

本文用一个真实可跑的示例工程，把这个交互从头做一遍。用到的三方库是light_sensor（3.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.1

flutter pub get

这个库不需要任何权限。环境光传感器在鸿蒙上不涉及隐私数据，宿主应用的module.json5里不用声明requestPermissions，装完就能读。

二、API 只有两个方法

整个 Dart 层的对外接口就这些：

luxStream()推的是整数Lux，不是小数——原生侧做了取整再上报，所以 Dart 层的Stream<int>拿着就能直接用，不用自己再转类型。

三、先探针再订阅

hasSensor()这一步别省。不是所有设备都有环境光传感器（部分平板、车机、模拟器镜像就没有），不检测直接listen的话，拿到的就是一个永远不吐数据的流，界面上表现为"一直转圈"，很难查。

Future<void>_bootstrap()async{finalbool hasSensor=awaitLightSensor.hasSensor();if(!mounted){return;}setState(()=>_hasSensor=hasSensor);if(!hasSensor){return;// 没传感器就别订阅，直接给提示}_subscription=LightSensor.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,1<<30);constLightLevel(this.label,this.min,this.max);finalStringlabel;finalint min;finalint max;staticLightLevelof(int lux){for(finallevelinvalues){if(lux>=level.min&&lux<level.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。传感器的回调来自原生侧，到达时机不受页面控制：

_subscription=LightSensor.luxStream().listen((int lux){if(!mounted){return;}setState((){_lux=lux;_history.add(lux);if(_history.length>48){_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.9+ohos-0.0.1-canary1+ DevEco Studio 26.0.0.621（API 26）+Pura X View模拟器（HarmonyOS 7.0.0(26.0.0) Beta2，ohos-x64）。

devecocli emulator sensor--target"Pura X View"--light-intensity320

分别在三个档位注入，界面给出的判定和建议亮度如下：

配色那一列是截屏后采样页面背景得到的实际像素值——深色和暖白差了非常多，说明主题确实跟着环境光换了，不是只改了个文案。

顺带说一句：模拟器里这个传感器默认读数是 0。第一次跑起来看到界面直接进"漆黑"档，会以为是渲染坏了，其实是环境光没注入——用上面那条命令给个值就正常了。

七、已知限制

• 档位阈值是主观的。上面那张表是按常见场景定的，不同应用该有自己的标准（比如阅读类可以更保守，工具类可以更激进）。插件只负责给 Lux，怎么用是应用的事。
• 光照度变化是异步的。从关灯到界面变色有一次传感器上报的延迟，别指望"零延迟响应"。示例里的界面切换都加了 300 ms 的动画过渡，避免忽明忽暗闪一下。
• 不是所有设备都有这个传感器。所以第三节那个hasSensor()探针必须有，并且要给"没有传感器"的降级路径——没有光感就退回到用户手动设置的主题。
• 示例不会真的改系统亮度。界面上显示的"建议屏幕亮度"是按档位算出来的展示值，没有去调系统背光——真去改要走窗口/背光相关接口，属于另一个库的职责。

八、常见问题

Q：怎么证明主题真的变了，而不是换个文案糊弄？
A：截屏后直接采样页面背景像素。三档分别是R21 G22 B26（深色）、R243 G244 B247（浅色）、R255 G248 B230（暖白）——这是像素级的证据，文案改了但颜色没改是做不出这个差别的。

Q：为什么第一次跑起来界面直接是漆黑色？
A：模拟器的光感默认读数为 0，0 Lux正好落在"漆黑"档（0–10）。这不是渲染坏了，注入一个光照度就正常：devecocli emulator sensor --target "Pura X View" --light-intensity 320。

Q：能不能不要hasSensor()，直接订阅？
A：可以跑，但会留一个很难查的坑。没有传感器时luxStream()既不报错也不吐数据，界面表现是"一直转圈"，而且没有任何日志能告诉你原因。hasSensor()就是用来把这种情况提前分流的。

Q：100 ms 一次太频繁了吗？会不会掉帧？
A：只显示读数不掉帧。但要注意每次事件都会触发一次setState，也就是每秒十次重建。如果这一屏结构很重，要么把 UI 抽成独立的小 widget 缩小重建范围，要么自己加节流。

Q：suggestedBrightness显示的 30% / 55% / 100% 会真的调屏幕背光吗？
A：不会。它只是示例算出来的建议值。真要调背光得用窗口/背光相关接口，跟读光感是两件事。

Q：这个库需要申请权限吗？真机上会不会弹授权框？
A：不需要。环境光不属于隐私数据，module.json5里不用声明requestPermissions，真机上也不会弹框。

Q：模拟器验证过就够了，还需要真机吗？
A：建议补真机。模拟器是"注入什么就读什么"，能验证通道和映射逻辑；真机能验证物理传感器的响应速度、量程和实际手感（比如傍晚开灯时的过渡是否自然）。

小结

这个库只有两个方法，但把"如何用好一个传感器插件"的要点都覆盖到了：

• 先探针再订阅——hasSensor()确认设备真的有能力，再开流；
• 分档再映射——连续值直接驱动 UI 会很难维护，中间加一层档位；
• 订阅要成套——回调判mounted、流带onError、dispose里cancel；
• 模拟器能验——鸿蒙模拟器可注入光照度，自适应效果不用等真机。

示例工程light_adaptive_demo完整实现了上面这套：一个自适应阅读页（当前光照度卡片 + 自适应预览 + 建议亮度条 + 最近采样趋势条）。

本篇用到的库

dependencies:light_sensor:git:url:https://atomgit.com/CPF-Flutter/fluttertpc_light_sensor.gitref:3.0.2-ohos-1.0.0-beta.1

验证环境

欢迎加入 CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter

Flutter 三方库鸿蒙适配清单：https://atomgit.com/oh-flutter/flutter-ohos-adaptation-checklist