ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apipython/device.md

@@ -0,0 +1,365 @@
+# 设备模块 (Device)
+
+设备模块提供设备信息与操作能力，包括电池信息、设备标识、屏幕信息、系统信息与设备振动等。
+
+## 电池信息
+
+### getBatteryInfo - 获取设备的电池信息。
+
+```python
+from typing import TypedDict, Literal
+
+class BatteryInfo(TypedDict):
+    level: int  # 电池电量（0-100）
+    isCharging: bool  # 是否正在充电
+
+def getBatteryInfo() -> BatteryInfo:
+```
+
+**返回值:**
+
+| 参数名       | 类型 | 描述                    |
+| ------------ | ---- | ----------------------- |
+| `level`      | int  | 电池电量百分比（0-100） |
+| `isCharging` | bool | 是否正在充电            |
+
+**示例:**
+
+```python
+from kuaijs import device
+info = device.getBatteryInfo()
+print(f"电量: {info.level}%, 充电状态: {info.isCharging}")
+if info.level < 20:
+    print("电池电量低于 20%")
+```
+
+## 存储空间信息
+
+### getStorageSpace - 获取设备存储空间信息。
+
+```python
+from typing import TypedDict, Literal
+
+class StorageSpaceInfo(TypedDict):
+    total: float  # 总存储空间（GB，十进制）
+    free: float  # 剩余存储空间（GB，十进制）
+    unit: Literal["GB"]  # 单位，固定 GB
+
+def getStorageSpace() -> StorageSpaceInfo:
+```
+
+**返回值:**
+
+| 参数名  | 类型  | 描述                                    |
+| ------- | ----- | --------------------------------------- |
+| `total` | float | 总存储空间（单位 GB，按 10 进制计算）   |
+| `free`  | float | 剩余可用空间（单位 GB，按 10 进制计算） |
+| `unit`  | `str` | 单位，固定返回 `"GB"`                   |
+
+**示例:**
+
+```python
+from kuaijs import device
+s = device.getStorageSpace()
+print(f"总存储: {s.total}{s.unit}")
+print(f"剩余存储: {s.free}{s.unit}")
+```
+
+## 设备标识信息
+
+### getDeviceID - 获取设备唯一标识（Vendor ID）。
+
+```python
+def getDeviceID() -> str
+```
+
+**注意事项:**
+
+- 卸载重装 APP 后会改变；更新 APP 后不会改变
+
+**返回值:**
+
+| 类型  | 描述        |
+| ----- | ----------- |
+| `str` | 设备唯一 ID |
+
+**示例:**
+
+```python
+from kuaijs import device
+print(device.getDeviceID())
+```
+
+### getServerDeviceId - 获取服务器设备 ID。
+
+```python
+def getServerDeviceId() -> str
+```
+
+**注意事项:**
+
+- 卸载重装后只要签名不变，该 ID 不变；如需唯一 ID 推荐使用此方法
+
+**返回值:**
+
+| 类型  | 描述              |
+| ----- | ----------------- |
+| `str` | 服务器分配设备 ID |
+
+**示例：**
+
+```python
+from kuaijs import device
+print(device.getServerDeviceId())
+```
+
+### getECID - 获取设备 ECID。
+
+**注意事项：**
+
+- 这个 ID 只有自激活一次后才能获取
+
+```python
+def getECID() -> str
+```
+
+**返回值:**
+
+| 类型  | 描述                         |
+| ----- | ---------------------------- |
+| `str` | ECID 字符串 设备的唯一标识符 |
+
+**示例：**
+
+```python
+from kuaijs import device
+print(device.getECID())
+```
+
+### getUDID - 获取设备 UDID。
+
+**注意事项：**
+
+- 这个 ID 只有自激活一次后才能获取
+
+```python
+def getUDID() -> str
+```
+
+**返回值:**
+
+| 类型  | 描述                         |
+| ----- | ---------------------------- |
+| `str` | UDID 字符串 设备的唯一标识符 |
+
+**示例：**
+
+```python
+from kuaijs import device
+print(device.getUDID())
+```
+
+### getDeviceName - 获取设备名称。
+
+```python
+def getDeviceName() -> str
+```
+
+**返回值:**
+
+| 类型  | 描述     |
+| ----- | -------- |
+| `str` | 设备名称 |
+
+**示例:**
+
+```python
+from kuaijs import device
+print(device.getDeviceName())
+```
+
+### getDeviceModel - 获取设备型号。
+
+```python
+def getDeviceModel() -> str
+```
+
+**返回值:**
+
+| 类型  | 描述     |
+| ----- | -------- |
+| `str` | 设备型号 |
+
+**示例:**
+
+```python
+from kuaijs import device
+print(device.getDeviceModel())
+```
+
+## 屏幕信息
+
+### getScreenSize - 获取屏幕尺寸（缩放后的）。
+
+**注意事项：**
+
+- 返回尺寸为设备分辨率除以缩放比例计算结果；仅返回竖屏分辨率
+
+```python
+class ScreenSize(TypedDict):
+    width: float  # 屏幕宽度（像素）
+    height: float  # 屏幕高度（像素）
+
+def getScreenSize() -> ScreenSize:
+```
+
+**返回值:**
+
+| 参数名   | 类型  | 描述             |
+| -------- | ----- | ---------------- |
+| `width`  | float | 屏幕宽度（像素） |
+| `height` | float | 屏幕高度（像素） |
+
+**示例:**
+
+```python
+from kuaijs import device
+size = device.getScreenSize()
+print(f"屏幕尺寸: {size.width} x {size.height}")
+```
+
+### getScreenRealSize - 获取屏幕实际尺寸。
+
+**注意事项：**
+
+- 返回实际分辨率；仅返回竖屏分辨率
+
+```python
+def getScreenRealSize() -> ScreenSize:
+```
+
+**返回值:**
+
+| 参数名   | 类型  | 描述             |
+| -------- | ----- | ---------------- |
+| `width`  | float | 屏幕宽度（像素） |
+| `height` | float | 屏幕高度（像素） |
+
+**示例:**
+
+```python
+from kuaijs import device
+rs = device.getScreenRealSize()
+print(f"屏幕实际尺寸: {rs.width} x {rs.height}")
+```
+
+### getScreenScale - 获取屏幕缩放比例。
+
+```python
+def getScreenScale() -> float
+```
+
+**返回值：**
+
+| 类型    | 描述         |
+| ------- | ------------ |
+| `float` | 屏幕缩放比例 |
+
+**示例:**
+
+```python
+from kuaijs import device
+print(device.getScreenScale())
+```
+
+### getOrientation - 获取屏幕方向。
+
+**注意事项：**
+
+- 方向依赖截屏更新；若未截屏可能不准确。建议通过截屏宽高判断方向
+
+```python
+from typing import Literal
+
+def getOrientation() -> Literal["PORTRAIT","LANDSCAPE"]
+```
+
+**返回值：**
+
+| 类型     | 描述                                  |
+| -------- | ------------------------------------- |
+| `string` | `"PORTRAIT"` 竖屏；`"LANDSCAPE"` 横屏 |
+
+**示例:**
+
+```python
+from kuaijs import device
+print(device.getOrientation())
+```
+
+## 系统信息
+
+### getOSVersion - 获取操作系统版本。
+
+```python
+def getOSVersion() -> str
+```
+
+**返回值：**
+
+| 类型  | 描述                       |
+| ----- | -------------------------- |
+| `str` | 系统版本号（如 "16.7.11"） |
+
+**示例:**
+
+```python
+from kuaijs import device
+print("系统版本:", device.getOSVersion())
+```
+
+### getLanIp - 获取局域网 IP 地址。
+
+```python
+def getLanIp() -> str
+```
+
+**返回值：**
+
+| 类型  | 描述                                 |
+| ----- | ------------------------------------ |
+| `str` | 局域网 IP 地址（如 "192.168.1.100"） |
+
+**示例:**
+
+```python
+from kuaijs import device
+print("局域网IP:", device.getLanIp())
+```
+
+## 设备操作
+
+### vibrate - 控制设备振动。
+
+```python
+def vibrate(duration: int, intensity: float) -> None
+```
+
+**参数：**
+
+| 参数名      | 类型  | 是否必填 | 描述                               |
+| ----------- | ----- | -------- | ---------------------------------- |
+| `duration`  | int   | 是       | 振动持续时间，单位毫秒             |
+| `intensity` | float | 是       | 振动强度，范围 0.0-1.0（0.0 最弱） |
+
+**返回值：** 无
+
+**示例:**
+
+```python
+from kuaijs import device
+device.vibrate(500, 0.5)
+device.vibrate(200, 0.2)
+device.vibrate(300, 0.8)
+device.vibrate(100, 1.0)
+```