前言

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

做过金融类、医疗类App的同学应该都遇到过这样的需求：用户切到后台时，应用切换器里不能显示敏感内容；用户回到App时，需要重新验证身份才能看到数据。这类需求说起来简单，但要在多个平台上统一实现，工作量其实不小。

secure_application 就是为了解决这个问题而生的Flutter插件。它提供了一套声明式的API，让开发者用几行代码就能实现应用内容的隐私保护。而我们今天要聊的，是如何把这个插件适配到OpenHarmony平台上——让它在鸿蒙设备上也能正常工作。

这是本系列30篇文章的第一篇，先把整体情况摸清楚。

一、secure_application 是什么

1.1 一句话定位

secure_application 是一个应用内容可见性保护插件，核心能力是：当用户离开App时，自动隐藏敏感内容；当用户回来时，要求认证后才能查看。

1.2 它能做什么

具体来说，它提供了以下能力：

1. 应用切换器内容隐藏：用户按Home键或切换App时，在系统的应用切换器（Recent Apps）中看不到你的App内容
2. 截屏/录屏防护：在Android上，开启保护后用户无法截屏或录屏
3. 模糊遮罩：用户回到App时，敏感内容上方会覆盖一层高斯模糊遮罩
4. 认证解锁：支持自定义认证流程（PIN码、生物识别等），认证通过后才移除遮罩
5. 状态事件流：提供认证事件流和锁定事件流，方便业务层响应

1.3 典型使用场景

场景	需求	secure_application 的作用
银行App	切后台时隐藏余额	SecureGate 模糊遮罩
医疗App	防止截屏泄露病历	FLAG_SECURE / PrivacyMode
企业App	切回时要求重新认证	onNeedUnlock 回调
社交App	私密聊天防偷看	局部 SecureGate 保护
笔记App	加密笔记的查看保护	lock/unlock 状态管理

1.4 插件基本信息

name: secure_application
description: Secure app content visibility when user leave app
version: 4.1.0
homepage: https://github.com/neckaros/secure_application

属性	值
包名	secure_application
当前版本	4.1.0
作者	neckaros
许可证	MIT
pub.dev	secure_application
最低Dart版本	>=2.12.0
最低Flutter版本	>=3.0.0

二、核心概念：四种状态

2.1 状态模型

secure_application 的核心是一个四状态模型，理解了这四个状态，就理解了整个插件：

class SecureApplicationState {
  final bool locked;        // 是否锁定（遮罩是否显示）
  final bool secured;       // 是否开启保护（切后台时是否触发锁定）
  final bool paused;        // 是否暂停（临时禁止自动锁定）
  final bool authenticated; // 最近一次认证是否成功
}

2.2 状态流转

状态	含义	触发方式
secured	保护已开启	调用 controller.secure()
locked	内容已锁定，遮罩显示	用户切后台自动触发，或手动 controller.lock()
paused	暂停保护	调用 controller.pause()，如打开文件选择器时
authenticated	认证状态	authSuccess() 设为true，authFailed() 设为false

💡 关键理解：secured 是"开关"，locked 是"结果"。只有 secured=true 时，用户切后台才会触发 locked=true。

2.3 状态流转图

                    secure()
    [未保护] ──────────────────► [已保护/未锁定]
        ◄──────────────────
                    open()
                                      │
                                      │ 用户切后台
                                      ▼
                               [已保护/已锁定]
                                      │
                                      │ 用户切回前台
                                      ▼
                               [触发 onNeedUnlock]
                                    /   \
                                   /     \
                          authSuccess  authFailed
                              │           │
                              ▼           ▼
                         [已解锁]    [仍锁定/清除数据]

三、多平台支持现状

3.1 平台覆盖

flutter:
  plugin:
    platforms:
      android:
        package: org.jezequel.secure_application
        pluginClass: SecureApplicationPlugin
      ios:
        pluginClass: SecureApplicationPlugin
      web:
        pluginClass: SecureApplicationWeb
        fileName: secure_application_web.dart
      windows:
        pluginClass: SecureApplicationPlugin
      ohos:
        pluginClass: SecureApplicationPlugin
        fileName: secure_application_plugin.ets

3.2 各平台实现方式对比

平台	实现语言	核心机制	截屏防护
Android	Kotlin	FLAG_SECURE 窗口标志	✅ 系统级
iOS	Swift	UIVisualEffectView 模糊覆盖	❌ 仅遮挡
Web	Dart	visibilitychange 事件	❌ 无法控制
Windows	C++	最小化/锁屏检测	❌ 无法控制
OpenHarmony	ArkTS	setWindowPrivacyMode	✅ 系统级

📌 值得注意的是：OpenHarmony 的 setWindowPrivacyMode 提供了和 Android FLAG_SECURE 类似的系统级截屏防护能力，这是 iOS/Web/Windows 都做不到的。

3.3 各平台代码量

平台	原生代码文件	大致行数
Android	SecureApplicationPlugin.kt	~120行
iOS	SecureApplicationPlugin.swift	~100行
Web	secure_application_web.dart	~50行
Windows	SecureApplicationPlugin.cpp	~80行
OpenHarmony	SecureApplicationPlugin.ets	~234行

OpenHarmony 的实现行数最多，因为它同时实现了窗口隐私模式和应用生命周期监听两套机制。

四、OpenHarmony 适配的意义

4.1 生态需求

OpenHarmony 作为面向万物互联的操作系统，在以下领域有大量隐私保护需求：

• 金融科技：手机银行、支付应用
• 政务办公：政府OA、公文处理
• 医疗健康：电子病历、健康数据
• 企业应用：内部通讯、商业机密

这些场景都需要应用内容保护能力，而 secure_application 正好填补了 Flutter-OHOS 生态中这个空缺。

4.2 技术价值

适配 secure_application 的技术价值在于：

1. 验证 Window API 的可用性：setWindowPrivacyMode 是 OpenHarmony 特有的 API，通过适配可以验证其在 Flutter 插件中的可用性
2. 探索生命周期管理：OpenHarmony 的应用生命周期与 Android 有差异，适配过程可以积累经验
3. 建立适配范式：为其他安全类插件的适配提供参考模板

4.3 与 flutter_speech 适配的差异

维度	flutter_speech	secure_application
核心 Kit	Core Speech Kit	ArkUI Window API
是否需要权限	麦克风权限	隐私窗口权限（可选）
是否需要 AbilityAware	✅ 需要 UIAbilityContext	❌ 通过 ApplicationContext
通信方向	双向（大量 Native→Dart）	双向（少量 Native→Dart）
状态管理	简单（isListening）	复杂（四状态机）
Dart 层复杂度	低（薄封装）	高（Widget + Controller + Provider）

五、插件的 Dart 层架构概览

5.1 文件结构

lib/
├── secure_application.dart           # 主 Widget + 导出
├── secure_application_controller.dart # 状态控制器
├── secure_application_state.dart      # 不可变状态类
├── secure_application_native.dart     # MethodChannel 封装
├── secure_application_provider.dart   # InheritedWidget 提供者
├── secure_application_web.dart        # Web 平台实现
└── secure_gate.dart                   # 模糊遮罩 Widget

5.2 类关系

SecureApplication (StatefulWidget)
    ├── 持有 SecureApplicationController (ValueNotifier)
    │       ├── 管理 SecureApplicationState (immutable)
    │       ├── 发射 authenticationEvents (BehaviorSubject)
    │       └── 发射 lockEvents (BehaviorSubject)
    ├── 通过 SecureApplicationProvider (InheritedWidget) 向下传递
    └── 监听 AppLifecycleState 变化

SecureGate (StatefulWidget)
    ├── 从 SecureApplicationProvider 获取 Controller
    ├── 监听 Controller 的 locked 状态
    └── 显示/隐藏 BackdropFilter 模糊遮罩

5.3 与传统 Plugin 的区别

大多数 Flutter Plugin（比如 flutter_speech）的 Dart 层很薄——就是一个类包装几个 MethodChannel.invokeMethod 调用。但 secure_application 不同，它的 Dart 层非常"重"：

• 有自己的 Widget 树（SecureApplication → SecureGate）
• 有自己的 状态管理（ValueNotifier + InheritedWidget）
• 有自己的 事件系统（rxdart BehaviorSubject）
• 有自己的 生命周期管理（WidgetsBindingObserver）

原生端反而相对"轻"——只负责设置窗口标志位和监听系统事件。

六、OpenHarmony 原生端架构概览

6.1 核心文件

ohos/
├── index.ets                          # 入口导出
├── oh-package.json5                   # 包配置
├── build-profile.json5                # 构建配置
└── src/main/
    ├── module.json5                   # 模块声明
    └── ets/components/plugin/
        └── SecureApplicationPlugin.ets # 核心实现

6.2 原生端职责

export default class SecureApplicationPlugin implements FlutterPlugin, MethodCallHandler {
  // 1. MethodChannel 通信
  // 2. Window 获取与隐私模式控制
  // 3. 窗口事件监听（失焦检测）
  // 4. 应用生命周期监听（前后台切换）
}

原生端做了三件事：

1. 响应 Dart 层的 secure/open/lock/unlock 指令
2. 通过 setWindowPrivacyMode 控制截屏防护
3. 监听窗口失焦和应用前后台切换，主动通知 Dart 层执行 lock

总结

本文介绍了 secure_application 插件的功能全景和 OpenHarmony 适配的价值：

1. 核心能力：应用切换器内容隐藏、截屏防护、模糊遮罩、认证解锁
2. 四状态模型：secured / locked / paused / authenticated
3. 五平台支持：Android、iOS、Web、Windows、OpenHarmony
4. OpenHarmony 特色：setWindowPrivacyMode 提供系统级截屏防护
5. 架构特点：Dart 层重（Widget + 状态管理），原生端轻（窗口控制）

下一篇我们来搭建开发环境——包括 DevEco Studio、Flutter-OHOS SDK 和多平台联调环境的配置。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• secure_application pub.dev
• secure_application GitHub
• secure_application Gitcode
• OpenHarmony Window API
• Flutter-OHOS 适配指南
• 开源鸿蒙跨平台社区
• Android FLAG_SECURE 文档
• iOS App Lifecycle

secure_application 锁定状态下的模糊遮罩效果

secure_application 点击UNLOCK

Android 切换到appswitcher时的状态