ms-vite-plugin 1.1.1 → 1.1.3

package/docs/apicn/image.md

@@ -0,0 +1,924 @@
+# 图片模块 ($图片)
+
+图片模块提供了强大的图像处理功能，包括截图、图像识别、模板匹配、颜色查找、图像变换等。
+
+注意所有的 `图片ID` 都需要在使用后释放，否则会导致内存泄漏。
+
+所有传递`图片ID`的函数都可以使用`"screen"`作为参数，来表示对当前屏幕进行操作。
+
+`"screen"` 在设置为`Agent`模式，使用`快点Agent`截图，录屏模式使用录屏截图。
+
+所有传递`图片ID`的函数都可以使用`"shortcut"`作为参数，来表示指定 HID 快捷指令截图
+
+所有传递`图片ID`的函数都可以使用`"actionScreenshot"`作为参数，来表示指定 HID 快捷键系统截图
+
+所有传递`图片ID`的函数都可以使用图片路径作为参数，来表示对指定图片进行操作，支持 res 目录文件，和手机文件路径。
+
+## 图片获取与管理
+
+### 截取屏幕
+
+```typescript
+function 截取屏幕(
+  区域左上角X坐标?: 数字,
+  区域左上角Y坐标?: 数字,
+  区域右下角X坐标?: 数字,
+  区域右下角Y坐标?: 数字,
+): 字符串 | null;
+```
+
+**参数：**
+
+| 参数名            | 类型 | 是否必填 | 默认值 | 描述              |
+| ----------------- | ---- | -------- | ------ | ----------------- |
+| `区域左上角X坐标` | 数字 | 否       | 0      | 区域左上角 X 坐标 |
+| `区域左上角Y坐标` | 数字 | 否       | 0      | 区域左上角 Y 坐标 |
+| `区域右下角X坐标` | 数字 | 否       | 0      | 区域右下角 X 坐标 |
+| `区域右下角Y坐标` | 数字 | 否       | 0      | 区域右下角 Y 坐标 |
+
+**返回值：**
+
+| 类型     | 描述                             |
+| -------- | -------------------------------- |
+| `字符串` | 截图的图片 ID，失败时返回 `null` |
+
+**示例：**
+
+```javascript
+// 截取全屏
+const 图片ID = $图片.截取屏幕();
+// 获取手机文档目录
+const 文档目录 = $文件.获取内部目录("documents");
+if (图片ID) {
+  $打印信息日志("截图成功");
+  $图片.保存图片(图片ID, `${文档目录}/screenshot.jpg`);
+  $图片.释放图片(图片ID); // 记得释放内存
+} else {
+  $打印错误日志("截图失败");
+}
+
+// 截取指定区域
+const 图片ID = $图片.截取屏幕(100, 100, 200, 200);
+// 获取手机文档目录
+const 文档目录 = $文件.获取内部目录("documents");
+if (图片ID) {
+  $打印信息日志("截图成功");
+  $图片.保存图片(图片ID, `${文档目录}/screenshot.jpg`);
+  $图片.释放图片(图片ID); // 记得释放内存
+} else {
+  $打印错误日志("截图失败");
+}
+```
+
+### 截取全屏 - 截取设备全屏。
+
+```typescript
+function 截取全屏(): 字符串 | null;
+```
+
+**返回值：**
+
+| 类型     | 描述                             |
+| -------- | -------------------------------- |
+| `字符串` | 截图的图片 ID，失败时返回 `null` |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+// 获取手机文档目录
+const 文档目录 = $文件.获取内部目录("documents");
+if (图片ID) {
+  $打印信息日志("截图成功");
+  $图片.保存图片(图片ID, `${文档目录}/screenshot.jpg`);
+  $图片.释放图片(图片ID); // 记得释放内存
+} else {
+  $打印错误日志("截图失败");
+}
+```
+
+### 截取区域 - 截取设备指定区域。
+
+```typescript
+function 截取区域(
+  区域左上角X坐标: 数字,
+  区域左上角Y坐标: 数字,
+  区域右下角X坐标: 数字,
+  区域右下角Y坐标: 数字,
+): 字符串 | null;
+```
+
+**参数：**
+
+| 参数名            | 类型 | 是否必填 | 默认值 | 描述              |
+| ----------------- | ---- | -------- | ------ | ----------------- |
+| `区域左上角X坐标` | 数字 | 是       | -      | 区域左上角 X 坐标 |
+| `区域左上角Y坐标` | 数字 | 是       | -      | 区域左上角 Y 坐标 |
+| `区域右下角X坐标` | 数字 | 是       | -      | 区域右下角 X 坐标 |
+| `区域右下角Y坐标` | 数字 | 是       | -      | 区域右下角 Y 坐标 |
+
+**返回值：**
+
+| 类型     | 描述                             |
+| -------- | -------------------------------- |
+| `字符串` | 截图的图片 ID，失败时返回 `null` |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取区域(100, 100, 200, 200);
+if (图片ID) {
+  $打印信息日志("截图成功");
+  // 使用图片...
+  $图片.释放图片(图片ID);
+} else {
+  $打印错误日志("截图失败");
+}
+```
+
+### 读取图片 - 从文件路径或图片ID读取图片。
+
+```typescript
+function 读取图片(图片路径: 字符串): 字符串 | null;
+```
+
+**参数：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                                                   |
+| ---------- | ------ | -------- | ------ | ---------------------------------------------------------------------- |
+| `图片路径` | 字符串 | 是       | -      | 图片文件路径 支持 res 目录文件和手机文件绝对路径，支持特殊标识的图片ID |
+
+**返回值：**
+
+| 类型     | 描述                       |
+| -------- | -------------------------- |
+| `字符串` | 图片 ID，失败时返回 `null` |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.读取图片("template.jpg");
+if (图片ID) {
+  $打印信息日志("图片读取成功");
+  // 使用图片...
+  $图片.释放图片(图片ID);
+} else {
+  $打印错误日志("图片读取失败");
+}
+```
+
+### 保存图片 - 保存图片到指定路径。
+
+```typescript
+function 保存图片(图片ID: 字符串, 保存路径: 字符串): 布尔值;
+```
+
+**参数：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述     |
+| ---------- | ------ | -------- | ------ | -------- |
+| `图片ID`   | 字符串 | 是       | -      | 图片 ID  |
+| `保存路径` | 字符串 | 是       | -      | 保存路径 |
+
+**返回值：**
+
+| 类型     | 描述                                  |
+| -------- | ------------------------------------- |
+| `布尔值` | `true` 表示保存成功，`false` 表示失败 |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+// 获取手机文档目录
+const 文档目录 = $文件.获取内部目录("documents");
+if (图片ID) {
+  $图片.保存图片(图片ID, `${文档目录}/screenshot.jpg`);
+  $图片.释放图片(图片ID);
+}
+```
+
+## 内存管理
+
+### 释放图片 - 释放单个图片的内存。
+
+```typescript
+function 释放图片(图片ID: 字符串): 无返回值;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述            |
+| -------- | ------ | -------- | ------ | --------------- |
+| `图片ID` | 字符串 | 是       | -      | 要释放的图片 ID |
+
+### 释放所有图片 - 释放所有图片的内存。
+
+```typescript
+function 释放所有图片(): 无返回值;
+```
+
+### 图片是否被释放 - 检查图片是否已被释放。
+
+```typescript
+function 图片是否被释放(图片ID: 字符串): 布尔值;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述    |
+| -------- | ------ | -------- | ------ | ------- |
+| `图片ID` | 字符串 | 是       | -      | 图片 ID |
+
+**返回值：**
+
+| 类型     | 描述                                  |
+| -------- | ------------------------------------- |
+| `布尔值` | `true` 表示已释放，`false` 表示未释放 |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  $打印信息日志(`释放前: ${$图片.图片是否被释放(图片ID)}`); // false
+  $图片.释放图片(图片ID);
+  $打印信息日志(`释放后: ${$图片.图片是否被释放(图片ID)}`); // true
+}
+```
+
+## 图片信息
+
+### 获取图片大小 - 获取图片尺寸。
+
+```typescript
+function 获取图片大小(图片ID: 字符串): { width: 数字; height: 数字 } | null;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述    |
+| -------- | ------ | -------- | ------ | ------- |
+| `图片ID` | 字符串 | 是       | -      | 图片 ID |
+
+**返回值：**
+
+| 类型                                    | 描述                                                           |
+| --------------------------------------- | -------------------------------------------------------------- |
+| `{ width: 数字; height: 数字 } \| null` | 图片尺寸对象，包含 `width` 和 `height` 属性，失败时返回 `null` |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  const 图片尺寸 = $图片.获取图片大小(图片ID);
+  if (图片尺寸) {
+    $打印信息日志(`图片尺寸: ${图片尺寸.width} x ${图片尺寸.height}`);
+  }
+  $图片.释放图片(图片ID);
+}
+```
+
+### 取像素颜色 - 获取图片指定坐标的像素颜色值。
+
+```typescript
+function 取像素颜色(图片ID: 字符串, 坐标x: 数字, 坐标y: 数字): 数字;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述    |
+| -------- | ------ | -------- | ------ | ------- |
+| `图片ID` | 字符串 | 是       | -      | 图片 ID |
+| `坐标x`  | 数字   | 是       | -      | X 坐标  |
+| `坐标y`  | 数字   | 是       | -      | Y 坐标  |
+
+**返回值：**
+
+| 类型   | 描述           |
+| ------ | -------------- |
+| `数字` | 颜色值（整型） |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  const 颜色值 = $图片.取像素颜色(图片ID, 100, 100);
+  const 颜色Hex = $图片.颜色转16进制字符串(颜色值);
+  $打印信息日志(`坐标 (100, 100) 的颜色: ${颜色Hex}`);
+  $图片.释放图片(图片ID);
+}
+```
+
+### 颜色转 16 进制字符串 - 将整型颜色值转换为 16 进制 RGB 字符串。
+
+```typescript
+function 颜色转16进制字符串(颜色值: 数字): 字符串;
+```
+
+**参数：**
+
+| 参数名   | 类型 | 是否必填 | 默认值 | 描述       |
+| -------- | ---- | -------- | ------ | ---------- |
+| `颜色值` | 数字 | 是       | -      | 整型颜色值 |
+
+**返回值：**
+
+| 类型     | 描述               |
+| -------- | ------------------ |
+| `字符串` | 16 进制 RGB 字符串 |
+
+## 颜色识别
+
+### 单点找色
+
+```typescript
+function 单点找色(
+  图片ID: 字符串,
+  颜色: 字符串,
+  阈值: 数字,
+  区域左上角x: 数字,
+  区域左上角y: 数字,
+  区域右下角x: 数字,
+  区域右下角y: 数字,
+  限制数量: 数字,
+  查找方向: 数字,
+): { x: 数字; y: 数字 }[];
+```
+
+**参数：**
+
+| 参数名        | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                                                                                                    |
+| ------------- | ------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `图片ID`      | 字符串 | 是       | -      | 图片 ID                                                                                                                                                                                                                                 |
+| `颜色`        | 字符串 | 是       | -      | 颜色值，支持 "主色-偏色" 格式，如 "#6DD1E6-#101010"                                                                                                                                                                                     |
+| `阈值`        | 数字   | 是       | -      | 颜色匹配阈值 (0.0-1.0)                                                                                                                                                                                                                  |
+| `区域左上角x` | 数字   | 是       | -      | 搜索区域左上角坐标                                                                                                                                                                                                                      |
+| `区域左上角y` | 数字   | 是       | -      | 搜索区域左上角坐标                                                                                                                                                                                                                      |
+| `区域右下角x` | 数字   | 是       | -      | 搜索区域右下角坐标                                                                                                                                                                                                                      |
+| `区域右下角y` | 数字   | 是       | -      | 搜索区域右下角坐标                                                                                                                                                                                                                      |
+| `限制数量`    | 数字   | 是       | -      | 最大查找数量                                                                                                                                                                                                                            |
+| `查找方向`    | 数字   | 是       | -      | 查找方向（1-8） 1 左上角到右下角，纵向开始 2 左上角到右下角，横向开始 3 右上角到左下角，横向开始 4 右上角到左下角，纵向开始 5 右下角到左上角，纵向开始 6 右下角到左上角，横向开始 7 左下角到右上角，横向开始 8 左下角到右上角，纵向开始 |
+
+**返回值：**
+
+| 类型   | 描述                                           |
+| ------ | ---------------------------------------------- |
+| `数组` | 找到的颜色点数组，每个元素包含 `x` 和 `y` 属性 |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  // 查找蓝色按钮
+  const 坐标数组 = $图片.单点找色(
+    图片ID,
+    "#1E90FF-#101010", // 蓝色，允许一定偏差
+    0.9, // 阈值
+    0,
+    0, // 搜索区域左上角
+    400,
+    800, // 搜索区域右下角
+    5, // 最多找 5 个
+    1, // 从左到右查找
+  );
+
+  if (坐标数组.length > 0) {
+    $打印信息日志(`找到 ${坐标数组.length} 个蓝色点`);
+    // 点击第一个找到的点
+    $动作.点击(坐标数组[0].x, 坐标数组[0].y, 100, false);
+  }
+
+  $图片.释放图片(图片ID);
+}
+```
+
+### 多点找色
+
+```typescript
+function 多点找色(
+  图片ID: 字符串,
+  第一个颜色: 字符串,
+  阈值: 数字,
+  颜色点: 字符串,
+  区域左上角x: 数字,
+  区域左上角y: 数字,
+  区域右下角x: 数字,
+  区域右下角y: 数字,
+  限制数量: 数字,
+  查找方向: 数字,
+): { x: 数字; y: 数字 }[];
+```
+
+**参数：**
+
+| 参数名        | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                                                                                                    |
+| ------------- | ------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `图片ID`      | 字符串 | 是       | -      | 图片 ID                                                                                                                                                                                                                                 |
+| `第一个颜色`  | 字符串 | 是       | -      | 第一个颜色                                                                                                                                                                                                                              |
+| `阈值`        | 数字   | 是       | -      | 颜色匹配阈值 (0.0-1.0)                                                                                                                                                                                                                  |
+| `颜色点`      | 字符串 | 是       | -      | 其他颜色点的相对位置和颜色，格式：`x1\|y1\|color1-偏色,x2\|y2\|color2-偏色`                                                                                                                                                             |
+| `区域左上角x` | 数字   | 是       | -      | 搜索区域左上角坐标                                                                                                                                                                                                                      |
+| `区域左上角y` | 数字   | 是       | -      | 搜索区域左上角坐标                                                                                                                                                                                                                      |
+| `区域右下角x` | 数字   | 是       | -      | 搜索区域右下角坐标                                                                                                                                                                                                                      |
+| `区域右下角y` | 数字   | 是       | -      | 搜索区域右下角坐标                                                                                                                                                                                                                      |
+| `限制数量`    | 数字   | 是       | -      | 最大查找数量                                                                                                                                                                                                                            |
+| `查找方向`    | 数字   | 是       | -      | 查找方向（1-8） 1 左上角到右下角，纵向开始 2 左上角到右下角，横向开始 3 右上角到左下角，横向开始 4 右上角到左下角，纵向开始 5 右下角到左上角，纵向开始 6 右下角到左上角，横向开始 7 左下角到右上角，横向开始 8 左下角到右上角，纵向开始 |
+
+**返回值：**
+
+| 类型                         | 描述                                           |
+| ---------------------------- | ---------------------------------------------- |
+| `数组<{ x: 数字; y: 数字 }>` | 找到的颜色点数组，每个元素包含 `x` 和 `y` 属性 |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  // 查找特定的颜色组合（如按钮的特征颜色）
+  const 坐标数组 = $图片.多点找色(
+    图片ID,
+    "#1E90FF-#101010", // 主颜色
+    0.9, // 阈值
+    "10|0|#FFFFFF-#101010,20|0|#000000-#101010", // 相对位置的其他颜色
+    0,
+    0,
+    400,
+    800,
+    1,
+    1,
+  );
+
+  if (坐标数组.length > 0) {
+    $打印信息日志(`找到 ${坐标数组.length} 个匹配的颜色组合`);
+    // 点击第一个找到的点
+    $动作.点击(坐标数组[0].x, 坐标数组[0].y, 100, false);
+  }
+
+  $图片.释放图片(图片ID);
+}
+```
+
+### 多点比色
+
+```typescript
+function 多点比色(图片ID: 字符串, 颜色点: 字符串, 阈值: 数字): 布尔值;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                                                                        |
+| -------- | ------ | -------- | ------ | --------------------------------------------------------------------------- |
+| `图片ID` | 字符串 | 是       | -      | 图片 ID                                                                     |
+| `颜色点` | 字符串 | 是       | -      | 其他颜色点的相对位置和颜色，格式：`x1\|y1\|color1-偏色,x2\|y2\|color2-偏色` |
+| `阈值`   | 数字   | 是       | -      | 颜色匹配阈值 (0.0-1.0)                                                      |
+
+**返回值：**
+
+| 类型     | 描述                                        |
+| -------- | ------------------------------------------- |
+| `布尔值` | 如果颜色匹配则返回 `true`，否则返回 `false` |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  // 检查特定区域是否为预期颜色
+  const isMatch = $图片.多点比色(
+    图片ID,
+    "1|2|#6DD1E6-#101010",
+    0.9, // 阈值
+  );
+
+  if (isMatch) {
+    $打印信息日志("颜色匹配");
+  }
+
+  $图片.释放图片(图片ID);
+}
+```
+
+## 图像识别
+
+### 找图 - 在图片中查找模板图片。
+
+```typescript
+function 找图(
+  图片ID: 字符串,
+  模板图片ID: 字符串,
+  区域左上角x: 数字,
+  区域左上角y: 数字,
+  区域右下角x: 数字,
+  区域右下角y: 数字,
+  阈值: 数字,
+  限制数量: 数字,
+  方法: 数字,
+  是否使用RGB找图?: 布尔值,
+  选项?: {
+    scaleFactors?: 数字[];
+  },
+): {
+  index: 数字; // 模板图片索引
+  x: 数字;
+  y: 数字;
+  width: 数字;
+  height: 数字;
+  confidence: 数字;
+  centerX: 数字;
+  centerY: 数字;
+  ex: 数字;
+  ey: 数字;
+}[];
+```
+
+**参数：**
+
+| 参数名              | 类型    | 是否必填 | 默认值                      | 描述                                                                                                                          |
+| ------------------- | ------- | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `图片ID`            | 字符串  | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）                                |
+| `模板图片ID`        | 字符串  | 是       | -                           | `"screen"`-当前屏幕截图, `string`-图片文件路径或 URL ,`imageId`-图片 ID（通过 image 模块获取）支持按\|分割,多个图片按顺序查找 |
+| `区域左上角x`       | 数字    | 是       | -                           | 搜索区域左上角坐标                                                                                                            |
+| `区域左上角y`       | 数字    | 是       | -                           | 搜索区域左上角坐标                                                                                                            |
+| `区域右下角x`       | 数字    | 是       | -                           | 搜索区域右下角坐标                                                                                                            |
+| `区域右下角y`       | 数字    | 是       | -                           | 搜索区域右下角坐标                                                                                                            |
+| `阈值`              | 数字    | 是       | -                           | 匹配阈值 (0.0-1.0) 全分辨率匹配时建议 0.5-0.6 其他建议 0.9-0.995                                                              |
+| `限制数量`          | 数字    | 是       | -                           | 最大查找数量，每个模板图片最多找 限制数量 个匹配结果                                                                          |
+| `方法`              | 数字    | 是       | -                           | 匹配方法 0 SIFT 全分辨率 1 TM_SQDIFF_NORMED 3 TM_CCORR_NORMED 5 TM_CCOEFF_NORMED 99 全分辨率缩放匹配法                        |
+| `是否使用RGB找图`   | 布尔值  | 否       | `false`                     | 是否使用 RGB 找图，默认 `false` 会自动转灰度找图                                                                              |
+| `选项`              | 对象    | 否       | -                           | 选项                                                                                                                          |
+| `选项.scaleFactors` | 数字\[] | 否       | `[1.0, 0.9, 1.1, 0.8, 1.2]` | 缩放匹配法缩放因子数组，默认 `[1.0, 0.9, 1.1, 0.8, 1.2]` 会在这些缩放比例下进行匹配。                                         |
+
+**返回值：**
+
+| 类型   | 描述                                                                                   |
+| ------ | -------------------------------------------------------------------------------------- |
+| `数组` | 找到的匹配结果数组，每个元素包含位置、尺寸和置信度，其中 index 为模板图片索引从 0 开始 |
+
+**示例：**
+
+```javascript
+const 匹配区域数组 = $图片.找图(
+  "screen",
+  "template.jpg|template2.jpg",
+  0,
+  0,
+  400,
+  800, // 搜索区域
+  0.8, // 80% 匹配度
+  3, // 最多找 3 个
+  5, // 匹配方法
+  false, // 不使用 rgb 找图
+);
+
+if (匹配区域数组.length > 0) {
+  const best = 匹配区域数组[0];
+  $打印信息日志(`找到匹配，置信度: ${best.confidence}`);
+
+  // 点击匹配区域的中心
+  const centerX = best.centerX;
+  const centerY = best.centerY;
+  $动作.点击(centerX, centerY, 100, false);
+}
+```
+
+## 图像处理
+
+### 裁剪图片
+
+```typescript
+function 裁剪图片(
+  图片ID: 字符串,
+  区域左上角x: 数字,
+  区域左上角y: 数字,
+  区域右下角x: 数字,
+  区域右下角y: 数字,
+): 字符串;
+```
+
+**参数：**
+
+| 参数名        | 类型   | 是否必填 | 默认值 | 描述               |
+| ------------- | ------ | -------- | ------ | ------------------ |
+| `图片ID`      | 字符串 | 是       | -      | 原图片 ID          |
+| `区域左上角x` | 数字   | 是       | -      | 裁剪区域左上角坐标 |
+| `区域左上角y` | 数字   | 是       | -      | 裁剪区域左上角坐标 |
+| `区域右下角x` | 数字   | 是       | -      | 裁剪区域右下角坐标 |
+| `区域右下角y` | 数字   | 是       | -      | 裁剪区域右下角坐标 |
+
+**返回值：**
+
+| 类型     | 描述              |
+| -------- | ----------------- |
+| `字符串` | 裁剪后的新图片 ID |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+// 获取手机文档目录
+const dir = $文件.获取内部目录("documents");
+if (图片ID) {
+  // 裁剪屏幕上半部分
+  const screen = $设备.获取屏幕实际宽高();
+  const 裁剪后的图片ID = $图片.裁剪图片(
+    图片ID,
+    0,
+    0,
+    screen.width,
+    screen.height / 2,
+  );
+
+  if (裁剪后的图片ID) {
+    $图片.保存图片(裁剪后的图片ID, `${dir}/top_half.jpg`);
+    $图片.释放图片(裁剪后的图片ID);
+  }
+
+  $图片.释放图片(图片ID);
+}
+```
+
+### 旋转图片
+
+```typescript
+function 旋转图片(图片ID: 字符串, 角度: 数字): 字符串 | null;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                          |
+| -------- | ------ | -------- | ------ | ----------------------------- |
+| `图片ID` | 字符串 | 是       | -      | 原图片 ID                     |
+| `角度`   | 数字   | 是       | -      | 旋转角度，只能是 90、-90、180 |
+
+**返回值：**
+
+| 类型             | 描述                                |
+| ---------------- | ----------------------------------- |
+| `字符串 \| null` | 旋转后的新图片 ID 失败时返回 `null` |
+
+**示例：**
+
+```typescript
+const 图片ID = $图片.读取图片("photo.jpg");
+// 获取手机文档目录
+const dir = $文件.获取内部目录("documents");
+if (图片ID) {
+  const 旋转后的图片ID = $图片.旋转图片(图片ID, 90);
+  if (旋转后的图片ID) {
+    $图片.保存图片(旋转后的图片ID, `${dir}/photo_rotated.jpg`);
+    $图片.释放图片(旋转后的图片ID);
+  }
+  $图片.释放图片(图片ID);
+}
+```
+
+### 灰度化图片
+
+```typescript
+function 灰度化图片(图片ID: 字符串): 字符串;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述      |
+| -------- | ------ | -------- | ------ | --------- |
+| `图片ID` | 字符串 | 是       | -      | 原图片 ID |
+
+**返回值：**
+
+| 类型     | 描述                |
+| -------- | ------------------- |
+| `字符串` | 灰度化后的新图片 ID |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.读取图片("photo.jpg");
+// 获取手机文档目录
+const dir = $文件.获取内部目录("documents");
+if (图片ID) {
+  const 灰度化后的图片ID = $图片.灰度化图片(图片ID);
+  if (灰度化后的图片ID) {
+    $图片.保存图片(灰度化后的图片ID, `${dir}/photo_gray.jpg`);
+    $图片.释放图片(灰度化后的图片ID);
+  }
+  $图片.释放图片(图片ID);
+}
+```
+
+### 二值化图片
+
+```typescript
+function 二值化图片(图片ID: 字符串, 阈值: 数字): 字符串;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                   |
+| -------- | ------ | -------- | ------ | ---------------------- |
+| `图片ID` | 字符串 | 是       | -      | 原图片 ID              |
+| `阈值`   | 数字   | 是       | -      | 二值化阈值 (0.0-255.0) |
+
+**返回值：**
+
+| 类型     | 描述                |
+| -------- | ------------------- |
+| `字符串` | 二值化后的新图片 ID |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+// 获取手机文档目录
+const dir = $文件.获取内部目录("documents");
+if (图片ID) {
+  const 二值化后的图片ID = $图片.二值化图片(图片ID, 128);
+  if (二值化后的图片ID) {
+    $图片.保存图片(二值化后的图片ID, `${dir}/screenshot_binary.jpg`);
+    $图片.释放图片(二值化后的图片ID);
+  }
+  $图片.释放图片(图片ID);
+}
+```
+
+### 绘制矩形
+
+```typescript
+function 绘制矩形(
+  图片ID: 字符串,
+  坐标x: 数字,
+  坐标y: 数字,
+  坐标ex: 数字,
+  坐标ey: 数字,
+  颜色: 字符串,
+  线宽: 数字,
+): 无返回值;
+```
+
+**参数：**
+
+| 参数名           | 类型   | 是否必填 | 默认值 | 描述                        |
+| ---------------- | ------ | -------- | ------ | --------------------------- |
+| `图片ID`         | 字符串 | 是       | -      | 原图片 ID                   |
+| `坐标x, 坐标y`   | 数字   | 是       | -      | 矩形左上角坐标              |
+| `坐标ex, 坐标ey` | 数字   | 是       | -      | 矩形右下角坐标              |
+| `颜色`           | 字符串 | 是       | -      | 颜色，如 "#FF0000" 表示红色 |
+| `线宽`           | 数字   | 是       | -      | 线宽                        |
+
+**示例：**
+
+```javascript
+// 获取手机文档目录
+const dir = $文件.获取内部目录("documents");
+
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  $图片.绘制矩形(图片ID, 100, 100, 200, 100, "#FF0000", 2);
+  $图片.保存图片(图片ID, `${dir}/test.jpg`);
+  $图片.释放图片(图片ID);
+}
+```
+
+### 扫码条码（支持一维码和二维码）
+
+```typescript
+function 扫描条码(图片ID: 字符串): 字符串 | null;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述      |
+| -------- | ------ | -------- | ------ | --------- |
+| `图片ID` | 字符串 | 是       | -      | 原图片 ID |
+
+**返回值：**
+
+| 类型             | 描述                        |
+| ---------------- | --------------------------- |
+| `字符串 \| null` | 扫码结果，失败时返回 `null` |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  const 扫码结果 = $图片.扫描条码(图片ID);
+  if (扫码结果) {
+    $打印信息日志(`扫码结果: ${扫码结果}`);
+  } else {
+    $打印信息日志("扫码失败");
+  }
+  $图片.释放图片(图片ID);
+}
+```
+
+## Base64 转换
+
+### base64 转图片
+
+```typescript
+function base64转图片(base64: 字符串): 字符串;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述          |
+| -------- | ------ | -------- | ------ | ------------- |
+| `base64` | 字符串 | 是       | -      | Base64 字符串 |
+
+**返回值：**
+
+| 类型     | 描述            |
+| -------- | --------------- |
+| `字符串` | 转换后的图片 ID |
+
+**示例：**
+
+```javascript
+const base64Data =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==";
+const 图片ID = $图片.base64转图片(base64Data);
+
+// 获取手机文档目录
+const dir = $文件.获取内部目录("documents");
+if (图片ID) {
+  $图片.保存图片(图片ID, `${dir}/base64.jpg`);
+  $图片.释放图片(图片ID);
+}
+```
+
+### 图片转base64
+
+```typescript
+function 图片转base64(图片ID: 字符串, 格式: 字符串, 质量: 数字): 字符串;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                           |
+| -------- | ------ | -------- | ------ | ------------------------------ |
+| `图片ID` | 字符串 | 是       | -      | 原图片 ID                      |
+| `格式`   | 字符串 | 是       | -      | 图片格式（如 "jpg", "png"）    |
+| `质量`   | 数字   | 是       | -      | 质量 (1-100)，数字越大质量越高 |
+
+**返回值：**
+
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `字符串` | 转换后的 Base64 字符串 |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  const base64 = $图片.图片转base64(图片ID, "jpg", 90);
+  $打印信息日志(`Base64 数据: ${base64.substring(0, 100)}...`);
+  $图片.释放图片(图片ID);
+}
+```
+
+## 安卓独有方法
+
+### 获取Bitmap - 获取安卓的Bitmap对象
+
+此方法仅在安卓可用，用于获取图片的 Bitmap 对象。
+
+```typescript
+function 获取Bitmap(图片ID: 字符串): 任意类型;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述      |
+| -------- | ------ | -------- | ------ | --------- |
+| `图片ID` | 字符串 | 是       | -      | 原图片 ID |
+
+**返回值：**
+
+| 类型  | 描述             |
+| ----- | ---------------- |
+| `any` | 安卓的Bitmap对象 |
+
+**示例：**
+
+```javascript
+const 图片ID = $图片.截取全屏();
+if (图片ID) {
+  const bitmap = $图片.获取Bitmap(图片ID);
+  $打印信息日志(`Bitmap 对象: ${bitmap}`);
+  // 注意：使用完 Bitmap 后，需要调用 recycle() 方法释放内存
+  bitmap.recycle();
+  $图片.释放图片(图片ID);
+}
+
+// 快捷获取截屏bitmap
+const bitmap = $图片.获取Bitmap("screen");
+logi(`Bitmap 对象: ${bitmap}`);
+bitmap.recycle();
+```