更新记录

1.0.0（2026-10-14） 下载此版本

• 首次发布
• 提供 TerminalCapabilities、TerminalDevice 类型定义
• 依赖 pro-device-core

平台兼容性

uni-app(5.06)

pro-device-terminal — 手持终端接口

定义手持终端设备的接口 TerminalDevice 和能力声明类型 TerminalCapabilities。本包只包含接口定义，不含任何具体设备实现。

依赖 pro-device-core。具体终端实现在项目层 src/devices/terminal/ 中。

设计理念

手持终端（如商米 T2、T3 等工业 PDA）与普通外设的本质区别：

• 终端本身不需要"连接"——它就是运行 App 的当前设备
• 终端提供设备身份信息（品牌、型号、序列号）
• 终端声明其内置外设能力（内置打印机、内置扫码头等）
• Store 层根据 capabilities 自动初始化对应的内置设备

TerminalCapabilities<TKey> 中的 TKey 由项目层传入，使本包与具体设备类型解耦。

导出内容

import type { TerminalDevice, TerminalCapabilities } from '@/uni_modules/pro-device-terminal'

API 参考

TerminalCapabilities<TKey> — 终端能力声明

// 等价于：键存在 → 具备该内置外设；键缺失 → 无该外设
type TerminalCapabilities<TKey extends string = string> =
  Partial<Record<TKey, DeviceConfig>>

// 项目中 TKey = BuiltInDeviceType = 'print' | 'scanner'
type BuiltInDeviceType = 'print' | 'scanner'
type MyCapabilities = TerminalCapabilities<BuiltInDeviceType>
// 等价于：{ print?: DeviceConfig; scanner?: DeviceConfig }

TerminalDevice<TKey> — 终端设备接口

interface TerminalDevice<TKey extends string = string> extends IIdentifiable {
  readonly capabilities: TerminalCapabilities<TKey>
}

使用示例

1. 读取终端信息

import { createDeviceSession, detectTerminalConfig } from '@/devices'

const session = createDeviceSession()

// detectTerminalConfig() 读取当前设备品牌/型号，匹配注册表
const config = detectTerminalConfig()
if (!config) {
  console.log('非已知终端设备，跳过终端初始化')
  return
}

const terminal = await session.acquire('terminal', config)

console.log('终端品牌:', terminal.info.brand)       // 'sunmi'
console.log('终端型号:', terminal.info.model)       // 'T2'
console.log('序列号:',   terminal.info.serialNumber) // 'SM-2026XXXXX'

2. 根据能力声明自动初始化内置外设

// 商米 T2 终端声明了内置打印机和内置扫码头
// terminal.capabilities = {
//   print:   { brand: 'sunmi', model: 'built-in' },
//   scanner: { brand: 'sunmi', model: 'infrared' },
// }

const caps = terminal.capabilities

// 自动初始化声明了的内置外设
if (caps.print) {
  const printer = await session.acquire('print', caps.print)
  console.log('内置打印机已就绪')
}

if (caps.scanner) {
  const scanner = await session.acquire('scanner', caps.scanner)
  scanner.onScan(code => console.log('扫码:', code))
}

3. 配合 app-device Store 自动初始化（推荐用法）

// 在 App.vue 或 app-device.ts store 中（实际已封装好）
import { detectTerminalConfig, createDeviceSession } from '@/devices'

const config = detectTerminalConfig()
if (config) {
  const session = createDeviceSession()
  const terminal = await session.acquire('terminal', config)

  // store 遍历 capabilities，自动初始化声明的内置外设
  for (const [type, capConfig] of Object.entries(terminal.capabilities)) {
    if (capConfig) {
      await session.acquire(type as DeviceType, capConfig)
    }
  }
}

4. 在 Vue 组件中检查终端信息

import { useAppDeviceStore } from '@/plugins/store/app-device'

const appDeviceStore = useAppDeviceStore()

// 读取已初始化的终端信息
const terminalEntry = appDeviceStore.devices.find(d => d.type === 'terminal')
if (terminalEntry) {
  console.log('当前终端:', terminalEntry.label)        // 例：'sunmi T2'
  console.log('连接状态:', terminalEntry.status)       // 'connected'
}

// 判断是否在商米终端上运行
const isOnSunmi = terminalEntry?.id.startsWith('sunmi')

实现新终端设备

在项目层 src/devices/terminal/ 创建具体实现，继承 IIdentifiable 并声明 capabilities：

// src/devices/terminal/my-device.ts
import type { TerminalDevice } from '@/uni_modules/pro-device-terminal'
import type { DeviceInfo } from '@/uni_modules/pro-device-core'
import type { BuiltInDeviceType } from '@/devices/interfaces'

export class MyPDATerminal implements TerminalDevice<BuiltInDeviceType> {
  readonly info: Readonly<DeviceInfo>

  constructor() {
    const sysInfo = uni.getSystemInfoSync()
    this.info = {
      brand:  sysInfo.deviceBrand ?? 'unknown',
      model:  sysInfo.deviceModel ?? 'unknown',
      // serialNumber: readSN(),  // 若有 SDK 可读取 SN
    }
  }

  get capabilities() {
    // 声明该终端具备哪些内置外设
    return {
      print:   { brand: 'my-brand', model: 'built-in-printer' },
      scanner: { brand: 'my-brand', model: 'built-in-scanner' },
    }
  }
}

// src/devices/index.ts 中注册
const terminalRegistry = new DeviceRegistry<TerminalDevice>()
  .registerBrand('sunmi', cfg => new SunmiTerminal(cfg))
  .registerBrand('my-brand', () => new MyPDATerminal())  // 新增

平台支持

本包为纯 TypeScript 接口定义，无平台依赖。

终端设备通常只在 APP-PLUS（Android）平台存在，但接口本身无平台限制——在非 APP 环境下 detectTerminalConfig() 会返回 null，Store 层会跳过终端初始化。