更新记录

1.0.0（2026-06-30）

• 提供 Android Device Owner + Lock Task kiosk runtime。
• 提供 initKiosk()、enableKiosk()、disableKiosk()、getKioskStatus()。
• 提供 Android receiver、HOME alias、manifest 验证脚本和中文文档。

平台兼容性

uni-app x(4.87)

其他

Shift Kiosk

用于 uni-app x 的 Android kiosk 模式插件。

该插件提供一组底层 Android 系统控制能力，用于构建 kiosk（自助终端 / 锁定任务）类型应用。它只负责 runtime，不包含业务逻辑、UI、管理员密码、隐藏手势、业务路由或日志系统。

插件信息

功能特性

完整 kiosk 能力依赖 Android Device Owner。普通 App 无法真正接管 Home、Recent 等系统行为。

安装方式

npm 安装

npm install uni-shift-kiosk

uni-app x / HBuilderX

uni-app x 插件需要放在项目的 uni_modules 目录下：

uni_modules/shift-kiosk/

如果通过 npm 安装后插件没有自动出现在 uni_modules/shift-kiosk，需要将包复制或软链接到该目录后再构建 App。

使用前提

1. Android 设备。
2. uni-app x App 端项目。
3. 使用自定义运行基座或正式 APK 验证原生能力。
4. 最终 APK 中必须包含本插件的 Android manifest、receiver 和 device_admin_receiver.xml。
5. 如需完整 kiosk/锁定任务能力，必须先将宿主 App 设置为 Android Device Owner。

API 使用

import {
  initKiosk,
  enableKiosk,
  disableKiosk,
  getKioskStatus,
} from "@/uni_modules/shift-kiosk/index.uts";

initKiosk(options?)

初始化 kiosk 运行环境，但不会进入 Lock Task 模式。

默认行为：

• 启用沉浸式全屏
• 保持屏幕常亮
• 将当前应用加入 Lock Task 白名单
• 将当前应用配置为 persistent HOME

const result = initKiosk();

if (!result.ok) {
  console.log(result.code + ": " + result.message);
}

也可以传入选项：

const result = initKiosk({
  immersive: true,
  keepScreenOn: true,
  configureLockTask: true,
  configureHome: true,
});

一般不需要手动传 lockTaskPackages。不传时，插件会默认使用当前 App 的 Android 包名。

enableKiosk(options?)

初始化 kiosk 运行环境，并调用 Android startLockTask() 进入 Lock Task 模式。

const result = enableKiosk({
  immersive: true,
  keepScreenOn: true,
});

if (!result.ok) {
  console.log(result.code + ": " + result.message);
}

disableKiosk()

退出 Lock Task 模式。

如果当前 App 是 Device Owner，插件还会尝试清理由本插件配置的 Lock Task 白名单和 persistent HOME 配置。该方法不会移除 Android Device Owner 身份。

const result = disableKiosk();

getKioskStatus()

获取当前运行状态：

const status = getKioskStatus();

console.log(status.packageName);
console.log(status.isDeviceOwner);
console.log(status.isLockTaskActive);
console.log(status.isLockTaskPermitted);

类型定义

export type KioskInitOptions = {
  immersive?: boolean;
  keepScreenOn?: boolean;
  configureLockTask?: boolean;
  configureHome?: boolean;
  lockTaskPackages?: Array<string>;
}

export type KioskStatus = {
  packageName: string;
  isDeviceOwner: boolean;
  isLockTaskActive: boolean;
  isLockTaskPermitted: boolean;
}

export type KioskResult = {
  ok: boolean;
  code: string;
  message: string;
  status: KioskStatus;
}

Android 组件

插件会通过 utssdk/app-android/AndroidManifest.xml 注册以下 Android 组件：

项目通常不需要手动添加这些组件，但最终 APK 必须包含它们。修改插件原生代码或 manifest 后，需要重新构建自定义基座 / APK。

插件结构

shift-kiosk/
├── index.uts
├── package.json
├── README.md
├── scripts/
│   └── verify-kiosk-manifest.sh
└── utssdk/
    ├── interface.uts
    └── app-android/
        ├── index.uts
        ├── KioskAndroid.kt
        ├── AndroidManifest.xml
        ├── config.json
        └── res/xml/device_admin_receiver.xml

是否需要 ADB

运行时调用 initKiosk()、enableKiosk()、disableKiosk() 不需要 ADB。

首次把 App 设置成 Android Device Owner 时需要 ADB，除非你使用 Android Enterprise、MDM、NFC 或二维码等其他企业设备配置方式。对于普通开发、测试和工厂部署，ADB 是最直接的方式。

Device Owner 只能在干净设备上设置：

• 设备已恢复出厂设置
• 没有登录 Google 账号或其他账号
• 没有已有 Device Owner
• 没有 Work Profile
• 已开启 USB 调试
• 电脑已安装 ADB

设置 Device Owner：

adb install -r your-app.apk
adb shell dumpsys package <your.package> | grep -A 25 uts.sdk.modules.shiftKiosk.DeviceAdminReceiver
adb shell dpm set-device-owner <your.package>/uts.sdk.modules.shiftKiosk.DeviceAdminReceiver
adb shell dpm list-owners
adb reboot

示例中的 <your.package> 必须替换成你的 App 的真实 Android 包名。

Device Owner 设置完成后，App 内调用 enableKiosk() 才能进入完整 kiosk 模式。开机拉起 App 后，也需要你的应用在启动或恢复时主动调用 enableKiosk()。

常用 ADB 命令

查看已安装包名：

adb shell pm list packages | grep -i your-keyword

检查 Device Owner：

adb shell dpm list-owners

检查 receiver 是否合入最终 APK：

adb shell dumpsys package <your.package> | grep -A 25 uts.sdk.modules.shiftKiosk.DeviceAdminReceiver

移除 Device Owner（通常仅测试阶段使用，部分系统可能要求先退出 kiosk 或恢复出厂设置）：

adb shell dpm remove-active-admin <your.package>/uts.sdk.modules.shiftKiosk.DeviceAdminReceiver

Manifest 验证

可以使用内置脚本检查最终 APK 或已安装应用是否包含必要组件：

npm run verify:manifest -- <your.package>
npm run verify:manifest -- <your.package> /path/to/your-app.apk

最终 APK 至少应包含：

• uts.sdk.modules.shiftKiosk.DeviceAdminReceiver
• uts.sdk.modules.shiftKiosk.BootReceiver
• uts.sdk.modules.shiftKiosk.KioskHomeAlias
• res/xml/device_admin_receiver.xml

如果缺少组件，通常需要重新构建自定义基座 / APK，然后重新安装。

注意事项

适用场景

• 自助终端 / 信息亭
• 工厂平板 / 工业手持设备
• 展厅导览屏
• 数字标牌
• 考试或培训专用设备
• 只允许访问单一 App 的企业设备

你的应用需要自己实现的内容

本插件不是完整 kiosk 应用，只提供系统运行时能力。以下内容必须由你的应用实现：

• 管理员认证 / 密码校验
• 隐藏入口或可见的管理员入口
• 是否允许退出 kiosk 的业务规则
• 开机进入应用后何时调用 enableKiosk()

常见问题

Q：不使用 ADB 可以吗？

运行时 API 不需要 ADB。但首次设置 Device Owner 需要一种设备配置方式：ADB、MDM、Android Enterprise、NFC 或二维码配置都可以。普通开发和工厂部署最常见的是 ADB。

Q：非 Root 设备能用吗？

可以。Lock Task kiosk 不要求 Root，但要求 App 具备 Device Owner 身份。

Q：退出 kiosk 后 Device Owner 会被移除吗？

不会。disableKiosk() 只退出 Lock Task，并尝试清理本插件配置的 Lock Task 白名单和 persistent HOME。Device Owner 身份需要通过设备管理流程或 ADB 单独移除。

Q：为什么普通调试基座里不可用？

本插件包含 Android 原生 receiver、manifest 和 Kotlin 代码，需要进入最终 APK。请使用自定义运行基座或正式 APK 验证。

支持平台

• Android
• uni-app x App 端

不支持：

• Web
• iOS

隐私、权限声明

Android 权限

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

该权限用于设备重启后接收开机广播并拉起宿主 App。

Device Admin policy

插件包含 res/xml/device_admin_receiver.xml，用于声明 Android Device Admin 能力。当前 runtime API 使用其中的 Lock Task 相关能力，不采集、不上传任何数据。

数据采集

本插件不采集用户数据，不请求网络，不上传数据到服务器。

广告

本插件不包含广告。

许可证

MIT