ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/ime.md

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

package/docs/apilua/logger.md

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