ms-vite-plugin 1.5.9 → 1.5.10

package/docs/apipython/jbdevice.md

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