PowerSDK

概述

PowerSDK 用来给插件读取当前省电状态，方便在低电量场景下自动降级高耗能能力。

快速开始

import { usePowerSDK } from '@talex-touch/utils/plugin/sdk'

const power = usePowerSDK()

const status = await power.getLowPowerStatus()
if (status.lowPower) {
  console.log('切换到轻量模式')
}

API 参考

`usePowerSDK()`

在插件渲染上下文中获取 PowerSDK 实例。

`getLowPowerStatus(options?)`

获取当前省电状态。

参数：

threshold?: number（默认 20，范围 1-100）

返回值：

字段	类型	说明
`lowPower`	`boolean`	当前是否处于省电模式
`onBattery`	`boolean`	当前是否为电池供电
`percent`	`number \| null`	电量百分比，不可用时为 `null`
`threshold`	`number`	本次计算使用的阈值

`isLowPower(options?)`

便捷方法，等价于 getLowPowerStatus(options).lowPower。

`onLowPowerChanged(callback, options?)`

监听省电状态变化。

参数：

threshold?: number（默认 20）
emitImmediately?: boolean（默认 true）

返回取消监听函数。

const dispose = power.onLowPowerChanged((status) => {
  console.log('省电状态变化', status)
})

// 后续取消监听
dispose()

index.js 全局上下文

插件 index.js 中可直接使用 globalThis.power：

const status = await power.getLowPowerStatus({ threshold: 25 })
if (status.lowPower) {
  logger.info('低电量时跳过高负载任务')
}

技术说明

在插件渲染上下文里，usePowerSDK().onLowPowerChanged 走 transport 电量事件回调。
在插件 index.js 全局上下文（globalThis.power）里，onLowPowerChanged 当前是轮询策略（约 60 秒），不是严格实时推送。

最佳实践

lowPower 为 true 时暂停高耗能后台任务。
percent 为 null 时提供可接受的兜底策略。
OCR/AI 等重任务建议使用更高阈值（例如 25）。