ms-vite-plugin 1.4.78 → 1.4.80

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/dist/luaObfuscator/addVararg.js +1 -1
  2. package/dist/luaObfuscator/flatten.js +1 -1
  3. package/dist/luaObfuscator/rename.js +1 -1
  4. package/dist/luaObfuscator/scope.js +1 -1
  5. package/docs/api/global.md +0 -85
  6. package/docs/api/image.md +72 -111
  7. package/docs/api/ui.md +9 -39
  8. package/docs/apicn/global.md +0 -54
  9. package/docs/apicn/image.md +63 -104
  10. package/docs/apicn/ui.md +12 -40
  11. package/docs/apilua/image.md +79 -81
  12. package/docs/apilua/ui.md +12 -44
  13. package/docs/apipython/g.md +0 -81
  14. package/docs/apipython/image.md +61 -103
  15. package/docs/apipython/ui.md +6 -36
  16. package/package.json +1 -1
package/docs/apicn/image.md CHANGED
@@ -415,20 +415,20 @@ function 统计颜色数量(
415
415
 
416
416
  **参数：**
417
417
 
418
- | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
419
- | ------------- | ------ | -------- | ------ | ------------------------------------------------------------------------------------- |
420
- | `图片ID` | 字符串 | 是 | - | 图片 ID，支持 `"screen"`、图片文件路径、HTTP 图片地址或已加载的图片 ID |
418
+ | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
419
+ | ------------- | ------ | -------- | ------ | --------------------------------------------------------------------------------- |
420
+ | `图片ID` | 字符串 | 是 | - | 图片 ID，支持 `"screen"`、图片文件路径、HTTP 图片地址或已加载的图片 ID |
421
421
  | `颜色列表` | 字符串 | 是 | - | 颜色列表，支持 `主色-偏色\|主色-偏色` 格式，如 `#0A0A0A-#101010\|#FFFFFF-#101010` |
422
- | `阈值` | 数字 | 是 | - | 颜色匹配阈值 (0.0-1.0)，数值越大匹配越严格 |
423
- | `区域左上角x` | 数字 | 是 | - | 统计区域左上角坐标 |
424
- | `区域左上角y` | 数字 | 是 | - | 统计区域左上角坐标 |
425
- | `区域右下角x` | 数字 | 是 | - | 统计区域右下角坐标；传 `0` 表示延伸到图片右侧边界 |
426
- | `区域右下角y` | 数字 | 是 | - | 统计区域右下角坐标；传 `0` 表示延伸到图片底部边界 |
422
+ | `阈值` | 数字 | 是 | - | 颜色匹配阈值 (0.0-1.0)，数值越大匹配越严格 |
423
+ | `区域左上角x` | 数字 | 是 | - | 统计区域左上角坐标 |
424
+ | `区域左上角y` | 数字 | 是 | - | 统计区域左上角坐标 |
425
+ | `区域右下角x` | 数字 | 是 | - | 统计区域右下角坐标；传 `0` 表示延伸到图片右侧边界 |
426
+ | `区域右下角y` | 数字 | 是 | - | 统计区域右下角坐标；传 `0` 表示延伸到图片底部边界 |
427
427
 
428
428
  **返回值：**
429
429
 
430
- | 类型 | 描述 |
431
- | ------ | ------------------------------------------------------------------------------------ |
430
+ | 类型 | 描述 |
431
+ | ------ | ---------------------------------------------------------------------------------- |
432
432
  | `数字` | 命中目标颜色的像素数量；图片加载失败、颜色为空、颜色格式无效或区域不合法时返回 `0` |
433
433
 
434
434
  **示例：**
@@ -531,20 +531,20 @@ function 找图(
531
531
 
532
532
  **参数：**
533
533
 
534
- | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
535
- | ------------------- | ------- | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
536
- | `图片ID` | 字符串 | 是 | - | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取） |
537
- | `模板图片ID` | 字符串 | 是 | - | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
538
- | `区域左上角x` | 数字 | 是 | - | 搜索区域左上角坐标 |
539
- | `区域左上角y` | 数字 | 是 | - | 搜索区域左上角坐标 |
540
- | `区域右下角x` | 数字 | 是 | - | 搜索区域右下角坐标；传 `0` 表示延伸到图片右侧边界 |
541
- | `区域右下角y` | 数字 | 是 | - | 搜索区域右下角坐标；传 `0` 表示延伸到图片底部边界 |
542
- | `阈值` | 数字 | 是 | - | 匹配阈值 (0.0-1.0)。方法 `0`/`99` 建议 `0.5`–`0.6`；普通模板匹配（`1`/`3`/`5`）建议 `0.9`–`0.995` |
543
- | `限制数量` | 数字 | 是 | - | 最大查找数量，每个模板图片最多找 限制数量 个匹配结果 |
544
- | `方法` | 数字 | 是 | - | 匹配方法，见下方说明 |
545
- | `是否使用RGB找图` | 布尔值 | 否 | `false` | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图 |
546
- | `选项` | 对象 | 否 | - | 额外选项。`scaleFactors` 仅 方法=`99` 生效；`orz` 用于按方向取结果 |
547
- | `选项.scaleFactors` | 数字\[] | 否 | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 方法=`99` 生效。模板相对当前图的缩放比列表（**不是** `$设备.获取屏幕缩放比例()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
534
+ | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
535
+ | ------------------- | ------- | -------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
536
+ | `图片ID` | 字符串 | 是 | - | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取） |
537
+ | `模板图片ID` | 字符串 | 是 | - | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
538
+ | `区域左上角x` | 数字 | 是 | - | 搜索区域左上角坐标 |
539
+ | `区域左上角y` | 数字 | 是 | - | 搜索区域左上角坐标 |
540
+ | `区域右下角x` | 数字 | 是 | - | 搜索区域右下角坐标；传 `0` 表示延伸到图片右侧边界 |
541
+ | `区域右下角y` | 数字 | 是 | - | 搜索区域右下角坐标；传 `0` 表示延伸到图片底部边界 |
542
+ | `阈值` | 数字 | 是 | - | 匹配阈值 (0.0-1.0)。方法 `0`/`99` 建议 `0.5`–`0.6`；普通模板匹配（`1`/`3`/`5`）建议 `0.9`–`0.995` |
543
+ | `限制数量` | 数字 | 是 | - | 最大查找数量，每个模板图片最多找 限制数量 个匹配结果 |
544
+ | `方法` | 数字 | 是 | - | 匹配方法，见下方说明 |
545
+ | `是否使用RGB找图` | 布尔值 | 否 | `false` | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图 |
546
+ | `选项` | 对象 | 否 | - | 额外选项。`scaleFactors` 仅 方法=`99` 生效；`orz` 用于按方向取结果 |
547
+ | `选项.scaleFactors` | 数字\[] | 否 | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 方法=`99` 生效。模板相对当前图的缩放比列表（**不是** `$设备.获取屏幕缩放比例()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
548
548
  | `选项.orz` | 数字 | 否 | 不传 | 查找方向（1-8），与单点找色的查找方向相同。不传或非 1-8 时仍按相似度从高到低返回。传入 1-8 时按该方向取前 `限制数量` 个达标结果；`限制数量=1` 时只返回该方向第一个，不会把其余命中都找出来。方法 `0`（SIFT）会先完成匹配再按方向排序截取 |
549
549
 
550
550
  #### 方法（method）匹配说明
@@ -614,20 +614,19 @@ baseScale = 屏幕上目标高度(px) / 模板高度(px)
614
614
 
615
615
  **数值例子：**
616
616
 
617
- | 截模板设备 | 当前运行设备 | 计算 | baseScale |
618
- | -------------- | -------------- | ----------- | --------- |
619
- | iPhone 8 750px | 同机 | 750 / 750 | `1.0` |
620
- | 750 宽 | 1170 宽 | 1170 / 750 | `1.56` |
621
- | 1170 宽 | 750 宽 | 750 / 1170 | `0.641` |
622
- | 1080 宽安卓 | 1440 宽安卓 | 1440 / 1080 | `1.333` |
623
- | 模板按钮 120px | 屏上按钮 96px | 96 / 120 | `0.8` |
617
+ | 截模板设备 | 当前运行设备 | 计算 | baseScale |
618
+ | -------------- | ------------- | ---------- | --------- |
619
+ | iPhone 8 750px | 同机 | 750 / 750 | `1.0` |
620
+ | 750 宽 | 1170 宽 | 1170 / 750 | `1.56` |
621
+ | 1170 宽 | 750 宽 | 750 / 1170 | `0.641` |
622
+ | 模板按钮 120px | 屏上按钮 96px | 96 / 120 | `0.8` |
624
623
 
625
624
  含义对照：
626
625
 
627
- | baseScale | 含义 | 引擎会对模板做什么 |
628
- | --------- | -------------------------------------------- | ------------------ |
629
- | `1.0` | 当前目标与模板同尺寸 | 不缩放 |
630
- | `0.64` | 当前目标大约是模板的 64%（高分屏模板跑低分） | 缩到 64% 再匹配 |
626
+ | baseScale | 含义 | 引擎会对模板做什么 |
627
+ | --------- | --------------------------------------------- | ------------------ |
628
+ | `1.0` | 当前目标与模板同尺寸 | 不缩放 |
629
+ | `0.64` | 当前目标大约是模板的 64%（高分屏模板跑低分） | 缩到 64% 再匹配 |
631
630
  | `1.56` | 当前目标大约是模板的 156%（低分屏模板跑高分） | 放大到 156% 再匹配 |
632
631
 
633
632
  ##### 2. 再围绕 baseScale 生成搜索列表
@@ -643,14 +642,14 @@ scaleFactors ≈ [ baseScale,
643
642
 
644
643
  推荐参数：
645
644
 
646
- | 项目 | 建议 | 原因 |
647
- | -------------- | ---------------------------------- | ------------------------------------------ |
648
- | 中心值 | 算出来的 `baseScale` | 最可能命中，必须放第一位 |
649
- | 步进 `step` | `0.05`～`0.1` | 太疏容易跳过真实尺寸；太密浪费时间 |
650
- | 半宽度 | `±0.1`～`±0.2`（约 ±10%～20%） | 覆盖状态栏/安全区/轻微布局差 |
651
- | 总档数 | 3～7 个 | 每多一档就多跑一轮全图模板匹配 |
652
- | 阈值 | `0.5`～`0.6` 起调 | 缩放插值会降低相关分数，别用 0.9+ |
653
- | 顺序 | **baseScale 最先**，再左右交替扩开 | 找满限制数量会提前结束 |
645
+ | 项目 | 建议 | 原因 |
646
+ | ----------- | ---------------------------------- | ---------------------------------- |
647
+ | 中心值 | 算出来的 `baseScale` | 最可能命中，必须放第一位 |
648
+ | 步进 `step` | `0.05`～`0.1` | 太疏容易跳过真实尺寸；太密浪费时间 |
649
+ | 半宽度 | `±0.1`～`±0.2`（约 ±10%～20%） | 覆盖状态栏/安全区/轻微布局差 |
650
+ | 总档数 | 3～7 个 | 每多一档就多跑一轮全图模板匹配 |
651
+ | 阈值 | `0.5`～`0.6` 起调 | 缩放插值会降低相关分数，别用 0.9+ |
652
+ | 顺序 | **baseScale 最先**，再左右交替扩开 | 找满限制数量会提前结束 |
654
653
 
655
654
  生成示例：
656
655
 
@@ -679,14 +678,14 @@ const scaleFactors = 生成缩放比例(baseScale);
679
678
 
680
679
  ##### 3. 按场景怎么选
681
680
 
682
- | 场景 | 怎么设 `scaleFactors` | 阈值 |
683
- | -------------------------------------- | -------------------------------------------------------------- | ------------- |
684
- | 模板就是本机截的，尺寸确定一致 | 不必用 99，直接方法 `5`；若坚持用 99 则 `[1.0]` | `0.9+` / `0.55` |
685
- | 已知截图机型与当前机型分辨率 | 算 `baseScale`，再 `±0.05`～`±0.1` 扩 3～5 档 | `0.5`～`0.6` |
686
- | 多机型跑同一套模板，分辨率跨度大 | 按每台设备运行时动态算 baseScale，不要写死默认那组 | `0.5`～`0.6` |
687
- | 完全不知道模板来源分辨率 | 先用方法 `0`（SIFT）；或宽范围粗扫（慢，如 0.5～2.0 步进 0.1） | `0.5` 左右 |
688
- | 只要微调（系统字体/显示缩放导致差几像素） | `[1.0, 0.95, 1.05, 0.9, 1.1]` | `0.55`～`0.65` |
689
- | 横竖屏切换 / 目标会旋转 | 方法 `99` **不够**，改用方法 `0` SIFT | `0.5`～`0.6` |
681
+ | 场景 | 怎么设 `scaleFactors` | 阈值 |
682
+ | ----------------------------------------- | -------------------------------------------------------------- | --------------- |
683
+ | 模板就是本机截的，尺寸确定一致 | 不必用 99，直接方法 `5`；若坚持用 99 则 `[1.0]` | `0.9+` / `0.55` |
684
+ | 已知截图机型与当前机型分辨率 | 算 `baseScale`，再 `±0.05`～`±0.1` 扩 3～5 档 | `0.5`～`0.6` |
685
+ | 多机型跑同一套模板，分辨率跨度大 | 按每台设备运行时动态算 baseScale，不要写死默认那组 | `0.5`～`0.6` |
686
+ | 完全不知道模板来源分辨率 | 先用方法 `0`（SIFT）；或宽范围粗扫（慢，如 0.5～2.0 步进 0.1） | `0.5` 左右 |
687
+ | 只要微调（系统字体/显示缩放导致差几像素） | `[1.0, 0.95, 1.05, 0.9, 1.1]` | `0.55`～`0.65` |
688
+ | 横竖屏切换 / 目标会旋转 | 方法 `99` **不够**，改用方法 `0` SIFT | `0.5`～`0.6` |
690
689
 
691
690
  默认值 `[1.0, 0.9, 1.1, 0.8, 1.2]` 的定位：
692
691
 
@@ -716,20 +715,20 @@ const scaleFactors = 生成缩放比例(baseScale);
716
715
 
717
716
  ##### 5. 与方法 `0`（SIFT）怎么选
718
717
 
719
- | | 方法 `99` 缩放匹配 | 方法 `0` SIFT |
720
- | -------------- | ---------------------------------- | ---------------------------------- |
721
- | 尺寸变化 | 支持（靠你提供的比例穷举） | 支持（特征点，不靠固定比例） |
722
- | 你需要知道比例 | 最好先算 baseScale | 不需要 |
723
- | 旋转 / 形变 | 基本不支持 | 较鲁棒 |
724
- | 阈值建议 | `0.5`–`0.6` | `0.5`–`0.6` |
725
- | 透明 PNG 模板 | 支持（alpha 作权重 mask） | 支持（alpha 作特征掩码） |
726
- | 性能 | 与 factor 数量近似成正比，通常更快 | 特征提取重，通常更慢 |
727
- | 推荐 | 比例可估算的跨分辨率找图 | 比例未知、或有旋转/透视时 |
718
+ | | 方法 `99` 缩放匹配 | 方法 `0` SIFT |
719
+ | -------------- | ---------------------------------- | ---------------------------- |
720
+ | 尺寸变化 | 支持（靠你提供的比例穷举） | 支持（特征点，不靠固定比例） |
721
+ | 你需要知道比例 | 最好先算 baseScale | 不需要 |
722
+ | 旋转 / 形变 | 基本不支持 | 较鲁棒 |
723
+ | 阈值建议 | `0.5`–`0.6` | `0.5`–`0.6` |
724
+ | 透明 PNG 模板 | 支持（alpha 作权重 mask） | 支持（alpha 作特征掩码） |
725
+ | 性能 | 与 factor 数量近似成正比，通常更快 | 特征提取重，通常更慢 |
726
+ | 推荐 | 比例可估算的跨分辨率找图 | 比例未知、或有旋转/透视时 |
728
727
 
729
728
  **返回值：**
730
729
 
731
- | 类型 | 描述 |
732
- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
730
+ | 类型 | 描述 |
731
+ | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
733
732
  | `数组` | 匹配结果数组。`index` 为模板在 `模板图片ID` 中的索引（从 0 开始）。方法=`99` 时额外包含 `scaleX`、`scaleY`（本次命中使用的缩放比） |
734
733
 
735
734
  **示例：**
@@ -854,8 +853,8 @@ function 找图Ex(
854
853
 
855
854
  **返回值：**
856
855
 
857
- | 类型 | 描述 |
858
- | ------ | ------------------------------------------------------------------------------------------ |
856
+ | 类型 | 描述 |
857
+ | ------ | --------------------------------------------------------------------------------------- |
859
858
  | `数组` | 命中矩形数组，字段与 `找图` 相同。OCR 命中额外含 `text`。未找到或 kjst 无效时返回空数组 |
860
859
 
861
860
  **说明：**
@@ -1176,43 +1175,3 @@ if (图片ID) {
1176
1175
  $图片.释放图片(图片ID);
1177
1176
  }
1178
1177
  ```
1179
-
1180
- ## 安卓独有方法
1181
-
1182
- ### 获取Bitmap - 获取安卓的Bitmap对象
1183
-
1184
- 此方法仅在安卓可用，用于获取图片的 Bitmap 对象。
1185
-
1186
- ```typescript
1187
- function 获取Bitmap(图片ID: 字符串): 任意类型;
1188
- ```
1189
-
1190
- **参数：**
1191
-
1192
- | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
1193
- | -------- | ------ | -------- | ------ | --------- |
1194
- | `图片ID` | 字符串 | 是 | - | 原图片 ID |
1195
-
1196
- **返回值：**
1197
-
1198
- | 类型 | 描述 |
1199
- | ----- | ---------------- |
1200
- | `any` | 安卓的Bitmap对象 |
1201
-
1202
- **示例：**
1203
-
1204
- ```javascript
1205
- const 图片ID = $图片.截取屏幕();
1206
- if (图片ID) {
1207
- const bitmap = $图片.获取Bitmap(图片ID);
1208
- $打印信息日志(`Bitmap 对象: ${bitmap}`);
1209
- // 注意：使用完 Bitmap 后，需要调用 recycle() 方法释放内存
1210
- bitmap.recycle();
1211
- $图片.释放图片(图片ID);
1212
- }
1213
-
1214
- // 快捷获取截屏bitmap
1215
- const bitmap = $图片.获取Bitmap("screen");
1216
- logi(`Bitmap 对象: ${bitmap}`);
1217
- bitmap.recycle();
1218
- ```
package/docs/apicn/ui.md CHANGED
@@ -62,7 +62,7 @@ UI 模块提供了 WebView 相关功能，支持事件通信和 JavaScript 交
62
62
 
63
63
  ```typescript
64
64
  function 监听事件回调(
65
- 回调函数: ((事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值) | null
65
+ 回调函数: ((事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值) | null,
66
66
  ): 无返回值;
67
67
  ```
68
68
 
@@ -70,9 +70,9 @@ function 监听事件回调(
70
70
 
71
71
  **参数：**
72
72
 
73
- | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
74
- | ---------- | ---------------------------------------------------- | -------- | ------ | ------------------------------------ |
75
- | `回调函数` | ((事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值) 或 null | 是 | | 事件回调函数，用于处理来自网页的事件，传 `null` 取消监听 |
73
+ | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
74
+ | ---------- | -------------------------------------------------------------- | -------- | ------ | -------------------------------------------------------- |
75
+ | `回调函数` | ((事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值) 或 null | 是 | | 事件回调函数，用于处理来自网页的事件，传 `null` 取消监听 |
76
76
 
77
77
  **示例：**
78
78
 
@@ -243,7 +243,7 @@ $视图.显示警告对话框("操作完成", "脚本执行完成，共处理了
243
243
  ```typescript
244
244
  declare function registerUIFunc(
245
245
  name: string,
246
- func: (data: Record<string, any>) => void
246
+ func: (data: Record<string, any>) => void,
247
247
  ): void;
248
248
  ```
249
249
 
@@ -269,9 +269,8 @@ declare function registerUIFunc(
269
269
  <script>
270
270
  // 注册供主进程调用的函数
271
271
  ms.registerUIFunc("updateStatus", function (data) {
272
- document.getElementById(
273
- "status"
274
- ).textContent = `状态: ${data.status}, 进度: ${data.progress}%`;
272
+ document.getElementById("status").textContent =
273
+ `状态: ${data.status}, 进度: ${data.progress}%`;
275
274
  });
276
275
 
277
276
  ms.registerUIFunc("loadData", function (data) {
@@ -644,35 +643,6 @@ ms.getDeviceID()
644
643
  });
645
644
  ```
646
645
 
647
- #### getServerDeviceId() - 获取服务器设备 ID
648
-
649
- ```typescript
650
- declare function getServerDeviceId(): Promise<string>;
651
- ```
652
-
653
- **返回值：**
654
-
655
- | 类型 | 描述 |
656
- | ----------------- | ------------- |
657
- | `Promise<string>` | 服务器设备 ID |
658
-
659
- **说明：**
660
-
661
- 获取当前运行脚本的服务器设备 ID。
662
-
663
- **网页端示例：**
664
-
665
- ```javascript
666
- // 获取服务器设备ID
667
- ms.getServerDeviceId()
668
- .then((deviceId) => {
669
- console.log("当前服务器设备ID:", deviceId);
670
- })
671
- .catch((error) => {
672
- console.error("获取服务器设备ID出错:", error);
673
- });
674
- ```
675
-
676
646
  #### getAuthCardNo() - 获取缓存的授权卡密
677
647
 
678
648
  ```typescript
@@ -681,8 +651,8 @@ declare function getAuthCardNo(): Promise<string>;
681
651
 
682
652
  **返回值：**
683
653
 
684
- | 类型 | 描述 |
685
- | ----------------- | ------------------------------------ |
654
+ | 类型 | 描述 |
655
+ | ----------------- | -------------------------------------------------- |
686
656
  | `Promise<string>` | 有缓存的授权卡密时返回卡密字符串，否则返回空字符串 |
687
657
 
688
658
  **说明：**
@@ -781,7 +751,9 @@ ms.openURL("https://www.baidu.com")
781
751
  <div class="panel">
782
752
  <h3>快点 Agent 控制</h3>
783
753
  <p>快点 Agent 状态: <span id="agent-status">检查中...</span></p>
784
- <button class="button" onclick="startAgentService()">启动 快点 Agent</button>
754
+ <button class="button" onclick="startAgentService()">
755
+ 启动 快点 Agent
756
+ </button>
785
757
  <button class="button" onclick="checkAgentStatus()">检查状态</button>
786
758
  </div>
787
759
 
package/docs/apilua/image.md CHANGED
@@ -40,8 +40,8 @@ function captureScreen(x, y, ex, ey) end
40
40
 
41
41
  **返回值：**
42
42
 
43
- | 类型 | 描述 |
44
- | --------------- | -------------------------------- |
43
+ | 类型 | 描述 |
44
+ | --------------- | ------------------------------- |
45
45
  | `string \| nil` | 截图的图片 ID，失败时返回 `nil` |
46
46
 
47
47
  **示例：**
@@ -80,8 +80,8 @@ function readImage(path) end
80
80
 
81
81
  **返回值：**
82
82
 
83
- | 类型 | 描述 |
84
- | -------- | -------------------------- |
83
+ | 类型 | 描述 |
84
+ | -------- | ------------------------- |
85
85
  | `string` | 图片 ID，失败时返回 `nil` |
86
86
 
87
87
  **示例：**
@@ -201,8 +201,8 @@ function getSize(imageId) end
201
201
 
202
202
  **返回值：**
203
203
 
204
- | 类型 | 描述 |
205
- | ---------------- | -------------------------------------------------------------- |
204
+ | 类型 | 描述 |
205
+ | -------------- | ------------------------------------------------------------- |
206
206
  | `table \| nil` | 图片尺寸对象，包含 `width` 和 `height` 属性，失败时返回 `nil` |
207
207
 
208
208
  **示例：**
@@ -420,18 +420,18 @@ function countColor(imageId, colors, threshold, x, y, ex, ey) end
420
420
 
421
421
  **参数：**
422
422
 
423
- | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
424
- | ----------- | ------ | -------- | ------ | ------------------------------------------------------------------------------------ |
425
- | `imageId` | string | 是 | - | 图片 ID，支持 `"screen"`、图片文件路径、HTTP 图片地址或已加载的图片 ID |
423
+ | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
424
+ | ----------- | ------ | -------- | ------ | --------------------------------------------------------------------------------- |
425
+ | `imageId` | string | 是 | - | 图片 ID，支持 `"screen"`、图片文件路径、HTTP 图片地址或已加载的图片 ID |
426
426
  | `colors` | string | 是 | - | 颜色列表，支持 `主色-偏色\|主色-偏色` 格式，如 `#0A0A0A-#101010\|#FFFFFF-#101010` |
427
- | `threshold` | number | 是 | - | 颜色匹配阈值 (0.0-1.0)，数值越大匹配越严格 |
428
- | `x, y` | number | 是 | - | 统计区域左上角坐标 |
429
- | `ex, ey` | number | 是 | - | 统计区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界 |
427
+ | `threshold` | number | 是 | - | 颜色匹配阈值 (0.0-1.0)，数值越大匹配越严格 |
428
+ | `x, y` | number | 是 | - | 统计区域左上角坐标 |
429
+ | `ex, ey` | number | 是 | - | 统计区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界 |
430
430
 
431
431
  **返回值：**
432
432
 
433
- | 类型 | 描述 |
434
- | -------- | ------------------------------------------------------------------------------------ |
433
+ | 类型 | 描述 |
434
+ | -------- | ---------------------------------------------------------------------------------- |
435
435
  | `number` | 命中目标颜色的像素数量；图片加载失败、颜色为空、颜色格式无效或区域不合法时返回 `0` |
436
436
 
437
437
  **示例：**
@@ -522,29 +522,29 @@ function findImage(imageId, templateImageId, x, y, ex, ey, threshold, limit, met
522
522
 
523
523
  **参数：**
524
524
 
525
- | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
526
- | ---------------------- | --------- | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
527
- | `imageId` | string | 是 | - | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取） |
528
- | `templateImageId` | string | 是 | - | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
529
- | `x, y` | number | 是 | - | 搜索区域左上角坐标 |
530
- | `ex, ey` | number | 是 | - | 搜索区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界 |
531
- | `threshold` | number | 是 | - | 匹配阈值 (0.0-1.0)。method `0`/`99` 建议 `0.5`–`0.6`；普通模板匹配（`1`/`3`/`5`）建议 `0.9`–`0.995` |
532
- | `limit` | number | 是 | - | 最大查找数量，每个模板图片最多找 limit 个匹配结果 |
533
- | `method` | number | 否 | `5` | 匹配方法，见下方说明 |
534
- | `rgb` | boolean | 否 | `false` | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图 |
535
- | `options` | table | 否 | - | 额外选项。`scaleFactors` 仅 method=`99` 生效；`orz` 用于按方向取结果 |
536
- | `options.scaleFactors` | number\[] | 否 | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 method=`99` 生效。模板相对当前图的缩放比列表（**不是** `device.getScreenScale()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
525
+ | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
526
+ | ---------------------- | --------- | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
527
+ | `imageId` | string | 是 | - | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取） |
528
+ | `templateImageId` | string | 是 | - | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
529
+ | `x, y` | number | 是 | - | 搜索区域左上角坐标 |
530
+ | `ex, ey` | number | 是 | - | 搜索区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界 |
531
+ | `threshold` | number | 是 | - | 匹配阈值 (0.0-1.0)。method `0`/`99` 建议 `0.5`–`0.6`；普通模板匹配（`1`/`3`/`5`）建议 `0.9`–`0.995` |
532
+ | `limit` | number | 是 | - | 最大查找数量，每个模板图片最多找 limit 个匹配结果 |
533
+ | `method` | number | 否 | `5` | 匹配方法，见下方说明 |
534
+ | `rgb` | boolean | 否 | `false` | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图 |
535
+ | `options` | table | 否 | - | 额外选项。`scaleFactors` 仅 method=`99` 生效；`orz` 用于按方向取结果 |
536
+ | `options.scaleFactors` | number\[] | 否 | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 仅 method=`99` 生效。模板相对当前图的缩放比列表（**不是** `device.getScreenScale()`）。应按 baseScale 动态计算，见下方详解；默认值只适合尺寸接近时的盲扫 |
537
537
  | `options.orz` | number | 否 | 不传 | 查找方向（1-8），与找色 `orz` 相同。不传或非 1-8 时仍按相似度从高到低返回。传入 1-8 时按该方向取前 `limit` 个达标结果；`limit=1` 时只返回该方向第一个，不会把其余命中都找出来。method `0`（SIFT）会先完成匹配再按方向排序截取 |
538
538
 
539
539
  #### method 匹配方法说明
540
540
 
541
- | method | 名称 | 原理简述 | 适用场景 | 速度 |
542
- | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------- |
543
- | `5` | TM_CCOEFF_NORMED | 标准模板匹配（归一化相关系数），模板必须与目标**像素尺寸一致** | 同分辨率、同尺寸截图模板，最常用 | 快 |
544
- | `3` | TM_CCORR_NORMED | 标准模板匹配（归一化相关） | 同尺寸模板；PNG 透明模板带 mask 时内部会优先用它 | 快 |
545
- | `1` | TM_SQDIFF_NORMED | 标准模板匹配（归一化平方差），分数越小越像，引擎已换算为越大越像 | 同尺寸模板 | 快 |
546
- | `0` | SIFT 全分辨率 | 提取 SIFT 特征点做匹配，对旋转、轻微形变更鲁棒，不要求模板与目标同尺寸 | 目标可能旋转/形变，或跨分辨率找图 | 较慢 |
547
- | `99` | 全分辨率缩放匹配法 | 把**模板**按多个比例缩放后，再做 `TM_CCOEFF_NORMED` 模板匹配（有透明通道时用 `TM_CCORR_NORMED`） | 目标与模板尺寸不完全一致，但形状相同 | 中等偏慢 |
541
+ | method | 名称 | 原理简述 | 适用场景 | 速度 |
542
+ | ------ | ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------- |
543
+ | `5` | TM_CCOEFF_NORMED | 标准模板匹配（归一化相关系数），模板必须与目标**像素尺寸一致** | 同分辨率、同尺寸截图模板，最常用 | 快 |
544
+ | `3` | TM_CCORR_NORMED | 标准模板匹配（归一化相关） | 同尺寸模板；PNG 透明模板带 mask 时内部会优先用它 | 快 |
545
+ | `1` | TM_SQDIFF_NORMED | 标准模板匹配（归一化平方差），分数越小越像，引擎已换算为越大越像 | 同尺寸模板 | 快 |
546
+ | `0` | SIFT 全分辨率 | 提取 SIFT 特征点做匹配，对旋转、轻微形变更鲁棒，不要求模板与目标同尺寸 | 目标可能旋转/形变，或跨分辨率找图 | 较慢 |
547
+ | `99` | 全分辨率缩放匹配法 | 把**模板**按多个比例缩放后，再做 `TM_CCOEFF_NORMED` 模板匹配（有透明通道时用 `TM_CCORR_NORMED`） | 目标与模板尺寸不完全一致，但形状相同 | 中等偏慢 |
548
548
 
549
549
  #### 什么是「缩放」全分辨率找图（method = 99）
550
550
 
@@ -603,21 +603,20 @@ baseScale = 屏幕上目标高度(px) / 模板高度(px)
603
603
 
604
604
  **数值例子：**
605
605
 
606
- | 截模板设备 | 当前运行设备 | 计算 | baseScale |
607
- | -------------- | -------------- | ---------------------------- | --------- |
608
- | iPhone 8 750px | 同机 | 750 / 750 | `1.0` |
609
- | 750 宽 | 1170 宽 | 1170 / 750 | `1.56` |
610
- | 1170 宽 | 750 宽 | 750 / 1170 | `0.641` |
611
- | 1080 宽安卓 | 1440 宽安卓 | 1440 / 1080 | `1.333` |
612
- | 模板按钮 120px | 屏上按钮 96px | 96 / 120 | `0.8` |
606
+ | 截模板设备 | 当前运行设备 | 计算 | baseScale |
607
+ | -------------- | ------------- | ---------- | --------- |
608
+ | iPhone 8 750px | 同机 | 750 / 750 | `1.0` |
609
+ | 750 宽 | 1170 宽 | 1170 / 750 | `1.56` |
610
+ | 1170 宽 | 750 宽 | 750 / 1170 | `0.641` |
611
+ | 模板按钮 120px | 屏上按钮 96px | 96 / 120 | `0.8` |
613
612
 
614
613
  含义对照：
615
614
 
616
- | baseScale | 含义 | 引擎会对模板做什么 |
617
- | --------- | ------------------------------------------ | ----------------------- |
618
- | `1.0` | 当前目标与模板同尺寸 | 不缩放 |
619
- | `0.64` | 当前目标大约是模板的 64%（高分屏模板跑低分） | 缩到 64% 再匹配 |
620
- | `1.56` | 当前目标大约是模板的 156%（低分屏模板跑高分） | 放大到 156% 再匹配 |
615
+ | baseScale | 含义 | 引擎会对模板做什么 |
616
+ | --------- | --------------------------------------------- | ------------------ |
617
+ | `1.0` | 当前目标与模板同尺寸 | 不缩放 |
618
+ | `0.64` | 当前目标大约是模板的 64%（高分屏模板跑低分） | 缩到 64% 再匹配 |
619
+ | `1.56` | 当前目标大约是模板的 156%（低分屏模板跑高分） | 放大到 156% 再匹配 |
621
620
 
622
621
  ##### 2. 再围绕 baseScale 生成搜索列表
623
622
 
@@ -632,14 +631,14 @@ scaleFactors ≈ [ baseScale,
632
631
 
633
632
  推荐参数：
634
633
 
635
- | 项目 | 建议 | 原因 |
636
- | -------------- | ----------------------------------------- | ---- |
637
- | 中心值 | 算出来的 `baseScale` | 最可能命中，必须放第一位 |
638
- | 步进 `step` | `0.05`～`0.1` | 太疏容易跳过真实尺寸；太密浪费时间 |
639
- | 半宽度 | `±0.1`～`±0.2`（约 ±10%～20%） | 覆盖状态栏/安全区/轻微布局差 |
640
- | 总档数 | 3～7 个 | 每多一档就多跑一轮全图模板匹配 |
641
- | 阈值 threshold | `0.5`～`0.6` 起调 | 缩放插值会降低相关分数，别用 0.9+ |
642
- | 顺序 | **baseScale 最先**，再左右交替扩开 | 找满 limit 会提前结束 |
634
+ | 项目 | 建议 | 原因 |
635
+ | -------------- | ---------------------------------- | ---------------------------------- |
636
+ | 中心值 | 算出来的 `baseScale` | 最可能命中，必须放第一位 |
637
+ | 步进 `step` | `0.05`～`0.1` | 太疏容易跳过真实尺寸；太密浪费时间 |
638
+ | 半宽度 | `±0.1`～`±0.2`（约 ±10%～20%） | 覆盖状态栏/安全区/轻微布局差 |
639
+ | 总档数 | 3～7 个 | 每多一档就多跑一轮全图模板匹配 |
640
+ | 阈值 threshold | `0.5`～`0.6` 起调 | 缩放插值会降低相关分数，别用 0.9+ |
641
+ | 顺序 | **baseScale 最先**，再左右交替扩开 | 找满 limit 会提前结束 |
643
642
 
644
643
  生成示例（伪代码思路）：
645
644
 
@@ -674,14 +673,14 @@ local scaleFactors = buildScaleFactors(baseScale)
674
673
 
675
674
  ##### 3. 按场景怎么选
676
675
 
677
- | 场景 | 怎么设 `scaleFactors` | threshold |
678
- | ---- | --------------------- | --------- |
679
- | 模板就是本机截的，尺寸确定一致 | 不必用 99，直接 method `5`；若坚持用 99 则 `[1.0]` | `0.9+` / `0.55` |
680
- | 已知截图机型与当前机型分辨率 | 算 `baseScale`，再 `±0.05`～`±0.1` 扩 3～5 档 | `0.5`～`0.6` |
681
- | 多机型跑同一套模板，分辨率跨度大 | 按每台设备运行时动态算 baseScale，不要写死默认那组 | `0.5`～`0.6` |
682
- | 完全不知道模板来源分辨率 | 先用 method `0`（SIFT）；或宽范围粗扫（慢，如 0.5～2.0 步进 0.1） | `0.5` 左右 |
683
- | 只要微调（系统字体/显示缩放导致差几像素） | `[1.0, 0.95, 1.05, 0.9, 1.1]` | `0.55`～`0.65` |
684
- | 横竖屏切换 / 目标会旋转 | method `99` **不够**，改用 method `0` SIFT | `0.5`～`0.6` |
676
+ | 场景 | 怎么设 `scaleFactors` | threshold |
677
+ | ----------------------------------------- | ----------------------------------------------------------------- | --------------- |
678
+ | 模板就是本机截的，尺寸确定一致 | 不必用 99，直接 method `5`；若坚持用 99 则 `[1.0]` | `0.9+` / `0.55` |
679
+ | 已知截图机型与当前机型分辨率 | 算 `baseScale`，再 `±0.05`～`±0.1` 扩 3～5 档 | `0.5`～`0.6` |
680
+ | 多机型跑同一套模板，分辨率跨度大 | 按每台设备运行时动态算 baseScale，不要写死默认那组 | `0.5`～`0.6` |
681
+ | 完全不知道模板来源分辨率 | 先用 method `0`（SIFT）；或宽范围粗扫（慢，如 0.5～2.0 步进 0.1） | `0.5` 左右 |
682
+ | 只要微调（系统字体/显示缩放导致差几像素） | `[1.0, 0.95, 1.05, 0.9, 1.1]` | `0.55`～`0.65` |
683
+ | 横竖屏切换 / 目标会旋转 | method `99` **不够**，改用 method `0` SIFT | `0.5`～`0.6` |
685
684
 
686
685
  默认值 `[1.0, 0.9, 1.1, 0.8, 1.2]` 的定位：
687
686
 
@@ -711,15 +710,15 @@ local scaleFactors = buildScaleFactors(baseScale)
711
710
 
712
711
  ##### 5. 与 method `0`（SIFT）怎么选
713
712
 
714
- | | method `99` 缩放匹配 | method `0` SIFT |
715
- | -------------- | ---------------------------------- | ---------------------------------- |
716
- | 尺寸变化 | 支持（靠你提供的比例穷举） | 支持（特征点，不靠固定比例） |
717
- | 你需要知道比例 | 最好先算 baseScale | 不需要 |
718
- | 旋转 / 形变 | 基本不支持 | 较鲁棒 |
719
- | 阈值建议 | `0.5`–`0.6` | `0.5`–`0.6` |
720
- | 透明 PNG 模板 | 支持（alpha 作权重 mask） | 支持（alpha 作特征掩码） |
721
- | 性能 | 与 factor 数量近似成正比，通常更快 | 特征提取重，通常更慢 |
722
- | 推荐 | 比例可估算的跨分辨率找图 | 比例未知、或有旋转/透视时 |
713
+ | | method `99` 缩放匹配 | method `0` SIFT |
714
+ | -------------- | ---------------------------------- | ---------------------------- |
715
+ | 尺寸变化 | 支持（靠你提供的比例穷举） | 支持（特征点，不靠固定比例） |
716
+ | 你需要知道比例 | 最好先算 baseScale | 不需要 |
717
+ | 旋转 / 形变 | 基本不支持 | 较鲁棒 |
718
+ | 阈值建议 | `0.5`–`0.6` | `0.5`–`0.6` |
719
+ | 透明 PNG 模板 | 支持（alpha 作权重 mask） | 支持（alpha 作特征掩码） |
720
+ | 性能 | 与 factor 数量近似成正比，通常更快 | 特征提取重，通常更慢 |
721
+ | 推荐 | 比例可估算的跨分辨率找图 | 比例未知、或有旋转/透视时 |
723
722
 
724
723
  **返回值：**
725
724
 
@@ -834,15 +833,15 @@ function findImageEx(id, kjstPath) end
834
833
 
835
834
  **参数：**
836
835
 
837
- | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
838
- | ----------- | ------ | -------- | ------ | -------------------------------------------------------------------------------------------- |
839
- | `id` | string | 是 | - | `"screen"`-当前屏幕截图，或图片 ID / 路径，语义与 `findImage` 相同 |
840
- | `kjstPath` | string | 是 | - | `res` 下的 kjst 文件名，例如 `"login.kjst"`。不要带 `res/` 前缀，也不要传手机绝对路径 |
836
+ | 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
837
+ | ---------- | ------ | -------- | ------ | ------------------------------------------------------------------------------------- |
838
+ | `id` | string | 是 | - | `"screen"`-当前屏幕截图，或图片 ID / 路径，语义与 `findImage` 相同 |
839
+ | `kjstPath` | string | 是 | - | `res` 下的 kjst 文件名，例如 `"login.kjst"`。不要带 `res/` 前缀，也不要传手机绝对路径 |
841
840
 
842
841
  **返回值：**
843
842
 
844
- | 类型 | 描述 |
845
- | ------ | --------------------------------------------------------------------------------------------- |
843
+ | 类型 | 描述 |
844
+ | ------- | --------------------------------------------------------------------------------------------------------- |
846
845
  | `table` | 命中矩形数组，字段与 `findImage` 相同。OCR 命中额外含 `text`。未找到或 kjst 无效时返回空表。下标从 1 开始 |
847
846
 
848
847
  **说明：**
@@ -933,8 +932,8 @@ function rotateImage(imageId, degree) end
933
932
 
934
933
  **返回值：**
935
934
 
936
- | 类型 | 描述 |
937
- | ---------------- | ----------------------------------- |
935
+ | 类型 | 描述 |
936
+ | --------------- | ---------------------------------- |
938
937
  | `string \| nil` | 旋转后的新图片 ID 失败时返回 `nil` |
939
938
 
940
939
  **示例：**
@@ -1076,8 +1075,8 @@ function scanCode(imageId) end
1076
1075
 
1077
1076
  **返回值：**
1078
1077
 
1079
- | 类型 | 描述 |
1080
- | ---------------- | --------------------------- |
1078
+ | 类型 | 描述 |
1079
+ | --------------- | -------------------------- |
1081
1080
  | `string \| nil` | 扫码结果，失败时返回 `nil` |
1082
1081
 
1083
1082
  **示例：**
@@ -1165,4 +1164,3 @@ if imageId then
1165
1164
  image.release(imageId)
1166
1165
  end
1167
1166
  ```
1168
-