ms-vite-plugin 1.5.8 → 1.5.10

package/docs/api/jbdevice.md

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