ms-vite-plugin 1.1.2 → 1.1.3

package/docs/api/image.md

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