@capacitor/privacy-screen

本项目基于 @capacitor/[email protected] 开发。

简介

隐私屏幕保护 API，可在应用进入后台时隐藏敏感内容，防止被查看。本插件是 capacitor 生态系统中的核心插件，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境中使用，本文档仅说明在 OpenHarmony 系统中的使用情况。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/privacy-screen

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/privacy-screen

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/privacy-screen",
  "classpath": "PrivacyScreen"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，找到 capacitor 模块，路径为 target 字段的 CMakeLists.txt 文件，并添加 add_subdirectory 和 target_link_libraries 如下：

// ...
add_subdirectory(PrivacyScreen)
// ...

// ...
target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  PrivacyScreen
  // ...
  "-Wl,--no-whole-archive"
);

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并复制到对应的目录：

将插件源码中 src/main/cpp/PrivacyScreen 目录下的 PrivacyScreen.h、PrivacyScreen.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/PrivacyScreen 目录下。

将源码中 src/main/ets/components/PrivacyScreen 目录下的 PrivacyScreen.ets、PrivacyScreenDialog.ets 文件引入到 capacitor 模块中 src/main/ets/components/PrivacyScreen 目录下。

在 capacitor 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入拷贝的 ets 文件路径：

"buildOption": {
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        "./src/main/ets/components/PrivacyScreen/PrivacyScreen.ets"
      ]
    }
  }
}

卸载

# 卸载 privacy-screen 插件
hionic plugin remove @capacitor/privacy-screen

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony 需要申请隐私窗口权限，在主工程的 module.json5 的 requestPermissions 添加 ohos.permission.PRIVACY_WINDOW 权限，示例如下：

{
  "name": "ohos.permission.PRIVACY_WINDOW",
  "reason": "$string:privacy_window",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "always"
  }
}

更多权限说明参考：申请应用权限。

使用示例

基础示例：开启关闭隐私屏幕

import { PrivacyScreen } from '@capacitor/privacy-screen';

// Enable privacy screen with default settings
await PrivacyScreen.enable();

// Enable with platform-specific configuration
await PrivacyScreen.enable({
  android: {
    dimBackground: true,
    privacyModeOnActivityHidden: 'splash'
  },
  ios: {
    blurEffect: 'dark'
  }
});

// Disable privacy screen
await PrivacyScreen.disable();

// Check if privacy screen is enabled
const { enabled } = await PrivacyScreen.isEnabled();

基础示例：暗屏保护

import { PrivacyScreen } from '@capacitor/privacy-screen';

// Enable privacy screen when navigating to a secure screen
async function navigateToSecureScreen() {
  await PrivacyScreen.enable({
    android: { dimBackground: true },
    ios: { blurEffect: 'dark' }
  });
  // Navigate to your secure screen
}

// Disable when navigating to a non-secure screen
async function navigateToPublicScreen() {
  await PrivacyScreen.disable();
  // Navigate to your public screen
}

使用说明

接口方法

| 方法名 | 请求参数 | 返回类型 | 描述 | | ------------- | ------------------------------------------------------------------------------ | ---------------------------- | ---------------------------------- | | enable() | config?: PrivacyScreenConfig | Promise<{ success: boolean }> | 开启隐私屏幕保护 || | disable() | | Promise<{ success: boolean }> | 关闭隐私屏幕保护 | | isEnabled() | | Promise<{ enabled: boolean }> | 检查隐私屏幕保护是否已开启 |

数据结构

PrivacyScreenConfig

| 参数 | 类型 | 描述 | | ----------- | -------------------------------------------------------------------------------------------------- | ------------ | | android | { dimBackground?: boolean; preventScreenshots?: boolean; privacyModeOnActivityHidden?: 'none' | 'dim' | 'splash' } | Android 配置 | | ios | { blurEffect?: 'none' | 'light' | 'dark' } | iOS 配置 |

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- PrivacyScreen   # 插件核心 C++ 实现
|                             |---- PrivacyScreen.h
|                             |---- PrivacyScreen.cpp
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- PrivacyScreen   # 插件核心 ArkTS 实现
|                                   |---- PrivacyScreen.ets
|                                   |---- PrivacyScreenDialog.ets
|     |---- README.md          # 说明文档
|     |---- package.json       # npm 配置文件
|     |---- plugin.xml         # capacitor 插件配置
|     |---- LICENSE            # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。