ms-vite-plugin 1.1.1 → 1.1.3

package/docs/apicn/ime.md

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

package/docs/apicn/logger.md

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