ms-vite-plugin 1.1.1 → 1.1.3

package/docs/api/ime.md

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

package/docs/api/logger.md

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