Kiosk 模式 - 无需 JS 调用集成方案

🎯 需求说明

在 UniApp 离线 Android 工程中，实现 Kiosk 模式功能（禁用锁屏、防退出等）无需通过 JS 调用，应用启动时自动激活。

✅ 解决方案

核心思路

通过自定义 Application 类，在应用启动时自动注册 Activity 生命周期监听，当主 Activity 创建时自动调用 Kiosk 相关功能。

实现文件

1. MyApplication.java - 自定义 Application

路径：app/src/main/java/com/YuyeTech/HeartRate/MyApplication.java
作用：
- 继承 DCloudApplication（保持 UniApp 功能）
- 注册 Activity 生命周期回调
- 在 PandoraEntry/PandoraEntryActivity 创建时自动初始化 Kiosk

2. KioskHelper.java - 锁屏控制辅助类

路径：app/src/main/java/com/YuyeTech/HeartRate/KioskHelper.java
提供方法：
- disableLockScreen(Activity) - 禁用锁屏
- keepScreenOn(Activity) - 屏幕常亮
- enableLockScreen(Activity) - 恢复锁屏

3. AndroidManifest.xml - 配置清单

修改 Application 为 com.YuyeTech.HeartRate.MyApplication
添加必要权限和 Receiver

4. device_admin.xml - Device Admin 策略

路径：app/src/main/res/xml/device_admin.xml
定义设备管理员权限

📦 涉及的模块

myLockView 模块

提供以下功能：

✅ KioskManager - Kiosk 模式管理（LockTask、全屏、按键拦截）
✅ KioskDeviceAdminReceiver - Device Admin 接收器
✅ BootReceiver - 开机启动支持
✅ 五指逃生门 - 5 指长按 5 秒 + 密码 9527 退出

myWIFIView 模块

提供 WiFi 配置功能：

📶 WiFi 扫描
🔐 WiFi 连接（支持开放/加密网络）
📱 WiFi 断开
💡 注意：这是交互式功能，需要通过 JS 调用 showWifiDialogView()

🔄 执行流程

应用启动
    ↓
MyApplication.onCreate()
    ↓
注册 ActivityLifecycleCallbacks
    ↓
PandoraEntry 创建
    ↓
onActivityCreated() 被触发
    ↓
判断是否为主 Activity
    ↓
KioskHelper.disableLockScreen(activity)  ← ✅ 自动执行（无需 JS）
    ↓
KioskHelper.keepScreenOn(activity)       ← ✅ 自动执行（无需 JS）
    ↓
KioskManager.attach(activity)            ← ✅ 自动执行（无需 JS）
    ↓
进入 Kiosk 模式

🔑 关键配置

1. AndroidManifest.xml 修改

<!-- 替换 Application -->
<application
    android:name="com.YuyeTech.HeartRate.MyApplication"  <!-- ← 改这里 -->
    ...>

<!-- 添加权限 -->
<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<!-- 添加 Device Admin Receiver -->
<receiver
    android:name="com.ble.mylockview.admin.KioskDeviceAdminReceiver"
    android:permission="android.permission.BIND_DEVICE_ADMIN"
    android:exported="true">
    <meta-data
        android:name="android.app.device_admin"
        android:resource="@xml/device_admin" />
    <intent-filter>
        <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" />
    </intent-filter>
</receiver>

2. MyApplication 核心代码

@Override
public void onCreate() {
    super.onCreate();
    
    // 配置 Kiosk
    LaunchConfig.setLaunchActivity(PandoraEntry.class);
    KioskManager.setDebug(BuildConfig.DEBUG);
    
    // 注册生命周期监听
    registerActivityLifecycleCallbacks(new ActivityLifecycleCallbacks() {
        @Override
        public void onActivityCreated(@NonNull Activity activity, @Nullable Bundle savedInstanceState) {
            if (activity instanceof io.dcloud.PandoraEntry || 
                activity instanceof io.dcloud.PandoraEntryActivity) {
                
                // ✅ 自动禁用锁屏（无需 JS 调用）
                KioskHelper.disableLockScreen(activity);
                KioskHelper.keepScreenOn(activity);
                
                // ✅ 自动绑定 KioskManager
                KioskManager.attach(activity);
            }
        }
        
        @Override
        public void onActivityResumed(@NonNull Activity activity) {
            if (activity instanceof io.dcloud.PandoraEntry || 
                activity instanceof io.dcloud.PandoraEntryActivity) {
                KioskManager.onResume();
            }
        }
        
        // ... 其他生命周期回调
    });
}

🚀 部署步骤

第 1 步：设置 Device Owner（必需）

⚠️ 完整 Kiosk 功能需要 Device Owner 权限

# 1. 恢复出厂设置（移除所有账号）
# 2. 安装 APK
adb install app-release.apk

# 3. 设置为 Device Owner
adb shell dpm set-device-owner com.YuyeTech.HeartRate/com.ble.mylockview.admin.KioskDeviceAdminReceiver

# 4. 验证
adb shell dumpsys device_policy | grep "Device Owner"

第 2 步：编译测试

# Debug 版本（宽松模式）
./gradlew assembleDebug

# Release 版本（严格模式）
./gradlew assembleRelease

第 3 步：验证功能

# 查看日志
adb logcat | grep -E "MyApplication|KioskHelper|KioskManager"

# 期望看到：
# D MyApplication: Application 初始化
# D MyApplication: ✅ 绑定 Kiosk 到: PandoraEntry
# D KioskHelper: ✅ 锁屏已禁用
# D KioskHelper: ✅ 屏幕保持常亮
# D KioskManager: ✅ LockTask 启用（一次）

📊 功能对比

功能	Device Owner	非 Device Owner
自动初始化	✅	✅
屏幕常亮	✅	✅
全屏沉浸	✅	✅
禁用锁屏	✅	❌
LockTask 模式	✅	❌
拦截 Home/Back	✅	⚠️ 部分
五指逃生门	✅	✅

🐛 常见问题

Q1: 日志显示 "⚠️ 不是 Device Owner"

A: 应用可以运行，但 Kiosk 功能受限。需要按照"部署步骤"设置 Device Owner。

Q2: 无法设置 Device Owner

确保设备恢复出厂设置
移除所有账号（包括 Google 账号）
不要在初始设置中登录账号
重新执行 dpm set-device-owner 命令

Q3: 应用启动后没有进入 Kiosk 模式

A: 检查：

AndroidManifest.xml 中 Application 是否改为 MyApplication
查看日志是否有 ✅ 绑定 Kiosk 到: PandoraEntry
确认是否设置为 Device Owner

Q4: 如何退出 Kiosk 模式？

运维人员：5 指长按 5 秒 → 输入密码 9527

开发者：

adb shell am task lock stop
# 或
adb shell am force-stop com.YuyeTech.HeartRate

🔧 自定义配置

修改管理员密码

// myLockView/src/main/java/com/ble/mylockview/admin/KioskManager.java
private static final String ADMIN_PASSWORD = "您的新密码";

修改逃生门条件

private static final int ADMIN_FINGER_COUNT = 5;      // 手指数量
private static final long ADMIN_HOLD_TIME = 5000;     // 长按时间（毫秒）

禁用开机自启动

<!-- AndroidManifest.xml -->
<receiver
    android:name="com.ble.mylockview.boot.BootReceiver"
    android:enabled="false"  <!-- 改为 false -->
    ...>

📚 相关文档

KIOSK_SETUP_GUIDE.md - 详细配置指南
QUICK_TEST_GUIDE.md - 快速测试指南（无需 Device Owner）

💡 最佳实践

开发阶段：
- 使用 Debug 模式（BuildConfig.DEBUG = true）
- 不设置 Device Owner，方便调试
- 保留 ADB 访问权限
测试阶段：
- 在测试设备上设置 Device Owner
- 验证完整 Kiosk 功能
- 测试五指逃生门
生产部署：
- 使用 Release 模式
- 批量配置 Device Owner（NFC/QR Code）
- 修改默认管理员密码
- 准备应急恢复方案

📞 技术支持

查看详细日志：

adb logcat -v time | grep -E "KioskManager|MyApplication|KioskHelper|BootLauncher"

检查 Device Owner 状态：

adb shell dumpsys device_policy

移除 Device Owner（应急）：

adb shell dpm remove-active-admin com.YuyeTech.HeartRate/com.ble.mylockview.admin.KioskDeviceAdminReceiver

创建时间：2026-01-22
适用版本：UniApp 离线打包 + Android 8.0+
核心优势：✅ 无需 JS 调用，应用启动自动激活 Kiosk 模式

README_KIOSK_INTEGRATION.md 8.3 KB Histórico Raw