ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/device.md

@@ -0,0 +1,485 @@
+# 设备模块 (Device)
+
+设备模块提供了获取设备信息和设备操作的功能，包括电池信息、设备标识、屏幕信息、系统信息等。
+
+## 电池信息
+
+### getBatteryInfo - 获取设备的电池信息。
+
+```lua
+---@return any
+function getBatteryInfo() end
+```
+
+**返回值：**
+
+| 参数名       | 类型    | 描述                    |
+| ------------ | ------- | ----------------------- |
+| `level`      | number  | 电池电量百分比（0-100） |
+| `isCharging` | boolean | 是否正在充电            |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取电池信息
+local battery = device.getBatteryInfo()
+print("电池电量: " .. tostring(battery.level) .. "%")
+print("充电状态: " .. tostring(battery.(isCharging) and "充电中" or "未充电"))
+```
+
+## 存储空间信息
+
+### getStorageSpace - 获取设备存储空间信息。
+
+```lua
+---@return any
+function getStorageSpace() end
+```
+
+**返回值：**
+
+| 参数名  | 类型   | 描述                                    |
+| ------- | ------ | --------------------------------------- |
+| `total` | number | 总存储空间（单位 GB，按 10 进制计算）   |
+| `free`  | number | 剩余可用空间（单位 GB，按 10 进制计算） |
+| `unit`  | string | 单位，固定返回 `"GB"`                   |
+
+**示例：**
+
+```lua
+local device = require("device")
+local storage = device.getStorageSpace()
+print("总存储: " .. tostring(storage.total) .. tostring(storage.unit))
+print("剩余存储: " .. tostring(storage.free) .. tostring(storage.unit))
+```
+
+## 设备标识信息
+
+### getDeviceID - 获取设备的唯一标识符（ID）。
+
+**注意事项：**
+
+- 这个 ID 卸载重装 APP 后会改变。
+- 更新 APP 后，不会改变。
+
+```lua
+---@return string
+function getDeviceID() end
+```
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| string | 设备的唯一标识符 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取设备ID
+local uuid = device.getDeviceID()
+print("设备ID = " .. tostring(uuid))
+```
+
+### getServerDeviceId - 获取服务器设备 ID。
+
+**注意事项：**
+
+- 这个 ID 卸载重装后，只要签名没变，就不会改变。
+- 如果要取唯一 ID 建议使用这个。
+
+```lua
+---@return string
+function getServerDeviceId() end
+```
+
+**返回值：**
+
+| 类型     | 描述                |
+| -------- | ------------------- |
+| `string` | 服务器分配的设备 ID |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取服务器设备ID
+local serverDeviceId = device.getServerDeviceId()
+print("服务器设备ID = " .. tostring(serverDeviceId))
+```
+
+### getECID - 获取设备 ECID。
+
+```lua
+---@return string
+function getECID() end
+```
+
+**返回值：**
+
+| 类型     | 描述                         |
+| -------- | ---------------------------- |
+| `string` | ECID 字符串 设备的唯一标识符 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取ECID
+local ecid = device.getECID()
+print("ECID = " .. tostring(ecid))
+```
+
+### getUDID - 获取设备 UDID。
+
+```lua
+---@return string
+function getUDID() end
+```
+
+**返回值：**
+
+| 类型     | 描述                         |
+| -------- | ---------------------------- |
+| `string` | UDID 字符串 设备的唯一标识符 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取UDID
+local udid = device.getUDID()
+print("UDID = " .. tostring(udid))
+```
+
+### getDeviceName - 获取设备名称。
+
+```lua
+---@return string
+function getDeviceName() end
+```
+
+**返回值：**
+
+| 类型     | 描述     |
+| -------- | -------- |
+| `string` | 设备名称 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取设备名称
+local deviceName = device.getDeviceName()
+print("设备名称: " .. tostring(deviceName))
+```
+
+### getDeviceModel - 获取设备型号。
+
+```lua
+---@return string
+function getDeviceModel() end
+```
+
+**返回值：**
+
+| 类型     | 描述     |
+| -------- | -------- |
+| `string` | 设备型号 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取设备型号
+local model = device.getDeviceModel()
+print("设备型号: " .. tostring(model))
+```
+
+## 屏幕信息
+
+### getScreenSize - 获取屏幕尺寸（缩放后的）。
+
+**注意事项：**
+
+- 该方法返回的屏幕尺寸是根据当前设备的屏幕分辨率除以缩放比例计算得到的。
+- 注意该方法只会返回竖屏分辨率。
+
+```lua
+---@return any
+function getScreenSize() end
+```
+
+**返回值：**
+
+| 参数名   | 类型   | 描述             |
+| -------- | ------ | ---------------- |
+| `width`  | number | 屏幕宽度（像素） |
+| `height` | number | 屏幕高度（像素） |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取屏幕尺寸
+local screenSize = device.getScreenSize()
+print("屏幕尺寸: " .. tostring(screenSize.width) .. " x " .. tostring(screenSize.height))
+```
+
+### getScreenRealSize - 获取屏幕实际尺寸。
+
+**注意事项：**
+
+- 该方法返回的屏幕尺寸是根据当前设备的屏幕实际分辨率。
+- 注意该方法只会返回竖屏分辨率。
+
+```lua
+---@return any
+function getScreenRealSize() end
+```
+
+**返回值：**
+
+| 参数名   | 类型   | 描述             |
+| -------- | ------ | ---------------- |
+| `width`  | number | 屏幕宽度（像素） |
+| `height` | number | 屏幕高度（像素） |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取屏幕实际尺寸
+local screenRealSize = device.getScreenRealSize()
+print("屏幕实际尺寸: " .. tostring(screenRealSize.width) .. " x " .. tostring(screenRealSize.height))
+```
+
+### getScreenScale - 获取屏幕缩放比例。
+
+```lua
+---@return number
+function getScreenScale() end
+```
+
+**返回值：**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `number` | 屏幕缩放比例 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取屏幕缩放比例
+local scale = device.getScreenScale()
+print("屏幕缩放比例: " .. tostring(scale))
+```
+
+### getScreenBrightness - 获取屏幕亮度。
+
+```lua
+---@return number
+function getScreenBrightness() end
+```
+
+**返回值：**
+
+| 类型     | 描述                     |
+| -------- | ------------------------ |
+| `number` | 屏幕亮度，范围 `0.0-1.0` |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取屏幕亮度
+local brightness = device.getScreenBrightness()
+print("屏幕亮度: " .. tostring(brightness))
+```
+
+### setScreenBrightness - 设置屏幕亮度。
+
+设置设备屏幕亮度，亮度范围为 `0.0-1.0`。
+
+```lua
+---@param brightness number
+---@return boolean
+function setScreenBrightness(brightness) end
+```
+
+**参数说明：**
+
+| 参数名       | 类型     | 是否必填 | 默认值 | 描述                         |
+| ------------ | -------- | -------- | ------ | ---------------------------- |
+| `brightness` | `number` | 是       | -      | 目标屏幕亮度，范围 `0.0-1.0` |
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否设置成功 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 设置屏幕亮度到 50%
+device.setScreenBrightness(0.5)
+```
+
+### getVolume - 获取系统音量。
+
+```lua
+---@return number
+function getVolume() end
+```
+
+**返回值：**
+
+| 类型     | 描述                     |
+| -------- | ------------------------ |
+| `number` | 系统音量，范围 `0.0-1.0` |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取系统音量
+local volume = device.getVolume()
+print("系统音量: " .. tostring(volume))
+```
+
+### setVolume - 设置系统音量。
+
+设置系统音量，音量范围为 `0.0-1.0`。
+
+```lua
+---@param volume number
+---@return boolean
+function setVolume(volume) end
+```
+
+**参数说明：**
+
+| 参数名   | 类型     | 是否必填 | 默认值 | 描述                         |
+| -------- | -------- | -------- | ------ | ---------------------------- |
+| `volume` | `number` | 是       | -      | 目标系统音量，范围 `0.0-1.0` |
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否设置成功 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 设置系统音量到 50%
+device.setVolume(0.5)
+```
+
+### getOrientation - 获取屏幕方向。
+
+**注意事项**
+
+- 该方法返回的方向，是靠截屏方法来更新的，如果没有截屏，该方法返回的方向可能是不准确的。
+- 该方法取到的方向可能不准，建议使用截屏，靠截屏的图片宽高来确定方向
+
+```lua
+---@return string
+function getOrientation() end
+```
+
+**返回值：**
+
+| 类型     | 描述                                                    |
+| -------- | ------------------------------------------------------- |
+| `string` | 设备方向，`"PORTRAIT"` 竖屏模式，`"LANDSCAPE"` 横屏模式 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取屏幕方向
+local orientation = device.getOrientation()
+print("屏幕方向: " .. tostring(orientation))
+```
+
+## 系统信息
+
+### getOSVersion - 获取操作系统版本。
+
+```lua
+---@return string
+function getOSVersion() end
+```
+
+**返回值：**
+
+| 类型     | 描述                       |
+| -------- | -------------------------- |
+| `string` | 系统版本号（如 "16.7.11"） |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取系统版本
+local osVersion = device.getOSVersion()
+print("系统版本: iOS " .. tostring(osVersion))
+```
+
+### getLanIp - 获取设备的局域网 IP 地址。
+
+```lua
+---@return string
+function getLanIp() end
+```
+
+**返回值：**
+
+| 类型     | 描述                                 |
+| -------- | ------------------------------------ |
+| `string` | 局域网 IP 地址（如 "192.168.1.100"） |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 获取局域网IP
+local lanIp = device.getLanIp()
+print("局域网IP = " .. tostring(lanIp))
+```
+
+## 设备操作
+
+### vibrate - 控制设备振动。
+
+```lua
+---@param duration number
+---@param intensity number
+function vibrate(duration, intensity) end
+```
+
+**参数说明：**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述                                           |
+| ----------- | ------ | -------- | ------ | ---------------------------------------------- |
+| `duration`  | number | 是       | -      | 振动持续时间，单位毫秒                         |
+| `intensity` | number | 是       | -      | 振动强度，范围 0.0-1.0，0.0 为最弱，1.0 为最强 |
+
+**示例：**
+
+```lua
+local device = require("device")
+-- 基础振动
+device.vibrate(500, 0.5); -- 振动500ms，中等强度
+-- 不同强度的振动
+device.vibrate(200, 0.2); -- 轻微振动
+device.vibrate(300, 0.8); -- 强烈振动
+device.vibrate(100, 1.0); -- 最强振动
+```

package/docs/apilua/dotocr.md

@@ -0,0 +1,230 @@
+# 点阵 OCR 模块 (dotOcr)
+
+点阵 OCR 模块基于图色工具生成的固定像素点阵字库，提供精确的文字识别与查找功能。字库保存在项目的 `res/fonts` 目录，使用前需先加载字库取得字库 ID，再复用该 ID 进行识别，使用完毕后释放。
+
+点阵模板按照制作时的原始像素尺寸匹配，不会自动缩放到其他分辨率。目标文字的字号、缩放比例或像素形状发生变化时，应制作对应的字库特征。
+
+## 功能概览
+
+- **字库管理**: 加载、缓存和释放项目字库
+- **文字识别**: 返回按阅读顺序排列的识别结果数组
+- **文本查找**: 先识别再按行定位目标串，返回命中位置的绝对坐标
+- **多源输入**: 支持屏幕截图、图片文件、URL 或 imageId
+- **区域识别**: 支持指定区域的精确文字识别
+- **绝对坐标**: 裁剪区域内的结果会映射回原图或全屏坐标
+- **资源控制**: 完整的字库生命周期管理
+
+## 数据类型
+
+### OCRChar
+
+识别结果的数据结构，包含完整的文本信息和位置数据：
+
+```lua
+---@class OCRChar
+---@field text string
+---@field confidence number
+---@field x number
+---@field y number
+---@field ex number
+---@field ey number
+---@field width number
+---@field height number
+---@field centerX number
+---@field centerY number
+```
+
+**数据结构说明：**
+
+| 字段               | 类型   | 描述                                                     |
+| ------------------ | ------ | -------------------------------------------------------- |
+| `text`             | string | 识别出的文本内容；查找结果中为命中的目标字符串           |
+| `confidence`       | number | 识别置信度，范围 0-1，值越高表示识别越准确               |
+| `x, y, ex, ey`     | number | 文本区域的坐标，分别为左上角和右下角的 x、y 绝对坐标     |
+| `width, height`    | number | 文本区域的宽度和高度                                     |
+| `centerX, centerY` | number | 文本区域的中心点绝对坐标                                 |
+
+## API 参考
+
+### 字库管理
+
+#### loadFont - 加载并缓存点阵字库。
+
+加载字库是使用点阵识别功能的前提。建议在脚本初始化时加载一次并保存 `fontId`，后续识别时复用，不要每次识别都重新加载。
+
+```lua
+---@param fontPath string
+---@return string | nil
+function loadFont(fontPath) end
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                                                        |
+| ---------- | ------ | -------- | ------ | --------------------------------------------------------------------------- |
+| `fontPath` | string | 是       |        | 资源路径，运行时会自动处理 `res` 目录解析；常见写法如 `/fonts/default.json` |
+
+**返回值:**
+
+| 类型             | 描述                                      |
+| ---------------- | ----------------------------------------- |
+| `string \| nil` | 加载成功返回字库 ID 字符串，失败返回 nil |
+
+**示例:**
+
+```lua
+local dotocr = require("dotocr")
+local fontId = dotocr.loadFont("/fonts/default.json")
+if not fontId then
+  print("字库加载失败")
+  return
+end
+print("字库加载成功: " .. tostring(fontId))
+```
+
+### 文字识别
+
+#### recognizeAbs - 执行点阵 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+传入裁剪区域时，返回坐标会映射回原图或全屏坐标，可直接用于点击。结果按行从上到下、同一行从左到右排列。颜色按字库各字自带的前景色/偏色匹配，无需额外传色。
+
+```lua
+---@param fontId string
+---@param input string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param confidenceThreshold number?
+---@return OCRChar[]
+function recognizeAbs(fontId, input, x, y, ex, ey, confidenceThreshold) end
+```
+
+**参数:**
+
+| 参数名                | 类型   | 是否必填 | 默认值 | 描述                                                                                          |
+| --------------------- | ------ | -------- | ------ | --------------------------------------------------------------------------------------------- |
+| `fontId`              | string | 是       |        | 字库 ID，通过 `loadFont` 获取                                                                 |
+| `input`               | string | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                                         |
+| `x`                   | number | 否       | 0      | 裁剪区域左上角 x 坐标；全屏识别传 0                                                           |
+| `y`                   | number | 否       | 0      | 裁剪区域左上角 y 坐标；全屏识别传 0                                                           |
+| `ex`                  | number | 否       | 0      | 裁剪区域右下角 x 坐标；全屏识别传 0；为 0 时使用图像宽度                                      |
+| `ey`                  | number | 否       | 0      | 裁剪区域右下角 y 坐标；全屏识别传 0；为 0 时使用图像高度                                      |
+| `confidenceThreshold` | number | 否       | 0.95   | 相似度下限；`<=0` 时按 `0.95`；低于阈值的字符会被过滤；`>0.95` 时要求像素完全一致             |
+
+**返回值:**
+
+| 类型        | 描述                                           |
+| ----------- | ---------------------------------------------- |
+| `OCRChar[]` | 识别结果数组，坐标为原图或全屏绝对坐标         |
+
+**示例:**
+
+```lua
+local dotocr = require("dotocr")
+local chars = dotocr.recognizeAbs(fontId, "screen", 100, 200, 600, 280, 0.95)
+print("识别数量: " .. tostring(#chars))
+if #chars > 0 then
+  print("文本: " .. tostring(chars[1].text) .. ", 坐标: (" .. tostring(chars[1].x) .. ", " .. tostring(chars[1].y) .. ")")
+  action.click(chars[1].centerX, chars[1].centerY)
+end
+```
+
+### 文本查找
+
+#### findTextAbs - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标。
+
+先识别再按行定位目标串。传入裁剪区域时，返回坐标会映射回原图或全屏坐标，可直接用于点击。每个目标最多返回一次命中（最先匹配到的行），每项的 `text` 是目标字符串。
+
+```lua
+---@param fontId string
+---@param input string
+---@param targetTexts string[]
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param confidenceThreshold number?
+---@param exactMatch boolean?
+---@return OCRChar[]
+function findTextAbs(fontId, input, targetTexts, x, y, ex, ey, confidenceThreshold, exactMatch) end
+```
+
+**参数:**
+
+| 参数名                | 类型     | 是否必填 | 默认值 | 描述                                                                  |
+| --------------------- | -------- | -------- | ------ | --------------------------------------------------------------------- |
+| `fontId`              | string   | 是       |        | 字库 ID，通过 `loadFont` 获取                                         |
+| `input`               | string   | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                 |
+| `targetTexts`         | string[] | 是       |        | 要查找的字符串数组，例如 `["商店", "背包"]`                           |
+| `x`                   | number   | 否       | 0      | 裁剪区域左上角 x 坐标；全屏识别传 0                                   |
+| `y`                   | number   | 否       | 0      | 裁剪区域左上角 y 坐标；全屏识别传 0                                   |
+| `ex`                  | number   | 否       | 0      | 裁剪区域右下角 x 坐标；全屏识别传 0；为 0 时使用图像宽度              |
+| `ey`                  | number   | 否       | 0      | 裁剪区域右下角 y 坐标；全屏识别传 0；为 0 时使用图像高度              |
+| `confidenceThreshold` | number   | 否       | 0.95   | 单字符识别相似度下限；语义同 `recognizeAbs`                           |
+| `exactMatch`          | boolean  | 否       | false  | `false` 为行内子串包含匹配；`true` 要求某一整行文本完全等于目标字符串 |
+
+**返回值:**
+
+| 类型        | 描述                                                   |
+| ----------- | ------------------------------------------------------ |
+| `OCRChar[]` | 命中结果数组，坐标为原图或全屏绝对坐标                 |
+
+**示例:**
+
+```lua
+local dotocr = require("dotocr")
+local hits = dotocr.findTextAbs(
+  fontId,
+  "screen",
+  { "商店", "背包" },
+  100,
+  200,
+  600,
+  280,
+  0.95,
+  false,
+)
+if #hits > 0 then
+  action.click(hits[1].centerX, hits[1].centerY)
+end
+```
+
+### 资源管理
+
+#### free - 释放指定字库的资源。
+
+```lua
+---@param fontId string
+function free(fontId) end
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述            |
+| -------- | ------ | -------- | ------ | --------------- |
+| `fontId` | string | 是       |        | 要释放的字库 ID |
+
+**示例:**
+
+```lua
+local dotocr = require("dotocr")
+if fontId then
+  dotocr.free(fontId)
+  print("字库 " .. tostring(fontId) .. " 资源已释放")
+end
+```
+
+#### freeAll - 释放全部已加载点阵字库的资源。
+
+```lua
+function freeAll() end
+```
+
+**示例:**
+
+```lua
+local dotocr = require("dotocr")
+dotocr.freeAll()
+print("所有点阵字库资源已释放")
+```