ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apicn/device.md

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