Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 is_lock

Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 is_lock_screen2

判断设备当前是否处于锁屏或屏幕熄灭状态。

本文以is_lock_screen2 2.1.0为例，记录我如何保留原有 Dart API、补齐 Flutter OH 插件入口、在鸿蒙端接入真实系统能力，并在 HarmonyOS API 26 真机上完成构建、安装、启动与调用验证。

适配仓库：is_lock_screen2

适配分支：feat/ohos_is_lock_screen2_2.1.0

适配 TAG：2.1.0-ohos.1

一、先看最终效果

图 1：HarmonyOS API 26 真机启动示例页

图 2：点击读取后的真实返回值

验证点	实测结果
Flutter OH 3.47 工程构建	通过，产出`entry-default-signed.hap`
安装、启动（真机）	通过
点击「读取锁屏状态」	`isLockScreen() = false`
与设备实际状态对照	屏幕点亮且已解锁，返回 false 一致

二、这个库原来是怎么工作的

上游is_lock_screen2通过平台通道与原生侧通信，通道定义在 Dart 源码里，原生侧只需要注册同名通道并实现方法分发，Dart 代码一行都不用改。

MethodChannel('is_lock_screen') -> isLockScreen

三、实际环境

Flutter 鸿蒙环境搭建不在本文重复展开，直接参考 Flutter OH 环境搭建指南。

组件	版本
Flutter OH	`3.47.4-ohos-1.0.4`
Dart	`3.13.3`
DevEco Studio	`26.0.0 Release`
HarmonyOS SDK	API 26
测试设备	华为畅享 90 Pro Max（CHZ-AL00），HarmonyOS`7.0.0.109`（API 26）
目标库	`is_lock_screen2 2.1.0`

flutter--versionhdc list targets

这里要特别注意 Flutter 版本：本机同时装了3.41和3.47.4-ohos，3.41会因为 SDK 约束解析失败，构建时必须显式把3.47.4-ohos放到 PATH 前面。

四、确认上游版本并同步到 AtomGit

上游包地址是 https://github.com/Wing-Li/flutter_is_lock_screen2，版本2.1.0使用 MIT License。适配前我用 AtomGit API（GET /api/v5/repos/<org>/<lib>）在oh-flutter、hxa-flutter、CPF-Flutter三个组织做了排重，未发现同名 OHOS 实现。

gitclone https://atomgit.com/oh-flutter/is_lock_screen2.gitcdis_lock_screen2gitswitch feat/ohos_is_lock_screen2_2.1.0gitlog--oneline-5

五、创建适配分支并检查工程结构

gitswitch-cfeat/ohos_is_lock_screen2_2.1.0

关键目录如下：

is_lock_screen2/ ├── lib/ # 原有 Dart API 和通道 ├── ohos/ │ ├── index.ets # OHOS 插件导出入口 │ └── src/main/ets/components/plugin/ │ └── IsLockScreen2Plugin.ets ├── example/lib/main.dart # 真机验证 Demo ├── example/ohos/ # Flutter OH 宿主工程 ├── pubspec.yaml # 声明 ohos 平台 └── README.OpenHarmony_CN.md # 鸿蒙适配说明

flutter:plugin:platforms:ohos:pluginClass:IsLockScreen2Plugin

pluginClass必须和ohos/index.ets导出的类名一致。这一步是本批次最容易踩的坑：pubspec.yaml里漏掉ohos声明时，Flutter 生成的GeneratedPluginRegistrant.ets是个空try块，Dart 侧调用直接返回null，构建期没有任何报错，运行时也不抛MissingPluginException，只是所有返回值都是空的。我第一次跑is_lock_screen2就卡在这里，查了半天日志才发现注册表是空的。

六、适配过程：注册通道并对齐语义

通道名必须与上游 Dart 源码逐字一致。本库的映射如下：

方法	OpenHarmony 实现	说明
`isLockScreen`	`display.getDefaultDisplaySync().state`+ `screenLock.isScreenLocked()	yes

核心代码：

privateisLockScreen(result:MethodResult):void{letscreenOn:boolean;try{constd:display.Display=display.getDefaultDisplaySync();screenOn=d.state===display.DisplayState.STATE_ON;}catch(error){conste=errorasBusinessError;result.error('SCREEN_STATE_UNAVAILABLE',`read display state failed:${e.message}`,null);return;}if(!screenOn){result.success(true);return;}screenLock.isScreenLocked().then((locked:boolean)=>{result.success(locked);}).catch((error:BusinessError)=>{// 缺少权限或系统不支持：屏幕已点亮，按未锁定返回，不伪造 trueresult.success(false);});}

先判屏幕点亮（不需要权限），再异步查锁屏态。屏幕熄灭时直接返回true，省掉一次可能因缺权限而失败的调用。

七、构建配置与签名

示例工程的目标 SDK 对齐到 26，与@ohos/flutter_ohos的要求一致：

{ "name": "default", "compatibleSdkVersion": "26.0.0", "targetSdkVersion": "26.0.0", "runtimeOS": "HarmonyOS" }

Demo 的AppScope/app.json5统一成com.example.flutter_oh_demo。签名 profile 里绑定的 bundleName 必须与它一致，否则SignHap直接报00303074 Configuration Error。证书、p12、p7b 和密码不提交到仓库。

另外两个和签名、SDK 相关的坑：

build-profile.json5里签名材料写${HOME}不会展开，必须是绝对路径，否则报00303107 Invalid storeFile value。
DEVECO_SDK_HOME要指向Contents/sdk（含版本目录的上一级）。指到sdk/default报00303312 Cannot find the corresponding SDK version，完全不设则报00303217。

八、通过 AtomGit 引入适配版

在业务工程中使用时锁定 TAG：

dependencies:is_lock_screen2:git:url:https://atomgit.com/oh-flutter/is_lock_screen2.gitref:2.1.0-ohos.1

flutter pub get

然后在pubspec.lock里确认source: git、AtomGit 地址和resolved-ref，避免解析到 pub.dev 的同名版本。

九、构建、安装和真机验证

cdexample flutter pub get flutter build hap--debughdcinstall-rbuild/ohos/hap/entry-default-signed.hap hdc shell aa start-aEntryAbility-bcom.example.flutter_oh_demo

构建输出为✓ Built build/ohos/hap/entry-default-signed.hap.，随后hdc报告安装成功。所有示例共用同一个 bundleName，重装后要先aa force-stop再aa start，否则系统只是把旧任务拉到前台，看到的是上一次安装的界面——这个现象在批量验证时骗过我一次。

取实测值时用uitest定位控件并点击，而不是靠肉眼判断：

hdc shell"uitest dumpLayout -p /data/local/tmp/l.json"hdcfilerecv /data/local/tmp/l.json /tmp/l.json hdc shell"uitest uiInput click <x> <y>"hdc shell"uitest screenCap -p /data/local/tmp/s.png"

十、适配结果和当前边界

鸿蒙的screenLock.isScreenLocked()需要ohos.permission.PRIVACY_WINDOW。未授予时该调用 reject，本实现按「屏幕已点亮即视为未锁定」返回false，因此无法区分「已解锁」与「无法查询锁屏态」两种情况。

十一、FAQ

Q1：为什么屏幕点亮时返回 false，而不是真实锁屏状态？

原因：screenLock.isScreenLocked()需要ohos.permission.PRIVACY_WINDOW。未授予时该调用 reject，实现捕获异常后按「屏幕已点亮即视为未锁定」返回false。
验证结果：真机上isLockScreen() = false，与设备解锁状态一致。

Q2：屏幕熄灭时怎么判断？

原因：直接读display.getDefaultDisplaySync().state，等于DisplayState.STATE_ON才算点亮。熄灭时必然处于不可用状态，直接返回true，不再查锁屏态。
验证结果：该分支不需要任何权限，是鸿蒙上最可靠的判断依据。

Q3：为什么 isScreenLocked 要写成 then/catch 而不是同步调用？

原因：SDK 只提供 Promise 版本，没有同步接口。实现里用then/catch保证result.success只在异步完成后调用一次，避免 Dart 侧收到两次结果。

十二、总结

is_lock_screen2 2.1.0在鸿蒙上已经接入真实系统能力，Dart 侧 API 与上游保持一致。本文的验证结果全部来自 HarmonyOS API 26 真机，没有占位返回值；平台本身不具备的能力在正文和 README 中都标注为边界。

十三、参考资料和仓库地址

适配仓库主页
适配分支
适配 TAG
ArkTS 通道实现
鸿蒙适配说明
pub.dev 包页面
pub.dev 2.1.0 版本页
上游仓库
Flutter 官方平台通道文档
Flutter OH 鸿蒙 SDK 仓库
HarmonyOS 开发者官方文档

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

企业官网建设流程全解析