ms-vite-plugin 1.1.2 → 1.1.3

package/docs/api/device.md

@@ -0,0 +1,374 @@
+# 设备模块 (Device)
+
+设备模块提供了获取设备信息和设备操作的功能，包括电池信息、设备标识、屏幕信息、系统信息等。
+
+## 电池信息
+
+### getBatteryInfo - 获取设备的电池信息。
+
+```typescript
+function getBatteryInfo(): {
+  level: number; // 电池电量（0-100）
+  isCharging: boolean; // 是否正在充电
+};
+```
+
+**返回值：**
+
+| 参数名       | 类型    | 描述                    |
+| ------------ | ------- | ----------------------- |
+| `level`      | number  | 电池电量百分比（0-100） |
+| `isCharging` | boolean | 是否正在充电            |
+
+**示例：**
+
+```typescript
+// 获取电池信息
+const battery = device.getBatteryInfo();
+logi(`电池电量: ${battery.level}%`);
+logi(`充电状态: ${battery.isCharging ? "充电中" : "未充电"}`);
+```
+
+## 存储空间信息
+
+### getStorageSpace - 获取设备存储空间信息。
+
+```typescript
+function getStorageSpace(): {
+  total: number; // 总存储空间（GB，十进制）
+  free: number; // 剩余存储空间（GB，十进制）
+  unit: string; // 单位，固定为 GB
+};
+```
+
+**返回值：**
+
+| 参数名  | 类型   | 描述                                    |
+| ------- | ------ | --------------------------------------- |
+| `total` | number | 总存储空间（单位 GB，按 10 进制计算）   |
+| `free`  | number | 剩余可用空间（单位 GB，按 10 进制计算） |
+| `unit`  | string | 单位，固定返回 `"GB"`                   |
+
+**示例：**
+
+```typescript
+const storage = device.getStorageSpace();
+logi(`总存储: ${storage.total}${storage.unit}`);
+logi(`剩余存储: ${storage.free}${storage.unit}`);
+```
+
+## 设备标识信息
+
+### getDeviceID - 获取设备的唯一标识符（ID）。
+
+**注意事项：**
+
+- 这个 ID 卸载重装 APP 后会改变。
+- 更新 APP 后，不会改变。
+
+```typescript
+function getDeviceID(): string;
+```
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| string | 设备的唯一标识符 |
+
+**示例：**
+
+```typescript
+// 获取设备ID
+const uuid = device.getDeviceID();
+logi(`设备ID: ${uuid}`);
+```
+
+### getServerDeviceId - 获取服务器设备 ID。
+
+**注意事项：**
+
+- 这个 ID 卸载重装后，只要签名没变，就不会改变。
+- 如果要取唯一 ID 建议使用这个。
+
+```typescript
+function getServerDeviceId(): string;
+```
+
+**返回值：**
+
+| 类型     | 描述                |
+| -------- | ------------------- |
+| `string` | 服务器分配的设备 ID |
+
+**示例：**
+
+```typescript
+// 获取服务器设备ID
+const serverDeviceId = device.getServerDeviceId();
+logi(`服务器设备ID: ${serverDeviceId}`);
+```
+
+### getECID - 获取设备 ECID。
+
+**注意事项：**
+
+- 这个 ID 只有自激活一次后才能获取
+
+```typescript
+function getECID(): string;
+```
+
+**返回值：**
+
+| 类型     | 描述                         |
+| -------- | ---------------------------- |
+| `string` | ECID 字符串 设备的唯一标识符 |
+
+**示例：**
+
+```typescript
+// 获取ECID
+const ecid = device.getECID();
+logi(`ECID: ${ecid}`);
+```
+
+### getUDID - 获取设备 UDID。
+
+**注意事项：**
+
+- 这个 ID 只有自激活一次后才能获取
+
+```typescript
+function getUDID(): string;
+```
+
+**返回值：**
+
+| 类型     | 描述                         |
+| -------- | ---------------------------- |
+| `string` | UDID 字符串 设备的唯一标识符 |
+
+**示例：**
+
+```typescript
+// 获取UDID
+const udid = device.getUDID();
+logi(`UDID: ${udid}`);
+```
+
+### getDeviceName - 获取设备名称。
+
+```typescript
+function getDeviceName(): string;
+```
+
+**返回值：**
+
+| 类型     | 描述     |
+| -------- | -------- |
+| `string` | 设备名称 |
+
+**示例：**
+
+```typescript
+// 获取设备名称
+const deviceName = device.getDeviceName();
+logi(`设备名称: ${deviceName}`);
+```
+
+### getDeviceModel - 获取设备型号。
+
+```typescript
+function getDeviceModel(): string;
+```
+
+**返回值：**
+
+| 类型     | 描述     |
+| -------- | -------- |
+| `string` | 设备型号 |
+
+**示例：**
+
+```typescript
+// 获取设备型号
+const model = device.getDeviceModel();
+logi(`设备型号: ${model}`);
+```
+
+## 屏幕信息
+
+### getScreenSize - 获取屏幕尺寸（缩放后的）。
+
+**注意事项：**
+
+- 该方法返回的屏幕尺寸是根据当前设备的屏幕分辨率除以缩放比例计算得到的。
+- 注意该方法只会返回竖屏分辨率。
+
+```typescript
+function getScreenSize(): {
+  width: number; // 屏幕宽度（像素）
+  height: number; // 屏幕高度（像素）
+};
+```
+
+**返回值：**
+
+| 参数名   | 类型   | 描述             |
+| -------- | ------ | ---------------- |
+| `width`  | number | 屏幕宽度（像素） |
+| `height` | number | 屏幕高度（像素） |
+
+**示例：**
+
+```typescript
+// 获取屏幕尺寸
+const screenSize = device.getScreenSize();
+logi(`屏幕尺寸: ${screenSize.width} x ${screenSize.height}`);
+```
+
+### getScreenRealSize - 获取屏幕实际尺寸。
+
+**注意事项：**
+
+- 该方法返回的屏幕尺寸是根据当前设备的屏幕实际分辨率。
+- 注意该方法只会返回竖屏分辨率。
+
+```typescript
+function getScreenRealSize(): {
+  width: number; // 屏幕宽度（像素）
+  height: number; // 屏幕高度（像素）
+};
+```
+
+**返回值：**
+
+| 参数名   | 类型   | 描述             |
+| -------- | ------ | ---------------- |
+| `width`  | number | 屏幕宽度（像素） |
+| `height` | number | 屏幕高度（像素） |
+
+**示例：**
+
+```typescript
+// 获取屏幕实际尺寸
+const screenRealSize = device.getScreenRealSize();
+logi(`屏幕实际尺寸: ${screenRealSize.width} x ${screenRealSize.height}`);
+```
+
+### getScreenScale - 获取屏幕缩放比例。
+
+```typescript
+function getScreenScale(): number;
+```
+
+**返回值：**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `number` | 屏幕缩放比例 |
+
+**示例：**
+
+```typescript
+// 获取屏幕缩放比例
+const scale = device.getScreenScale();
+logi(`屏幕缩放比例: ${scale}`);
+```
+
+### getOrientation - 获取屏幕方向。
+
+**注意事项**
+
+- 该方法返回的方向，是靠截屏方法来更新的，如果没有截屏，该方法返回的方向可能是不准确的。
+- 该方法取到的方向可能不准，建议使用截屏，靠截屏的图片宽高来确定方向
+
+```typescript
+function getOrientation(): "PORTRAIT" | "LANDSCAPE";
+```
+
+**返回值：**
+
+| 类型     | 描述                                                    |
+| -------- | ------------------------------------------------------- |
+| `string` | 设备方向，`"PORTRAIT"` 竖屏模式，`"LANDSCAPE"` 横屏模式 |
+
+**示例：**
+
+```typescript
+// 获取屏幕方向
+const orientation = device.getOrientation();
+logi(`屏幕方向: ${orientation}`);
+```
+
+## 系统信息
+
+### getOSVersion - 获取操作系统版本。
+
+```typescript
+function getOSVersion(): string;
+```
+
+**返回值：**
+
+| 类型     | 描述                       |
+| -------- | -------------------------- |
+| `string` | 系统版本号（如 "16.7.11"） |
+
+**示例：**
+
+```typescript
+// 获取系统版本
+const osVersion = device.getOSVersion();
+logi(`系统版本: iOS ${osVersion}`);
+```
+
+### getLanIp - 获取设备的局域网 IP 地址。
+
+```typescript
+function getLanIp(): string;
+```
+
+**返回值：**
+
+| 类型     | 描述                                 |
+| -------- | ------------------------------------ |
+| `string` | 局域网 IP 地址（如 "192.168.1.100"） |
+
+**示例：**
+
+```typescript
+// 获取局域网IP
+const lanIp = device.getLanIp();
+logi(`局域网IP: ${lanIp}`);
+```
+
+## 设备操作
+
+### vibrate - 控制设备振动。
+
+```typescript
+function vibrate(
+  duration: number, // 持续时间（毫秒）
+  intensity: number, // 强度（0.0-1.0）
+): void;
+```
+
+**参数说明：**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                           |
+| ----------- | ------ | -------- | ------ | ---------------------------------------------- |
+| `duration`  | number | 是       | -      | 振动持续时间，单位毫秒                         |
+| `intensity` | number | 是       | -      | 振动强度，范围 0.0-1.0，0.0 为最弱，1.0 为最强 |
+
+**示例：**
+
+```typescript
+// 基础振动
+device.vibrate(500, 0.5); // 振动500ms，中等强度
+// 不同强度的振动
+device.vibrate(200, 0.2); // 轻微振动
+device.vibrate(300, 0.8); // 强烈振动
+device.vibrate(100, 1.0); // 最强振动
+```