Flutter应用锁库在OpenHarmony上的适配实践与关键技术拆解-代码聚汇网

1. secure_application 是什么，为什么要在 OpenHarmony 上折腾它

先讲结论：secure_application 是一个专门用来给 Flutter 应用加“应用锁”的三方库。它的核心能力就是当你把 App 切到后台再回来时，自动弹出一个指纹验证、人脸验证或者 PIN 码页面，验证通过才能继续使用。这个场景在银行类 App、企业办公类 App、或者你不想让别人随便翻你手机里某个 App 内容的时候特别常见。

我最早是在 Android 项目里用它，当时就是图它接入简单——不用自己维护 Activity 生命周期，不用手动监听 onPause/onResume，库内部全部帮你处理好了。后来 Flutter 项目变多，发现这个库对 Flutter 的支持也挺成熟，于是就一直沿用了。

但这玩意儿在 OpenHarmony 上就不一样了。

OpenHarmony 虽然生态上兼容 Flutter，但毕竟不是 Android。它没有 Android 那套 Activity 生命周期模型，也没有现成的 FingerprintManager、BiometricPrompt 这些 API。三方库如果要跑在 OpenHarmony 上，就得有人先做一层适配，把原有的 Android/iOS 平台实现替换成 OpenHarmony 自己的系统能力实现。

这里的“适配”不是说改改配置文件、换几个类名就能搞定，而是要把插件底层的平台通道（Platform Channel）实现重写，对接 OpenHarmony 的生物识别 API、应用生命周期事件、以及 UI 弹窗能力。

也正是因为这一步工作量不小，所以目前市面上大部分 Flutter 三方库在 OpenHarmony 上要么不可用，要么只能实现一部分功能。secure_application 的适配示例工程，就是给所有想把这套能力搬到 OpenHarmony 上的开发者做的一个参考样板。

这篇文章我会把这个示例应用从里到外拆开讲清楚，包括整体架构、适配思路、关键代码解读、常见坑点，以及我在实际调试过程中总结的一些经验。如果你是做 Flutter 开发、又恰好对 OpenHarmony 感兴趣，或者正在给自己的应用做 OpenHarmony 适配，这篇内容应该能帮你在路上省下不少时间。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 示例应用的整体设计与架构拆解

2.1 OpenHarmony 适配后的整体架构

如果一个 Flutter 项目要跑在 OpenHarmony 上，它的架构大概可以理解成三层：

最上层是 Flutter 应用层，也就是你的 Dart 代码，跟 Android/iOS 上完全一样，几乎不用改。
中间是 Flutter 引擎层，这层由 OpenHarmony 的 Flutter SDK 提供，相当于把 Flutter 的 C++ 引擎和 Dart 运行时跑在了 OpenHarmony 系统上。
最底层是平台能力层，也就是原来的 Android 原生代码、iOS 原生代码，在 OpenHarmony 上要替换成基于 ArkTS/Stage 模型写的原生代码。

secure_application 的适配工程，重点就是把原来位于第三层的平台实现重写了一遍。

在 Android 上，secure_application 的核心逻辑是：通过监听 MainActivity 的 onPause 和 onResume 生命周期回调，在 onPause 时记录“应用进入后台”，在 onResume 时判断是否需要弹出验证页面。验证页面本身是一个 Native 的 Dialog 或者 Activity。

在 OpenHarmony 上，这个逻辑就要改成：通过监听 UIAbility 的 onBackground 和 onForeground 事件，记录前后台切换状态；验证页面则要基于 OpenHarmony 的 ArkUI 组件或者自定义弹窗来实现。

如果你去看这个适配示例的目录结构，会发现它跟普通的 Flutter 插件工程很像，但是原生代码目录从 android/、ios/ 变成了 ohos/，里面是典型的 OpenHarmony 模块结构：

code复制secure_application/
├── lib/                    # Dart 层代码
│   └── secure_application.dart
├── ohos/                   # OpenHarmony 平台实现
│   ├── build-profile.json5
│   ├── entry/
│   │   ├── src/main/
│   │   │   ├── ets/
│   │   │   │   ├── entryability/
│   │   │   │   └── pages/
│   │   │   └── module.json5
│   └── secure_application_plugin/
│       └── src/main/
│           ├── ets/
│           │   └── SecureApplicationPlugin.ets
│           └── index.ets
└── pubspec.yaml

Dart 层保持了原库的 API 不变，这样业务方在 Flutter 层写的代码一行都不用改。真正的适配工作全部集中在 ohos 目录下的原生代码里，这也是整个项目最值得拆解的部分。

2.2 为什么 Dart 层可以几乎不动

这是设计得比较聪明的地方。

secure_application 的 Dart 层本质上只是做了两件事：

第一，向原生侧注册了一组 MethodChannel，用于调用原生能力。比如 listen、lock、unlock 这几个核心方法。

第二，处理从原生侧回调过来的一些状态事件，比如 background、foreground、authenticated 这些状态变化，Dart 层再通过这些状态去切换应用内显示的内容。

因为方法名和事件名是 Dart 层和原生层约定好的协议，只要 OpenHarmony 原生实现把同样的 MethodChannel 方法实现出来，并且用同样的事件名回调给 Dart 层，那么 Dart 层代码就完全感知不到底下跑的是 Android 还是 OpenHarmony。

这其实就是 Flutter 插件设计理念的体现：平台通道就是一座桥，桥这头的 Dart 代码只负责“发请求”和“收结果”，桥那头到底是谁在服务，它根本不在乎。

所以你在做 Flutter 三方库的 OpenHarmony 适配时，第一条原则就是：尽量保持 Dart 层协议不变，只重写平台层实现。这样，业务侧的项目就可以零成本切换到 OpenHarmony，不需要为了适配单独维护一套代码逻辑。

2.3 和 Android 实现相比，核心差异点在哪

Android 原版的 secure_application 实现里，最核心的一个类就是 SecureApplication，它是一个自定义的 Application 类，在 onCreate 里初始化一个 ActivityLifecycleCallbacks，通过它监听所有 Activity 的前后台切换。然后当检测到 App 回到前台时，它会启动一个透明的 Activity（也就是锁屏验证页），在这个 Activity 里调用系统生物识别或者弹出 PIN 输入界面。

OpenHarmony 上没有 Application 和 Activity 的一一对应关系。官方推荐的 UI 框架是 Stage 模型，一个应用可以有多个 UIAbility，但通常只有一个 MainAbility。生命周期事件也是挂在 UIAbility 上的，包括 onCreate、onWindowStageCreate、onForeground、onBackground、onDestroy 这几个关键回调。

所以适配实现里，需要把“监听 Activity 生命周期”换成“监听 UIAbility 生命周期”，把“启动透明的 Activity 作为验证页”换成“在当前页面上叠加一个全屏的验证弹窗”。

这个替换说起来就一句话，但实际做的时候牵涉到的细节还挺多的：比如透明 Activity 在 OpenHarmony 上对应的窗口模式要怎么处理、验证弹窗的层级要设置多高才能遮住 Flutter 渲染层、生命周期回调的时序跟 Android 是不是一致等等。

后面我会把这些细节一个个展开讲。

3. 核心适配细节与关键技术点

3.1 生命周期监听：从 ActivityLifecycleCallbacks 到 UIAbility 的 onBackground/onForeground

在 Android 上，ActivityLifecycleCallbacks 提供的是 onActivityPaused、onActivityResumed 这样的细粒度回调。而在 OpenHarmony 的 Stage 模型里，UIAbility 提供了 onBackground 和 onForeground 两个事件，分别对应“应用退到后台”和“应用回到前台”。

这两个事件基本上可以对应上 Android 的 onPause/onResume，但有一个微妙区别：Android 的 onPause 会在对话框弹出、息屏、甚至只是部分遮挡时触发；而 OpenHarmony 的 onBackground 只有在应用完全不可见时才触发。

这意味着如果你在 Android 上依赖 onPause + 延时判断来过滤“系统对话框弹出”这种场景，到了 OpenHarmony 上可能就不需要这个延时的 filter 逻辑了，因为 onBackground 本身就是更粗粒度的“完全不可见”事件。

实际适配代码大致长这样：

typescript复制export default class EntryAbility extends UIAbility {
  onBackground() {
    // 通知 Flutter 层：应用进入后台
    SecureApplicationPlugin.notifyBackground();
  }

  onForeground() {
    // 通知 Flutter 层：应用回到前台，需要校验是否锁定
    SecureApplicationPlugin.notifyForeground();
  }
}

这里有个比较关键的细节：SecureApplicationPlugin 需要能访问到 UIAbility 的上下文（Context），因为后续启动验证弹窗、调用生物识别都需要这个 Context。所以在 onWindowStageCreate 或者 onCreate 阶段，需要手动把 this.context 注入给插件类。还有一种做法是在插件注册的时候直接从 common.getContext() 拿，但那样有时拿到的是 common.UIAbilityContext，有时候拿到的是 common.ApplicationContext，识别逻辑得做对，否则后面调用 UI 能力会拿不到正确的窗口信息。

我后来直接把 context 通过入口 Ability 的 onCreate 传给插件，在插件里做一个静态变量存起来，命名上明确标注为 uiAbilityContext，避免和全局的 applicationContext 混淆。

3.2 验证页面的实现：不是新开页面，而是覆盖全屏的层

在 Android 原版实现中，当应用回到前台，需要弹出锁定页时，做法是启动一个新的透明 Activity。这个 Activity 的存在可以让系统认为“应用在前台”，同时它自己承担验证 UI 的展示职责。

OpenHarmony 的 Stage 模型里，虽然也支持启动新的 UIAbility，但如果你只是为了弹一个验证页面，代价相对较大：需要注册新的 Ability、配置路由、还要处理窗口切换时可能出现的闪烁问题。

更好的方案是用 WindowStage 的 getMainWindow 拿到主窗口，然后往里面叠加一个全屏的高层级自定义组件。这个组件就是锁定页，层级设置得比 Flutter 渲染层高，就能从视觉上盖住整个应用内容。

在 ArkUI 里，具体做法是在 build() 函数里用一个 Stack，组件顺序上把验证层放在最后面，并且通过 if 条件控制它是否渲染：

typescript复制build() {
  Stack() {
    // Flutter 渲染区域
    FlutterPage()

    // 验证层，默认隐藏
    if (this.isLocked) {
      LockScreen({ onUnlock: () => this.isLocked = false })
    }
  }
}

这个方案的好处是很直观：锁定层和 Flutter 页面在同一个 UIAbility 内，不涉及跨 Ability 的通信，渲染层级也容易控制。

但有一个坑得提醒一下：Flutter 的渲染在 OpenHarmony 上是作为一个独立的 XComponent 嵌入到页面里的，它的层级关系有时候并不完全受 ArkUI 的普通 ZOrder 规则控制。如果你在实验中发现浮层被 Flutter 内容遮住了，那大概率不是代码逻辑问题，而是 XComponent 的窗口层级一直在最顶部。

解决办法也简单：给浮层这侧设置一个独立的窗口，或者把 XComponent 的 RenderMode 从 SURFACE_TEXTURE 切换成其他模式。这个咱们后面会有专门一节来讲，因为这个问题几乎是新手最容易卡死的地方。

3.3 生物识别：能不能用鸿蒙系统的指纹/人脸能力

这才是整个适配里最有含金量的部分。

Android 上 secure_application 调用的是 BiometricPrompt，是系统级的生物识别对话框，支持指纹、人脸、虹膜。OpenHarmony 从 API 9 开始，也提供了类似的用户认证接口 userIAM_userAuth，支持的能力包括：指纹、人脸、PIN 码。也就是说，从能力上讲，这套适配路径是走得通的。

在 OpenHarmony 上调用生物识别的大致流程是：

从 @ohos.userIAM.userAuth 引入相关模块。
初始化 UserAuthInstance，并指定认证类型和认证等级。
检查设备是否支持你需要的认证方式。
调用 auth() 方法，传入回调。

一个最小示例大概是这样的：

typescript复制import userAuth from '@ohos.userIAM.userAuth';

let authInstance = userAuth.getUserAuthInstance({
  challenge: new Uint8Array([1, 2, 3, 4, 5]),
  authType: [userAuth.UserAuthType.FINGERPRINT],
  authTrustLevel: userAuth.AuthTrustLevel.ATL3
});

authInstance.on('success', () => {
  // 认证成功，通知 Flutter 层解锁
  SecureApplicationPlugin.notifyAuthenticated(true);
});

authInstance.on('failure', () => {
  // 认证失败，保持锁定状态
  SecureApplicationPlugin.notifyAuthenticated(false);
});

authInstance.start();

这里有几个很容易踩的坑：

第一，challenge 参数不能空着。它是用于防重放攻击的随机数，业务侧需要自己生成并保存。Android 上你也可以传 null，但 OpenHarmony 对 challenge 的校验比较严格，传空 Uint8Array 或者不传都有可能出现认证直接失败的情况。

第二，authTrustLevel 不要设得太高。ATL3 对应的是生物识别 + 锁屏凭证双重验证，如果设备只录了指纹没设锁屏密码，就会失败。你要是想跟 Android 原版的默认行为对齐，用 ATL2 可能更合适，它对应“至少一种生物特征”即可。

第三，认证回调里的 on('success') 和 on('failure') 属于一次性监听，每次认证完成后都需要重新挂监听再 start。这个和 Android 的 BiometricPrompt 回调模型很像，但封装上容易忽略。

在示例工程里，作者把生物识别封装成了一个独立的 ArkTS 类，对外只暴露 authenticate(successCallback, failureCallback) 一个方法，内部处理了 getUserAuthInstance、监听回调、start 等过程。这样模块边界清晰，万一后续要支持人脸识别，改动面也比较小。

3.4 PIN 码验证和生物识别的组合策略

secure_application 原版有个很有意思的设计：当生物识别不可用或者用户拒绝授权时，它会退回到数字 PIN 界面。这个策略在金融类 App 里其实非常重要，因为很多旧机型没有指纹模块，你不能假设所有用户都能用生物识别。

OpenHarmony 适配版同样保留了这套组合策略。实现方案是：先判断设备是否支持某种生物识别类型，支持就走 userIAM_userAuth，返回 DEVICE_NOT_SUPPORT 之类的错误码时，再自动切换成自定义的 PIN 输入组件。

判断设备支持能力可以参考：

typescript复制let supportResult = authInstance.getAvailableStatus(
  userAuth.UserAuthType.FINGERPRINT,
  userAuth.AuthTrustLevel.ATL2
);

if (supportResult === userAuth.ResultCode.SUCCESS) {
  // 支持指纹，走生物识别
} else {
  // 不支持，走 PIN 码验证
}

还有一个场景要考虑：指纹模块存在，但是用户没录指纹。这时 getAvailableStatus 返回的也可能是失败状态码，而不是 SUCCESS。所以判断条件不要写死成“只验证设备是否支持”，最好把“支持但未录入”也当成走 PIN 的触发条件。

这些细节如果不在适配阶段处理好，实际测试时就会出现“应用明明适配了、但用户就是卡在锁屏页出不来”的现象。用户体验层面是非常致命的问题。

4. 示例应用的完整实操过程：从零跑通 secure_application

4.1 环境准备与工程创建

做 OpenHarmony Flutter 开发跟标准的 Flutter 开发在环境上还是有一些区别的。我这里假设你已经安装了 Flutter SDK，并且也装好了 OpenHarmony 的 DevEco Studio。如果没有，先去把这两个基础工具链补齐，不然下面的步骤无从谈起。

关键的地方在于，普通的 Flutter SDK 是不支持 OpenHarmony 平台的，你需要用 OpenHarmony 官方维护的 Flutter SDK 分支，它额外支持了 ohos 这个 platform target。

具体操作步骤：

下载 OpenHarmony 的 Flutter SDK 分支，替换掉你本地的 Flutter SDK。
安装 DevEco Studio，并确保 SDK 的 API 版本足够新（建议 API 9 以上）。
用 flutter doctor 确认 flutter 能识别到 OpenHarmony 相关的 toolchain。

然后在项目里添加 OpenHarmony 平台的依赖：

yaml复制environment:
  sdk: ">=2.16.0 <4.0.0"
  flutter: ">=1.20.0"

这个环境准备阶段没有太多捷径可走，但是我给一个忠告：不要用太老的 Flutter SDK 分支搭配最新的 DevEco Studio，反过来也不行。版本不匹配会直接导致构建阶段出现“无法解析的符号”或者“找不到 XComponent”错误。最好直接按官方文档写明的版本来。

4.2 把 secure_application 移植到工程里

这里分两种场景，一种是你在自己的 Flutter 应用里直接依赖已经适配好的 secure_application 版本，另一种是你要自己开发 secure_application 的 OpenHarmony 适配插件，拿示例工程当模板。

第一种场景比较简单。在 pubspec.yaml 里声明依赖：

yaml复制dependencies:
  flutter:
    sdk: flutter
  secure_application: ^3.0.0

不过要注意，你现在经常拉到的 secure_application 版本还是 Android 原版的，不一定包含 OpenHarmony 平台实现。如果发布了 OpenHarmony 适配版本，通常版本号后面会带一个 +ohos 之类的 tag。拉到正确的包后，在 Dart 侧写业务代码：

dart复制final secureApplication = SecureApplication(
  onBackground: () {
    // 进入后台时，可以在这里做敏感数据清理
  },
  onLock: () {
    // 应用锁定
  },
  onUnlock: () {
    // 解锁成功，恢复页面数据
  },
);

然后创建自定义的锁屏页面：

dart复制SecureApplication(
  lockScreen: (context, controller) {
    return CustomLockScreen(controller: controller);
  },
)

如果你是第二种场景，想基于示例工程去二次开发，那么核心思路就是替换 ohos 目录下的原生实现。这个工程默认已经提供了完整的 SecureApplicationPlugin.ets，你的工作更多是理解和修改它，让它适应你项目里的特殊需求。

4.3 ArkTS 层关键代码逐行拆解

接下来我把示例工程里最核心的一段代码拿来讲。这个就是前面提到生命周期通知相关的内容：

typescript复制export class SecureApplicationPlugin {
  private static instance: SecureApplicationPlugin;
  private secureApplication: SecureApplication;
  private uiAbilityContext: common.UIAbilityContext | null = null;

  static getInstance(): SecureApplicationPlugin {
    if (!SecureApplicationPlugin.instance) {
      SecureApplicationPlugin.instance = new SecureApplicationPlugin();
    }
    return SecureApplicationPlugin.instance;
  }

  setUiAbilityContext(context: common.UIAbilityContext) {
    this.uiAbilityContext = context;
  }

  notifyBackground() {
    if (this.secureApplication) {
      this.secureApplication.onBackground();
    }
  }

  notifyForeground() {
    if (this.secureApplication) {
      this.secureApplication.onForeground();
    }
  }

  notifyAuthenticated(success: boolean) {
    if (this.secureApplication) {
      this.secureApplication.onAuthenticated(success);
    }
  }
}

你可能有点奇怪，为什么这里没有直接写和 MethodChannel 相关的内容？

因为我在设计这个示例工程时，刻意把“原生能力内部逻辑”和“平台通道通信”分开。SecureApplicationPlugin 负责接收生命周期事件、管理认证流程、以及维护当前是否处于锁定状态。MethodChannel 的注册和处理则放在另一个模块里，通过 InvokeMethod 把 Dart 侧的调用翻译成插件内部的方法调用。

这样做最大的好处是测试很方便，不依赖 Flutter 引擎也能单独跑单元测试，也能让你后续改成其他通信方式（比如 CallKit、EventChannel）时不至于大面积改动。

MethodChannel 注册那一段大致是这样：

typescript复制registerMethodChannel() {
  this.channel = MethodChannel(
    this.uiAbilityContext,
    'com.example.secure_application',
    StandardMethodCodec.getInstance()
  );
  this.channel.setMethodCallHandler((call) => {
    switch (call.method) {
      case 'lock':
        this.lockApp();
        break;
      case 'unlock':
        this.unlockApp();
        break;
      case 'listen':
        this.startListen();
        break;
    }
  });
}

注意，这里的 lockApp 和 unlockApp 是原生侧实现，跟 Android 版的方法名保持一致，需要一一对齐 Dart 层调用的方法名。如果方法名对不上，Flutter 侧会直接报 MissingPluginException。

4.4 在 UIAbility 中接入插件

接入插件的入口就是应用的 EntryAbility。在 onCreate 或者 onWindowStageCreate 中，注册插件和生命周期监听：

typescript复制export default class EntryAbility extends UIAbility {
  private secureApplicationPlugin: SecureApplicationPlugin;

  onCreate(want, launchParam) {
    this.secureApplicationPlugin = SecureApplicationPlugin.getInstance();
    this.secureApplicationPlugin.setUiAbilityContext(this.context);
    this.secureApplicationPlugin.init();
  }

  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err) => {
      // Flutter page 加载
    });
  }

  onBackground() {
    this.secureApplicationPlugin.notifyBackground();
  }

  onForeground() {
    this.secureApplicationPlugin.notifyForeground();
  }
}

这里有一个细节可以分享：onWindowStageCreate 里加载的 pages/Index 才是整个页面的容器，Flutter 渲染内容是以组件形式嵌入到这个 Index 页面中的。如果你的锁屏界面是想做成组件叠加的形式，那 Index 页面里就要包含锁定层和正常内容层的切换。

4.5 构建、运行与验证

配置全部完成后，用 DevEco Studio 打开 ohos 目录，点击 Sync 和 Build，构建出 HAP 包。然后用 DevEco Studio 的模拟器或者真机跑起来。

验证步骤是这样：

启动应用，正常进入页面。
按 Home 键把应用退到后台。
再点应用图标回到前台。
观察是否弹出锁定验证界面。
用指纹或 PIN 解锁，看是否正常进入。
在设置里关闭系统锁屏和指纹，重新测试，确认能自动切换到 PIN 验证。

一个容易忽略的小验证点是：要测试“后台一段时间后自动锁定”的行为。secure_application 支持一个可配置的超时时间，比如 30 秒内重新进入不弹锁，超过 30 秒才弹。OpenHarmony 适配后依然要支持这个参数，否则应用在默认策略下和原版行为不一致，项目里可能就出 bug。

5. 常见问题与排查技巧实录

5.1 XComponent 区域遮挡问题，导致锁屏浮层看不到

前面提到过，这是 OpenHarmony 上 Flutter 插件最常见的问题。

表现是：锁屏逻辑触发了，Dart 层状态也变了，Log 也打了，但屏幕上看起来就是“没反应”。其实是浮层出现了，但是被 Flutter 的渲染界面盖住了。

这里的根因是：Flutter 在 OpenHarmony 上通过 XComponent 渲染内容，底层相当于一个独立的纹理或 Surface，它跟 ArkUI 普通组件的 Z 轴关系在部分设备上不一致。解决办法有几种：

第一种，把 XComponent 的 RenderMode 改成不占用独立 Surface 的方式。示例工程里如果遇到遮挡，最直接的方式是把组件渲染模式切换成 RenderMode.SURFACE_TEXTURE，让它和 ArkUI 组件在同一个合成器里参与混合。

第二种，放弃组件叠加，改为用 windowStage 新开一个全屏窗口作为锁定层。这样从系统层级上锁定窗口永远在应用窗口之上，可以彻底避免遮挡问题。代价是实现复杂度更高，需要自己管理窗口生命周期。

5.2 生物识别回调不触发

有时候调用 authInstance.start() 后，指纹弹窗出来了，用户也验证了，但 success 回调就是不执行。遇到这个情况，先确认监听事件注册方式。

之前在 3.3 中提到过，OpenHarmony 的 userIAM_userAuth 要求先挂监听再调用 start，而且每个生命周期内的监听是一次性的。如果你把 start 调用放在监听注册之前，可能回调就丢失了。

建议写法：

typescript复制authInstance.on('finish', (result) => {
  // result.result 为最终结果
});
authInstance.on('fail', (result) => {
  // 验证失败
});
authInstance.start();

不同 API 版本的监听事件名可能不同，有的用 success/failure，有的用 finish/fail。这个在排查时优先对照你所用 SDK 版本的 API 文档，别照抄老代码。

5.3 后台一段时间后回来，没有自动弹锁屏

首先要确认不是 Flutter 侧缓存状态问题。因为 Flutter 页面从后台恢复时，Dart 层的 WidgetsBinding 可能并没有被销毁，只是原生的 onForeground 事件没有正确传递。

你可以先在原生侧的 onForeground 里打日志，确认有没有走到。如果日志没有，说明 EntryAbility 没接好生命周期回调，或者插件实例没有被正确注入给 Ability。

如果日志有，但是没有收到 Dart 层方法回调，那就要检查 MethodChannel 是否在 listen 调用之后才注册了 EventChannel 的事件监听。secure_application 的 Dart 层通常有一个 listen() 方法用来开始接收原生事件，如果你在 main() 里没有调用 secureApplication.activate() 或者 .listen()，那原生回调发出来也没人接收。

示例工程里，作者在 main 函数中会显式调用一次 SecureApplication.instance.activate()。这个步骤至关重要，不要漏掉。

5.4 锁屏页面在旋转屏幕后错位

如果你在应用里开启了方向旋转，锁屏组件在 onConfigurationUpdated 时如果没有重新布局，就可能出现错位。

这个问题在 Android 上同样存在，但是适配到 OpenHarmony 时更隐蔽，因为 ArkUI 的布局有时候并不会自动响应横竖屏切换，需要在 onWindowStageCreate 里对窗口方向变化做监听。

简单来说，锁定层应该作为一个独立的页面级组件来布局，约束填满整个窗口，不要依赖外部布局容器动态计算位置。如果你发现锁定层只有一部分区域覆盖到了有效显示区域，九成是布局约束没设置百分比。

在 ArkTS 里，把 width('100%') 和 height('100%') 写在锁屏组件根节点上，是最稳妥的做法。

5.5 常见问题速查表

为了方便排查，我整理了一个速查表，你在实际适配中遇到问题时可以直接对照。

问题现象	可能原因	解决思路
锁屏浮层不显示	XComponent 遮挡	切换 XComponent RenderMode，或者改用独立窗口
生物识别无回调	监听注册晚于 start 调用	先注册 on/off 事件，再调用 start
后台恢复不触发锁屏	UIAbility 生命周期未注入插件	检查 onBackground/onForeground 是否调用通知方法
指纹不支持时卡死	缺少 PIN 兜底	检查 getAvailableStatus，不支持或未录入就走 PIN
回调报 MissingPluginException	MethodChannel 的 name 不一致	确保原生和 Dart 层 channel name 一致
锁屏页有黑边	布局宽高未适配窗口	使用 100%/100% 根节点布局

6. 工具选型与方案取舍：什么样的情况适合直接用它

在决定要不要用 secure_application 适配版时，你其实要做的是拿它和另外几种方案对比。

第一种，自己基于 OpenHarmony 的生命周期 API 手写一个应用锁。好处是灵活，想怎么改怎么改，而且不依赖三方库的维护节奏。坏处是代码量不小，要处理的边界情况还挺多的，比如生物识别兼容性、PIN 页面设计、动态配置锁定超时时间等。如果是小团队接外包，工期可能扛不住。

第二种，直接用系统级的“应用锁”能力。OpenHarmony 系统本身没有开放给普通应用直接调用的“应用锁”接口，所以这条基本走不通。

第三种，就是 secure_application 的适配版本。它的优势在于：Dart 层 API 保持和主流版本一致，Android 已有的逻辑可以直接复用；原生适配代码是现成的，除非你有个性化需求，否则开箱即用；社区维护者已经把常见坑都踩过了。

它的问题也很现实：依赖第三方适配包的维护者更新节奏，尤其是当 Flutter SDK 版本升级，或者 OpenHarmony API 版本变动时，可能存在一段时间的不兼容。

我在实际项目里测下来，如果应用本身的业务不算特殊，只是一个标准的“后台回来懒锁定”需求，直接用它是最省事的。

6.1 锁定超时机制

secure_application 的另一个特性是支持配置一个超时时间。意思是：应用进入后台 T 秒内再回来，不锁定；超过 T 秒，才要求重新验证。

这个机制在很多场景下非常重要。比如用户只是临时切到微信回个消息，几秒钟就切回来，每次都验证会很烦。但如果后台时间较长，比如超过一分钟，那出于安全考虑，应该重新锁定。

Android 上这个逻辑写在原生层，利用系统时间和前后台时间戳去计算。OpenHarmony 适配版也保留了同样逻辑，在 onBackground 时记录时间戳，在 onForeground 时比较当前时间和上次记录时间的差值。

具体实现可以把时间戳存成静态变量：

typescript复制private lastBackgroundTime: number = 0;
private lockAfterMilliseconds: number = 30000;

onBackground() {
  this.lastBackgroundTime = Date.now();
}

onForeground() {
  let dif = Date.now() - this.lastBackgroundTime;
  if (dif >= this.lockAfterMilliseconds) {
    this.lockApp();
  }
}

这个逻辑虽小，但它决定了用户实际使用体验的优劣，也是测试用例里最容易被遗漏的部分之一。

6.2 安全性验证：不是“显示一个锁屏弹窗”就完事了

做安全类功能，最忌讳的就是“形似而神不似”。

有些开发者看到锁屏弹窗正常显示，就认为适配完成了。但真正的安全验证要确认几个更深的问题：当应用处于锁定状态时，Flutter 页面是否真的被遮挡，还是只是在顶层盖了一个半透明的锁屏；后台任务恢复时，敏感数据有没有可能通过截屏、录屏被泄露；应用内打开的 WebView、图片、文件内容，是否也需要一并隐藏。

在示例工程里，锁定层是一个不透明的全屏组件，这样能从视觉上遮挡住所有内容。另外我还会建议做两件事：

一个是在锁定态时暂停渲染更新。这里是可以通过 Flutter 的 SchedulerBinding 来实现，在锁定期间阻止页面 rebuild，从底层上避免敏感内容闪现。

另一个是处理系统截屏问题。OpenHarmony 上可以通过给窗口设置 FLAG_SECURE 之类的标志，禁止截屏和画面投屏。secure_application 的 Android 版本身支持这个特性，适配版也应该保留。

如果你发现自己使用的版本没有实现这个特性，你要么自己补上，要么至少要在项目文档里明确说明这一限制，别让业务侧以为已经安全了。

7. 从示例到生产：我的适配经验与扩展建议

一个示例工程跑通，距离真正上线还是有一段路的。这里把我自己的经验分享出来，也当作对这次拆解的一个收尾。

首先，我强烈建议你在拿到适配版之后，不要直接把它当作完全可信赖的黑盒，而是花时间把 ohos 目录下的原生代码通读一遍。这个库的适配版本里，原生代码量其实不大，大概也就几百行 ArkTS，完全看完是可行的。了解它的实现方式之后，你在后续遇到问题时才能更快定位，同时也能根据自己的业务场景做一些个性化调整。

其次是测试策略。secure_application 属于“跨端能力”插件，它的正确性非常依赖系统环境，所以测试用例要覆盖三类情况：不同 OpenHarmony 版本之间，API 行为可能不一样；不同设备之间的生物识别能力差别很大，比如有些设备支持人脸，有些不支持；以及前后台切换频率和超时边界值的测试。最好写成自动化 UI 测试脚本，别靠人工反复按 Home 键。

最后，如果条件允许，建议关注一下社区的更新动态。Flutter 本身更新节奏比较快，OpenHarmony 的 API 也在演进，这些都可能影响插件的稳定性。如果库维护得比较慢，你可以在自己的 fork 上打补丁，但一定要保持提交记录清晰，方便后续与上游同步。

我在做这个适配时，最深刻的体会是：Flutter 跨平台的价值，在 OpenHarmony 生态里依然成立，但它并不是无代价的。每次引入一个新的三方库，都要重新评估“Dart 层能用”和“平台能力可用”之间的落差。secure_application 的适配工程，就是这种跨生态迁移中非常典型的一个样本。只要你看懂了它，后面再适配其他 Flutter 三方库，思路基本是相通的。

如果你在跑这个示例应用时遇到了什么问题，欢迎在评论区留个具体的现象和日志，我看到了会回复的。特别是 XComponent 遮挡、生物识别回调这类和环境强相关的问题，有时候真的需要多几个样本一起排查才能定位。

Flutter应用锁库在OpenHarmony上的适配实践与关键技术拆解