zt-electron-kiosk

一个用于 Electron 主进程的工具包，提供自助终端模式（Kiosk）及触控板相关能力。

GitHub 仓库地址：https://github.com/lzt-T/zt-electron-kiosk

Installation

npm install zt-electron-kiosk zt-block-system-shortcuts

zt-block-system-shortcuts 需由使用方显式安装，用于提供系统快捷键禁用能力。
如果未安装该依赖，Kiosk 快捷键拦截会降级并输出安装提示日志。

如果你在公司网络或代理环境中安装失败，请优先检查：

• 是否可访问 GitHub Releases
• HTTP_PROXY / HTTPS_PROXY 配置是否正确
• 是否存在拦截下载的企业安全策略

Usage

Kiosk 主流程（推荐接入方式）

以下示例用于 Electron 主进程。
调用顺序建议为：app.whenReady -> createWindow -> createKiosk -> enter/exit -> destroyKiosk。

import { app, BrowserWindow, ipcMain } from 'electron'
import {
  createKiosk,
  destroyKiosk,
  isElectronEnvironment,
} from 'zt-electron-kiosk'

let mainWindow: BrowserWindow | null = null
const kiosk = createKiosk({
  name: 'my-kiosk',
  debug: true,
  alwaysOnTop: true,
  // 仅 Windows 生效：进入 Kiosk 时隐藏“切换账户”入口，退出时恢复显示
  manageSwitchAccountOnWindows: true,
})

function createWindow(): BrowserWindow {
  return new BrowserWindow({
    width: 1280,
    height: 800,
  })
}

app.whenReady().then(() => {
  // 建议在非 Electron 环境提前短路
  if (!isElectronEnvironment()) {
    return
  }

  mainWindow = createWindow()

  // 进入 Kiosk：必须传入有效 BrowserWindow 实例
  ipcMain.on('kiosk:enter', () => {
    if (!mainWindow || mainWindow.isDestroyed()) {
      return
    }
    kiosk.enter(mainWindow)
  })

  // 退出 Kiosk
  ipcMain.on('kiosk:exit', () => {
    kiosk.exit()
  })
})

app.on('before-quit', () => {
  // 应用退出前做资源清理
  destroyKiosk()
})

触控板能力（可选）

import { getTouchpadManager } from 'zt-electron-kiosk'

const touchpadManager = getTouchpadManager()
const settings = await touchpadManager.getTouchpadSettings()
const pass = await touchpadManager.isPassTouchpad()

常见误区提示

• createKiosk 是单例语义，多次调用不会创建多个独立实例。
• enter(window) 需要可用的 BrowserWindow；销毁窗口后请勿复用旧引用。
• 未安装 zt-block-system-shortcuts 时，系统快捷键拦截会降级并输出提示日志。

Development

# 安装依赖
npm install

# 构建包
npm run build

# 监听模式
npm run dev

# 运行 Electron 示例
npm run example:build
npm run example

API

createKiosk(options?: KioskOptions)

创建一个自助终端模式（Kiosk）实例。
进入 Kiosk 时会在 Electron 主进程中禁用系统快捷键；在退出或 dispose 后会自动恢复。

KioskOptions 可选项补充：

• manageSwitchAccountOnWindows?: boolean
  • 仅 Windows 生效。
  • 当为 true 时：enter 阶段会隐藏系统“切换账户”入口，exit 阶段恢复显示。
  • 该能力依赖写入系统注册表，通常需要管理员权限。

getTouchpadManager()

创建或返回单例 TouchpadManager 实例。
触控板能力仅在 Windows 平台生效；在非 Windows 平台上，相关方法会返回安全的默认值。

import { getTouchpadManager } from 'zt-electron-kiosk'

const touchpadManager = getTouchpadManager()
const settings = await touchpadManager.getTouchpadSettings()
const pass = await touchpadManager.isPassTouchpad()

TouchpadManager

Windows 触控板工具类，支持：

• 打开触控板设置页面
• 判断设备是否可能为笔记本机型
• 检查三指/四指滑动配置

isElectronEnvironment()

检查当前代码是否运行在 Electron 环境中。

VERSION

当前包版本号。

License

MIT