ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apipython/ime.md

@@ -0,0 +1,306 @@
+# 输入法模块 (IME)
+
+输入法模块提供了文本输入、剪贴板操作、键盘控制等功能，支持模拟用户的文本输入行为。
+
+## 前提条件
+
+- 在系统设置中添加 **快点 JS API 键盘**
+- 授予完全访问权限，并切换到 **快点 JS API 键盘**
+- 如果添加了键盘，切换时找不到，请重启机器再试
+- 注意键盘的方法，只有键盘弹出后才能调用
+
+## 输入法状态检查
+
+### isOk - 检查输入法键盘是否已弹出
+
+```python
+def isOk() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述                 |
+| ------ | -------------------- |
+| `bool` | 输入法键盘是否已弹出 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 检查输入法状态，只有键盘弹出后面的方法才能调用
+if ime.isOk():
+    print("输入法键盘已弹出")
+else:
+    print("输入法键盘未弹出，请检查设置")
+    # 可能需要重新初始化或检查权限
+```
+
+### autoSwitchApiKeyboard - 自动切换到 API 键盘
+
+```python
+def autoSwitchApiKeyboard() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述                                       |
+| ------ | ------------------------------------------ |
+| `bool` | 是否成功切换并连接到 API 键盘，成功为 True |
+
+- 该方法仅在系统设置中添加了快点JS API键盘 并且已授权完全访问权限时有效。
+- Agent模式下，全面屏机型支持任意输入法切换快点JS API键盘，包括系统键盘和第三方键盘。
+- Agent模式下，非全面屏机型仅支持系统键盘切换到快点JS API键盘，不支持第三方键盘切换。
+- HID模式下，所有机型都能从任意输入法切换到快点JS API键盘，包括系统键盘和第三方键盘。
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 自动切换到 API 键盘（如未弹出会尝试切换）
+if ime.autoSwitchApiKeyboard():
+    print("已切换到 API 键盘")
+else:
+    print("切换失败，请检查键盘设置和完全访问权限")
+```
+
+## 文本获取和清除
+
+### getText - 获取当前输入框的文本内容
+
+```python
+def getText() -> str
+```
+
+**返回值：**
+
+| 类型  | 描述                 |
+| ----- | -------------------- |
+| `str` | 当前输入框的文本内容 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 获取当前输入框文本
+current_text = ime.getText()
+print(f"当前文本: {current_text}")
+```
+
+### clearText - 清空当前输入框的所有文本
+
+```python
+def clearText() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 清除操作是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 清空输入框
+if ime.clearText():
+    print("文本清除成功")
+else:
+    print("文本清除失败")
+```
+
+## 文本输入
+
+### input - 模拟输入文本到当前焦点的输入框
+
+```python
+def input(text: str) -> str
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述             |
+| ------ | ---- | -------- | ------ | ---------------- |
+| `text` | str  | 是       | -      | 要输入的文本内容 |
+
+**返回值：**
+
+| 类型  | 描述                             |
+| ----- | -------------------------------- |
+| `str` | 输入后的文本内容，失败为空字符串 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 基础文本输入
+text_after = ime.input("Hello World")
+print(f"输入后文本: {text_after}")
+
+# 输入中文
+zh_text_after = ime.input("你好，世界！")
+print(f"输入后文本: {zh_text_after}")
+```
+
+### paste - 模拟粘贴操作，将剪贴板内容粘贴到当前输入框
+
+```python
+def paste(text: str | None = None) -> str
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                                             |
+| ------ | ---- | -------- | ------ | ------------------------------------------------ |
+| `text` | str  | 否       | -      | 要粘贴的内容，可选参数，如果不传则使用剪贴板内容 |
+
+**返回值：**
+
+| 类型  | 描述                             |
+| ----- | -------------------------------- |
+| `str` | 粘贴后的文本内容，失败为空字符串 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 基础粘贴操作（使用剪贴板内容）
+pasted = ime.paste()
+print(f"粘贴后文本: {pasted}")
+
+# 粘贴指定内容
+pasted_specified = ime.paste("要粘贴的文本")
+print(f"粘贴指定内容后文本: {pasted_specified}")
+```
+
+## 键盘操作
+
+### pressDel - 模拟按下删除键（退格键）
+
+```python
+def pressDel() -> str
+```
+
+**返回值：**
+
+| 类型  | 描述                                   |
+| ----- | -------------------------------------- |
+| `str` | 删除后剩余文本内容，为空表示无更多内容 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 删除一个字符
+remaining = ime.pressDel()
+print(f"删除后剩余文本: {remaining}")
+```
+
+### pressEnter - 模拟按下回车键
+
+```python
+def pressEnter() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 回车操作是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 按下回车键
+if ime.pressEnter():
+    print("回车键按下成功")
+else:
+    print("回车键按下失败")
+```
+
+### dismiss - 隐藏键盘
+
+```python
+def dismiss() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 隐藏操作是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 隐藏键盘
+if ime.dismiss():
+    print("键盘隐藏成功")
+else:
+    print("键盘隐藏失败")
+```
+
+## 剪贴板操作
+
+### getClipboard - 获取剪贴板内容
+
+```python
+def getClipboard() -> str
+```
+
+**返回值：**
+
+| 类型  | 描述               |
+| ----- | ------------------ |
+| `str` | 剪贴板中的文本内容 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 获取剪贴板内容
+clipboard_text = ime.getClipboard()
+print(f"剪贴板内容: {clipboard_text}")
+```
+
+### setClipboard - 设置剪贴板内容
+
+```python
+def setClipboard(text: str) -> bool
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                     |
+| ------ | ---- | -------- | ------ | ------------------------ |
+| `text` | str  | 是       | -      | 要设置到剪贴板的文本内容 |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 设置操作是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import ime
+
+# 设置剪贴板内容
+if ime.setClipboard("要复制的文本"):
+    print("剪贴板设置成功")
+else:
+    print("剪贴板设置失败")
+```

package/docs/apipython/logger.md

@@ -0,0 +1,330 @@
+# 日志模块 (Logger)
+
+日志模块提供了完整的日志记录功能，支持不同的日志级别、文件输出、日志管理等。
+
+- **日志级别** 开发环境默认 `debug`，打包环境默认 `info`。如需自定义日志级别，可使用 `setLoggerLevel` 方法。
+- **日志存储路径** 日志文件默认存储在我的 iPhone->应用名称的文件夹->Logger 目录中。
+- **日志文件大小** 每个日志文件最大 10MB，超过会自动创建新文件。
+- **日志文件数量** 最多保留 10 个日志文件，超过会自动删除旧文件。
+- **关闭日志输出** 可使用 `setLoggerLevel("off")` 关闭所有日志输出。
+- **关闭存储日志** 可使用 `setLogToFile(False)` 关闭将日志输出到文件的功能。
+
+## 日志级别
+
+日志模块支持以下级别（按严重程度排序）：
+
+1. **error** - 错误日志，记录程序错误和异常
+2. **warn** - 警告日志，记录潜在问题
+3. **info** - 信息日志，记录一般信息
+4. **debug** - 调试日志，记录详细的调试信息
+5. **off** - 关闭日志输出
+
+## 日志配置
+
+### setLoggerLevel - 设置日志输出级别。
+
+```python
+def setLoggerLevel(level: str) -> None
+```
+
+**参数：**
+
+| 参数名  | 类型 | 是否必填 | 默认值 | 描述                                                                                                                                                            |
+| ------- | ---- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `level` | str  | 是       |        | 日志级别 <br>`error` 只输出错误日志 <br>`warn` 输出警告和错误日志 <br>`info` 输出信息、警告和错误日志 <br>`debug` 输出所有级别的日志 <br>`off` 关闭所有日志输出 |
+
+**默认值：**
+
+- 开发环境：`"debug"`
+- 生产环境：`"info"`
+
+**示例：**
+
+```python
+from kuaijs import logger
+
+# 设置为调试级别（输出所有日志）
+logger.setLoggerLevel("debug")
+
+# 设置为信息级别（不输出调试日志）
+logger.setLoggerLevel("info")
+
+# 设置为错误级别（只输出错误日志）
+logger.setLoggerLevel("error")
+
+# 关闭所有日志
+logger.setLoggerLevel("off")
+
+# 根据环境动态设置
+isDevelopment = True # 根据实际情况判断
+logger.setLoggerLevel("debug" if isDevelopment else "info")
+```
+
+### setLogToFile - 设置是否将日志输出到文件。
+
+```python
+def setLogToFile(enabled: bool) -> None
+```
+
+**参数：**
+
+| 参数名    | 类型 | 是否必填 | 默认值 | 描述                      |
+| --------- | ---- | -------- | ------ | ------------------------- |
+| `enabled` | bool | 是       |        | 是否启用文件输出 默认开启 |
+
+**示例：**
+
+```python
+from kuaijs import logger
+
+# 启用文件日志（默认）
+logger.setLogToFile(True)
+
+# 禁用文件日志（只在控制台输出）
+logger.setLogToFile(False)
+
+# 根据配置动态设置
+enableFileLog = True # 从配置文件读取
+logger.setLogToFile(enableFileLog)
+```
+
+### setMaxLogFileCount - 设置最大日志文件数量 默认 10 个文件
+
+```python
+def setMaxLogFileCount(count: int) -> None
+```
+
+**注意事项：**
+
+- 1053 版本开始支持
+- 使用此方法请放到你的代码最前面，确保在其他日志输出之前设置。
+
+**参数：**
+
+| 参数名  | 类型 | 是否必填 | 默认值 | 描述             |
+| ------- | ---- | -------- | ------ | ---------------- |
+| `count` | int  | 是       |        | 最大日志文件数量 |
+
+**示例：**
+
+```python
+from kuaijs import logger
+
+# 设置最大日志文件数量为 5 个文件
+logger.setMaxLogFileCount(5)
+```
+
+### setMaxLogFileSize - 设置最大日志文件大小 默认 10MB
+
+```python
+def setMaxLogFileSize(size: int) -> None
+```
+
+**注意事项：**
+
+- 1053 版本开始支持
+- 使用此方法请放到你的代码最前面，确保在其他日志输出之前设置。
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                         |
+| ------ | ---- | -------- | ------ | ---------------------------- |
+| `size` | int  | 是       |        | 最大日志文件大小（单位：MB） |
+
+**示例：**
+
+```python
+from kuaijs import logger
+
+# 设置最大日志文件大小为 5MB
+logger.setMaxLogFileSize(5)
+```
+
+### resetLogFile - 重置日志文件，创建新的日志文件。
+
+```python
+def resetLogFile() -> None
+```
+
+**用途：**
+
+- 避免单个日志文件过大
+- 按时间或事件分割日志
+- 清理历史日志
+
+**示例：**
+
+```python
+from kuaijs import logger
+
+# 手动重置日志文件
+logger.resetLogFile()
+logger.info("日志文件已重置")
+
+# 重置日志文件
+def reset_log_file():
+    logger.info("开始日志轮转")
+    logger.resetLogFile()
+    logger.info("日志轮转完成")
+
+# 根据文件大小重置（需要配合文件系统检查）
+def check_and_reset_log():
+    # 这里需要配合文件模块检查日志文件大小
+    # 如果文件过大则重置
+    logger.resetLogFile()
+```
+
+## 日志输出方法
+
+### debug - 输出调试级别的日志。
+
+```python
+def debug(*args: object) -> None
+```
+
+**参数：**
+
+| 参数名 | 类型      | 是否必填 | 默认值 | 描述             |
+| ------ | --------- | -------- | ------ | ---------------- |
+| `args` | object... | 是       |        | 要输出的日志内容 |
+
+**用途：**
+
+- 详细的程序执行信息
+- 变量值和状态信息
+- 函数调用跟踪
+
+**示例：**
+
+```python
+from kuaijs import logger
+import json
+
+logger.debug("程序开始执行")
+
+# 函数调用跟踪
+def process_data(data):
+    logger.debug(f"process_data 开始，参数: {json.dumps(data)}")
+
+    # 处理逻辑...
+
+    logger.debug("process_data 完成")
+```
+
+### info - 输出信息级别的日志。
+
+```python
+def info(*args: object) -> None
+```
+
+**参数：**
+
+| 参数名 | 类型      | 是否必填 | 默认值 | 描述             |
+| ------ | --------- | -------- | ------ | ---------------- |
+| `args` | object... | 是       |        | 要输出的日志内容 |
+
+**用途：**
+
+- 程序正常运行信息
+- 重要操作的确认
+- 状态变更通知
+
+**示例：**
+
+```python
+from kuaijs import logger
+
+logger.info("应用程序启动成功")
+logger.info("用户登录成功")
+logger.info("文件下载完成")
+count = 100
+logger.info(f"处理了 {count} 条记录")
+
+# 操作确认
+def save_settings(settings):
+    # 保存设置...
+    logger.info("设置已保存")
+```
+
+### warn - 输出警告级别的日志。
+
+```python
+def warn(*args: object) -> None
+```
+
+**参数：**
+
+| 参数名 | 类型      | 是否必填 | 默认值 | 描述             |
+| ------ | --------- | -------- | ------ | ---------------- |
+| `args` | object... | 是       |        | 要输出的日志内容 |
+
+**用途：**
+
+- 潜在的问题
+- 不推荐的操作
+- 性能警告
+- 兼容性问题
+
+**示例：**
+
+```python
+from kuaijs import logger, device
+import time
+
+logger.warn("电池电量低于 20%")
+logger.warn("网络连接不稳定")
+logger.warn("使用了已废弃的 API")
+logger.warn("内存使用率较高")
+
+# 条件警告
+battery = device.getBatteryInfo()
+if battery.level < 20:
+    logger.warn(f"电池电量不足: {battery.level}%")
+
+# 性能警告
+def perform_heavy_task():
+    start_time = time.time() * 1000
+
+    # 执行耗时任务...
+
+    duration = time.time() * 1000 - start_time
+    if duration > 5000:
+        logger.warn(f"任务执行时间过长: {duration}ms")
+```
+
+### error - 输出错误级别的日志。
+
+```python
+def error(*args: object) -> None
+```
+
+**参数：**
+
+| 参数名 | 类型      | 是否必填 | 默认值 | 描述             |
+| ------ | --------- | -------- | ------ | ---------------- |
+| `args` | object... | 是       |        | 要输出的日志内容 |
+
+**用途：**
+
+- 程序错误和异常
+- 操作失败
+- 系统错误
+- 致命问题
+
+**示例：**
+
+```python
+from kuaijs import logger
+
+logger.error("网络请求失败")
+logger.error("文件读取错误")
+logger.error("数据库连接失败")
+
+# 异常处理
+try:
+    # 可能出错的操作
+    # result = risky_operation()
+    pass
+except Exception as e:
+    logger.error(f"操作失败: {str(e)}")
+```