快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-android-kiosk` plugin in my project.

如果你更倾向于手动设置，请运行以下命令安装插件，并参考下文针对各平台的具体说明：

npm install @capgo/capacitor-android-kiosk
npx cap sync

导入

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

快速入门

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

await CapacitorAndroidKiosk.enterKioskMode();

常见坑点

• Launcher: 将应用设为默认启动器，实现可靠的 Kiosk 模式锁定。
• MDM: 在发布大规模设备版本前，验证退出机制。
• iOS: 不支持。

API 概览

isInKioskMode

检查应用当前是否正处于 Kiosk 模式。

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

const { isInKioskMode } = await CapacitorAndroidKiosk.isInKioskMode();
console.log('Kiosk mode active:', isInKioskMode);

isSetAsLauncher

检查应用是否已被设置为设备启动器（Home 应用）。

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

const { isLauncher } = await CapacitorAndroidKiosk.isSetAsLauncher();
console.log('Is launcher:', isLauncher);

enterKioskMode

进入 Kiosk 模式，隐藏系统 UI 并屏蔽硬件按键。 同时启动前台保活服务，降低应用被系统杀掉的概率。 应用必须设为设备启动器，该功能才能有效工作。

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

await CapacitorAndroidKiosk.enterKioskMode();

exitKioskMode

退出 kiosk 模式，恢复正常的系统 UI 和硬件按键功能。 同时停止由 enterKioskMode() 启动的前台保活服务。

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

await CapacitorAndroidKiosk.exitKioskMode();
console.log('Exited kiosk mode');

setAsLauncher

打开设备的桌面设置，允许用户将此应用设为 Launcher。 这是实现完整 kiosk 模式功能的必要步骤。

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

await CapacitorAndroidKiosk.setAsLauncher();
// User will be prompted to select this app as the home app

setAllowedKeys

设置在 kiosk 模式下允许使用的硬件按键。 默认情况下，kiosk 模式会禁用所有硬件按键。

import { CapacitorAndroidKiosk } from '@capgo/capacitor-android-kiosk';

// Allow volume keys only
await CapacitorAndroidKiosk.setAllowedKeys({
  volumeUp: true,
  volumeDown: true,
  back: false,
  home: false,
  recent: false
});

类型参考

EnterKioskModeOptions

可选参数： enterKioskMode.

export interface EnterKioskModeOptions {
  /**
   * After reboot, start the app so you can call `enterKioskMode()` again. Best-effort only (OEM
   * behavior, force-stop). Omit to keep the saved value. Cleared when you call `exitKioskMode()`.
   */
  restoreAfterReboot?: boolean;

  /**
   * Periodically tries to bring the app to the foreground. Skipped while the screen is off. Often
   * blocked from the background on some devices—being the default launcher, relaxing battery limits,
   * and allowing exact alarms (where required) improve odds. Omit to keep the saved value.
   */
  relaunch?: boolean;

  /** Minutes between relaunch attempts when `relaunch` is on. Range 5–60; default 15. */
  relaunchIntervalMinutes?: number;
}

AllowedKeysOptions

Kiosk 模式下允许使用的硬件按键配置选项。

export interface AllowedKeysOptions {
  /**
   * Allow volume up button
   * @default false
   */
  volumeUp?: boolean;

  /**
   * Allow volume down button
   * @default false
   */
  volumeDown?: boolean;

  /**
   * Allow back button
   * @default false
   */
  back?: boolean;

  /**
   * Allow home button
   * @default false
   */
  home?: boolean;

  /**
   * Allow recent apps button
   * @default false
   */
  recent?: boolean;

  /**
   * Allow power button
   * @default false
   */
  power?: boolean;

  /**
   * Allow camera button (if present)
   * @default false
   */
  camera?: boolean;

  /**
   * Allow menu button (if present)
   * @default false
   */
  menu?: boolean;
}

唯一数据源

本页面由该插件的 src/definitions.ts当上游的公共 API 发生变化时，请重新运行 sync。

继续阅读入门指南

如果你正在使用 快速入门 来规划 dashboard 和 API 操作，请将其连接至 使用 @capgo/capacitor-android-kiosk 在“使用 @capgo/capacitor-android-kiosk”中实现原生能力， API 概览 关于 API 概览中的实现细节， 简介 有关 Introduction 中的实现细节， API 密钥 有关 API Keys 中的实现细节，以及 设备 有关 Devices 中的实现细节。