ms-vite-plugin 1.5.9 → 1.5.11

package/docs/apilua/jbdevice.md

@@ -0,0 +1,609 @@
+# 设备模块 (JBDevice)
+
+模块表是内置全局 `jbdevice`，直接调用即可。不要 `require` 宿主模块。
+
+仅越狱包可用。免越狱包没有 `jbdevice`。
+
+可设置自动锁屏分钟数（`0` 为不自动锁屏）并还原，读取序列号和 Wi-Fi 信息 / MAC，打开或关闭 Wi-Fi / 蓝牙 / 蜂窝数据 / 飞行模式，读取开关，扫描附近或列出已保存无线网，加入或遗忘无线网，设置和获取音量与背光亮度。
+
+## 类型
+
+```lua
+---@class JbWifiInfo
+---@field ssid string
+---@field bssid string
+---@field password string
+---@field encryption string
+---@field channel integer
+---@field hidden boolean
+```
+
+| 字段         | 类型      | 描述                                      |
+| ------------ | --------- | ----------------------------------------- |
+| `ssid`       | string    | 无线网名称                                |
+| `bssid`      | string    | BSSID；没有则为空串                       |
+| `password`   | string    | 已保存密码；开放网络为空串                |
+| `encryption` | string    | 加密方式：`WEP` / `WPA` / `EAP` / `NONE` |
+| `channel`    | integer   | 信道                                      |
+| `hidden`     | boolean   | 是否隐藏网络                              |
+
+## API 参考
+
+### setAutoLockMinutes - 设置自动锁屏分钟数。
+
+`0` 表示不自动锁屏。
+
+```lua
+---@param minutes integer
+---@return boolean
+function setAutoLockMinutes(minutes) end
+```
+
+**参数:**
+
+| 参数名    | 类型    | 是否必填 | 默认值 | 描述                             |
+| --------- | ------- | -------- | ------ | -------------------------------- |
+| `minutes` | integer | 是       | -      | 锁屏分钟数；`<= 0` 视为不自动锁屏 |
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.setAutoLockMinutes(0)
+```
+
+### restoreAutoLock - 还原自动锁屏分钟数。
+
+没有可还原的值则失败。
+
+```lua
+---@return boolean
+function restoreAutoLock() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.restoreAutoLock()
+```
+
+### getAutoLockMinutes - 读取当前自动锁屏分钟数。
+
+`0` 表示不自动锁屏。
+
+```lua
+---@return integer|nil
+function getAutoLockMinutes() end
+```
+
+**返回值:**
+
+| 类型             | 描述                    |
+| ---------------- | ----------------------- |
+| `integer \| nil` | 分钟数；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local minutes = jbdevice.getAutoLockMinutes()
+```
+
+### serialNumber - 读取设备序列号。
+
+```lua
+---@return string|nil
+function serialNumber() end
+```
+
+**返回值:**
+
+| 类型            | 描述                    |
+| --------------- | ----------------------- |
+| `string \| nil` | 序列号；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local serial = jbdevice.serialNumber()
+```
+
+### wifiMac - 读取本机 Wi-Fi MAC。
+
+```lua
+---@return string|nil
+function wifiMac() end
+```
+
+**返回值:**
+
+| 类型            | 描述                                        |
+| --------------- | ------------------------------------------- |
+| `string \| nil` | `aa:bb:cc:dd:ee:ff` 形式；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local mac = jbdevice.wifiMac()
+```
+
+### wifiInfo - 读取当前已连接无线网信息。
+
+没连上返回 `nil`。
+
+```lua
+---@return JbWifiInfo|nil
+function wifiInfo() end
+```
+
+**返回值:**
+
+| 类型                | 描述                       |
+| ------------------- | -------------------------- |
+| `JbWifiInfo \| nil` | Wi-Fi 信息；没连上返回 `nil` |
+
+**示例:**
+
+```lua
+local info = jbdevice.wifiInfo()
+if info then
+    print(info.ssid)
+end
+```
+
+### wifiOn - 打开 Wi-Fi。
+
+```lua
+---@return boolean
+function wifiOn() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.wifiOn()
+```
+
+### wifiOff - 关闭 Wi-Fi。
+
+```lua
+---@return boolean
+function wifiOff() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.wifiOff()
+```
+
+### isWifiOn - 读取 Wi-Fi 是否打开。
+
+```lua
+---@return boolean|nil
+function isWifiOn() end
+```
+
+**返回值:**
+
+| 类型           | 描述                           |
+| -------------- | ------------------------------ |
+| `boolean \| nil` | 当前是否打开；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local on = jbdevice.isWifiOn()
+```
+
+### bluetoothOn - 打开蓝牙。
+
+```lua
+---@return boolean
+function bluetoothOn() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.bluetoothOn()
+```
+
+### bluetoothOff - 关闭蓝牙。
+
+```lua
+---@return boolean
+function bluetoothOff() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.bluetoothOff()
+```
+
+### isBluetoothOn - 读取蓝牙是否打开。
+
+```lua
+---@return boolean|nil
+function isBluetoothOn() end
+```
+
+**返回值:**
+
+| 类型           | 描述                           |
+| -------------- | ------------------------------ |
+| `boolean \| nil` | 当前是否打开；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local on = jbdevice.isBluetoothOn()
+```
+
+### cellularOn - 打开蜂窝数据。
+
+```lua
+---@return boolean
+function cellularOn() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.cellularOn()
+```
+
+### cellularOff - 关闭蜂窝数据。
+
+```lua
+---@return boolean
+function cellularOff() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.cellularOff()
+```
+
+### isCellularOn - 读取蜂窝数据是否打开。
+
+没有蜂窝能力时失败。
+
+```lua
+---@return boolean|nil
+function isCellularOn() end
+```
+
+**返回值:**
+
+| 类型           | 描述                           |
+| -------------- | ------------------------------ |
+| `boolean \| nil` | 当前是否打开；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local on = jbdevice.isCellularOn()
+```
+
+### airplaneOn - 打开飞行模式。
+
+```lua
+---@return boolean
+function airplaneOn() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.airplaneOn()
+```
+
+### airplaneOff - 关闭飞行模式。
+
+```lua
+---@return boolean
+function airplaneOff() end
+```
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.airplaneOff()
+```
+
+### isAirplaneOn - 读取飞行模式是否打开。
+
+```lua
+---@return boolean|nil
+function isAirplaneOn() end
+```
+
+**返回值:**
+
+| 类型           | 描述                           |
+| -------------- | ------------------------------ |
+| `boolean \| nil` | 当前是否打开；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local on = jbdevice.isAirplaneOn()
+```
+
+### joinWifi - 加入一个无线网。
+
+开放网络密码传空串。有密码时至少 8 位。可传 SSID 或 BSSID。
+
+```lua
+---@param ssid string
+---@param password? string
+---@param timeoutMs? integer
+---@return boolean
+function joinWifi(ssid, password, timeoutMs) end
+```
+
+**参数:**
+
+| 参数名      | 类型    | 是否必填 | 默认值  | 描述                                                           |
+| ----------- | ------- | -------- | ------- | -------------------------------------------------------------- |
+| `ssid`      | string  | 是       | -       | 无线网名称，也可传 BSSID；空串失败                             |
+| `password`  | string  | 否       | `""`    | 密码；开放网络传空串；长度 `1-7` 失败                          |
+| `timeoutMs` | integer | 否       | `15000` | 等待上限毫秒；`<= 0` 时用默认值，最短 `5000`，最长 `120000` |
+
+**返回值:**
+
+| 类型      | 描述                |
+| --------- | ------------------- |
+| `boolean` | 连上目标网为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.joinWifi("Office", "password123")
+```
+
+### forgetWifi - 遗忘一个已保存的无线网。
+
+可传 SSID 或 BSSID。空串失败。
+
+```lua
+---@param ssid string
+---@return boolean
+function forgetWifi(ssid) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述               |
+| ------ | ------ | -------- | ------ | ------------------ |
+| `ssid` | string | 是       | -      | 无线网名称或 BSSID |
+
+**返回值:**
+
+| 类型      | 描述                |
+| --------- | ------------------- |
+| `boolean` | 找到并删掉为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.forgetWifi("Office")
+```
+
+### listWifi - 列出已保存的无线网。
+
+没有已存网络时是空表。
+
+```lua
+---@return table|nil
+function listWifi() end
+```
+
+**返回值:**
+
+| 类型           | 描述                             |
+| -------------- | -------------------------------- |
+| `table \| nil` | Wi-Fi 信息表；读失败返回 `nil`   |
+
+**示例:**
+
+```lua
+local list = jbdevice.listWifi()
+if list then
+    for _, item in ipairs(list) do
+        print(item.ssid)
+    end
+end
+```
+
+### scanWifi - 扫描附近无线网。
+
+会先打开 Wi-Fi。附近没有网时是空表。
+
+```lua
+---@param timeoutMs? integer
+---@return table|nil
+function scanWifi(timeoutMs) end
+```
+
+**参数:**
+
+| 参数名      | 类型    | 是否必填 | 默认值  | 描述                                                           |
+| ----------- | ------- | -------- | ------- | -------------------------------------------------------------- |
+| `timeoutMs` | integer | 否       | `15000` | 等待上限毫秒；`<= 0` 时用默认值，最短 `5000`，最长 `120000` |
+
+**返回值:**
+
+| 类型           | 描述                             |
+| -------------- | -------------------------------- |
+| `table \| nil` | Wi-Fi 信息表；扫失败返回 `nil`   |
+
+**示例:**
+
+```lua
+local list = jbdevice.scanWifi()
+if list then
+    for _, item in ipairs(list) do
+        print(item.ssid)
+    end
+end
+```
+
+### setVolume - 设置系统音量。
+
+范围 `0.0-1.0`。
+
+```lua
+---@param volume number
+---@return boolean
+function setVolume(volume) end
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述     |
+| -------- | ------ | -------- | ------ | -------- |
+| `volume` | number | 是       | -      | 目标音量 |
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.setVolume(0.5)
+```
+
+### getVolume - 读取系统音量。
+
+范围 `0.0-1.0`。
+
+```lua
+---@return number|nil
+function getVolume() end
+```
+
+**返回值:**
+
+| 类型            | 描述                       |
+| --------------- | -------------------------- |
+| `number \| nil` | 当前音量；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local volume = jbdevice.getVolume()
+```
+
+### setBrightness - 设置背光亮度。
+
+范围 `0.0-1.0`。
+
+```lua
+---@param brightness number
+---@return boolean
+function setBrightness(brightness) end
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述     |
+| ------------ | ------ | -------- | ------ | -------- |
+| `brightness` | number | 是       | -      | 目标亮度 |
+
+**返回值:**
+
+| 类型      | 描述          |
+| --------- | ------------- |
+| `boolean` | 成功为 `true` |
+
+**示例:**
+
+```lua
+jbdevice.setBrightness(0.5)
+```
+
+### getBrightness - 读取背光亮度。
+
+范围 `0.0-1.0`。
+
+```lua
+---@return number|nil
+function getBrightness() end
+```
+
+**返回值:**
+
+| 类型            | 描述                       |
+| --------------- | -------------------------- |
+| `number \| nil` | 当前亮度；读不到返回 `nil` |
+
+**示例:**
+
+```lua
+local brightness = jbdevice.getBrightness()
+```