ms-types 0.0.10 → 0.0.13

package/types/image.d.ts

@@ -1,40 +1,73 @@
+/**
+ * 图片模块 包含图片操作、图片内容读写等功能
+ */
 declare namespace image {
   /**
    * 截图
    * @returns 截图的imageId ，如果截图失败则返回null
+   * @example
+   * const imageId = image.captureFullScreen()
+   * if (imageId) {
+   *   image.saveTo(imageId, "screen.png")
+   * }
    */
   function captureFullScreen(): string | null;
   /**
    * 保存图片
    * @param imageId 图片id 路径 http地址或者 screen 实时截屏
    * @param filePath 保存路径
+   * @example
+   * image.saveTo(imageId, "screen.png")
    */
   function saveTo(imageId: string, filePath: string): void;
   /**
    * 图片是否已释放
    * @param imageId 图片id
    * @returns true 已释放 false 未释放
+   * @example
+   * const imageId = image.captureFullScreen()
+   * if (imageId) {
+   *   image.saveTo(imageId, "screen.png")
+   *   image.isRelease(imageId) // false
+   *   image.release(imageId)
+   *   image.isRelease(imageId) // true
+   * }
    */
   function isRelease(imageId: string): boolean;
   /**
    * 释放图片
    * @param imageId 图片id
+   * @example
+   * image.release(imageId)
    */
   function release(imageId: string): void;
   /**
    * 释放所有图片
+   * @example
+   * image.releaseAll()
    */
   function releaseAll(): void;
   /**
    * 获取图片大小
    * @param imageId 图片id
    * @returns 图片大小 {width: number, height: number}
+   * @example
+   * const size = image.getSize(imageId)
+   * if (size) {
+   *   console.log(size.width, size.height)
+   * }
    */
   function getSize(imageId: string): { width: number; height: number } | null;
   /**
    * 读取图片
    * @param path 图片路径
    * @returns 图片id ，如果读取失败则返回null
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   image.saveTo(imageId, "screen.png")
+   * }
+   * image.release(imageId)
    */
   function readImage(path: string): string | null;
   /**
@@ -42,6 +75,15 @@ declare namespace image {
    * @param imageId 图片id
    * @param degree 旋转角度 只能是 90 -90 180
    * @returns 旋转后的图片id ，如果旋转失败则返回null
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const newImageId = image.rotateImage(imageId, 90)
+   *   if (newImageId) {
+   *     image.saveTo(newImageId, "screen.png")
+   *   }
+   *   image.release(imageId)
+   * }
    */
   function rotateImage(imageId: string, degree: number): string | null;
   /**
@@ -54,6 +96,14 @@ declare namespace image {
    * @param ex 右下角x
    * @param ey 右下角y
    * @returns true 相同 false 不同
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const isSame = image.cmpColor(imageId, "1|2|#6DD1E6-#101010", 10, 0, 0, 100, 100)
+   *   if (isSame) {
+   *     console.log("颜色相同")
+   *   }
+   * }
    */
   function cmpColor(
     imageId: string,
@@ -76,6 +126,15 @@ declare namespace image {
    * @param limit 限制数量
    * @param orz 查找方向1-8
    * @returns 颜色点数组
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const points = image.findColor(imageId, "0x6DD1E6-0x101010", 10, 0, 0, 100, 100, 1, 1)
+   *   if (points.length > 0) {
+   *     console.log("找到颜色")
+   *   }
+   * }
+   * image.release(imageId)
    */
   function findColor(
     imageId: string,
@@ -101,6 +160,15 @@ declare namespace image {
    * @param limit 限制数量
    * @param orz 查找方向1-8
    * @returns 颜色点数组
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const points = image.findMultiColor(imageId, "0x6DD1E6-0x101010", 10, "1|2|#6DD1E6-#101010", 0, 0, 100, 100, 1, 1)
+   *   if (points.length > 0) {
+   *     console.log("找到颜色")
+   *   }
+   * }
+   * image.release(imageId)
    */
   function findMultiColor(
     imageId: string,
@@ -122,10 +190,23 @@ declare namespace image {
    * @param y 左上角y
    * @param ex 右下角x
    * @param ey 右下角y
-   * @param weakThreshold 弱阈值
+   * @param threshold 阈值
    * @param limit 限制数量
    * @param method 方法
    * @returns 图片数组
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const templateImageId = image.readImage("template.png")
+   *   if (templateImageId) {
+   *     const points = image.findImage(imageId, templateImageId, 0, 0, 100, 100, 0.8, 1, 0)
+   *     if (points.length > 0) {
+   *       console.log("找到图片")
+   *     }
+   *   }
+   *   image.release(templateImageId)
+   * }
+   * image.release(imageId)
    */
   function findImage(
     imageId: string,
@@ -134,7 +215,7 @@ declare namespace image {
     y: number,
     ex: number,
     ey: number,
-    weakThreshold: number,
+    threshold: number,
     limit: number,
     method: number
   ): {
@@ -152,6 +233,15 @@ declare namespace image {
    * @param ex 坐标ex
    * @param ey 坐标ey
    * @returns 裁剪后的图片id
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const clipImageId = image.clip(imageId, 0, 0, 100, 100)
+   *   if (clipImageId) {
+   *     console.log("裁剪成功")
+   *   }
+   * }
+   * image.release(imageId)
    */
   function clip(
     imageId: string,
@@ -166,6 +256,13 @@ declare namespace image {
    * @param x 坐标x
    * @param y 坐标y
    * @returns 颜色值
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const color = image.pixel(imageId, 0, 0)
+   *   console.log(color)
+   * }
+   * image.release(imageId)
    */
   function pixel(imageId: string, x: number, y: number): number;
   /**
@@ -173,6 +270,13 @@ declare namespace image {
    * @param imageId 图片id
    * @param color 颜色值
    * @returns 16进制RGB字符串
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const color = image.pixel(imageId, 0, 0)
+   *   console.log(image.argb(imageId, color))
+   * }
+   * image.release(imageId)
    */
   function argb(imageId: string, color: number): string;
   /**
@@ -180,26 +284,57 @@ declare namespace image {
    * @param imageId 图片id
    * @param threshold 阈值
    * @returns 二值化后的图片id
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const binaryzationImageId = image.binaryzation(imageId, 128)
+   *   if (binaryzationImageId) {
+   *     console.log("二值化成功")
+   *   }
+   * }
+   * image.release(imageId)
    */
   function binaryzation(imageId: string, threshold: number): string;
   /**
    * 灰度化
    * @param imageId 图片id
    * @returns 灰度化后的图片id
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const grayImageId = image.gray(imageId)
+   *   if (grayImageId) {
+   *     console.log("灰度化成功")
+   *   }
+   * }
+   * image.release(imageId)
    */
   function gray(imageId: string): string;
   /**
-   * 图片转base64
-   * @param imageId 图片id
-   * @returns base64字符串
+   * base64转图片
+   * @param base64 base64字符串
+   * @returns 图片id
+   * @example
+   * const imageId = image.base64ToImage("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==")
+   * if (imageId) {
+   *   console.log("base64转图片成功")
+   * }
+   * image.release(imageId)
    */
   function base64ToImage(base64: string): string;
   /**
    * 图片转base64
    * @param imageId 图片id
    * @param format 格式
-   * @param q 质量
+   * @param q 质量 1-100 数字越大质量越高
    * @returns base64字符串
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const base64 = image.toBase64Format(imageId, "png", 100)
+   *   console.log(base64)
+   * }
+   * image.release(imageId)
    */
   function toBase64Format(imageId: string, format: string, q: number): string;
 }

package/types/ime.d.ts

@@ -1,59 +1,99 @@
+/**
+ * 输入法模块 包含输入法操作、输入法内容读写等功能
+ */
 declare namespace ime {
   /**
-   * 检查输入法是否正常工作 键盘是否显示
-   * @returns {boolean} 如果输入法正常工作返回 true，否则返回 false
+   * 检查输入法是否正常工作 键盘是否已弹出
+   * @returns {boolean} 如果输入法键盘是否已弹出返回 true，否则返回 false
+   * @example
+   * if (ime.isOk()) {
+   *   console.log("输入法已启动")
+   * }
    */
   function isOk(): boolean;
   /**
    * 获取当前输入框的文本内容
    * @returns {string} 当前输入框的完整文本
+   * @example
+   * const text = ime.getText()
+   * console.log(text)
    */
   function getText(): string;
   /**
    * 清空当前输入框的文本内容
+   * @example
+   * ime.clearText()
    */
   function clearText(): boolean;
   /**
    * 模拟输入文本
    * @param {string} text 要输入的文本
    * @returns {string} 输入后的文本内容 失败返回空字符串
+   * @example
+   * const text = ime.input("hello")
+   * console.log(text)
    */
   function input(text: string): string;
   /**
    * 模拟粘贴文本
    * @param {string} text 要粘贴的文本
    * @returns {string} 粘贴后的文本内容 失败返回空字符串
+   * @example
+   * const text = ime.paste("hello")
+   * console.log(text)
    */
   function paste(text: string): string;
   /**
    * 模拟删除键
    * @returns {string} 如果为空，代表输入框无数据，如果不为空，代表输入框剩余数据
+   * @example
+   * const text = ime.pressDel()
+   * console.log(text)
    */
   function pressDel(): string;
   /**
    * 模拟回车键
    * @returns {boolean} 如果成功返回 true，否则返回 false
+   * @example
+   * if (ime.pressEnter()) {
+   *   console.log("回车键按下")
+   * }
    */
   function pressEnter(): boolean;
   /**
    * 隐藏键盘
    * @returns {boolean} 如果成功返回 true，否则返回 false
+   * @example
+   * if (ime.dismiss()) {
+   *   console.log("键盘已隐藏")
+   * }
    */
   function dismiss(): boolean;
   /**
    * 获取剪贴板内容
    * @returns {string} 剪贴板内容
+   * @example
+   * const text = ime.getClipboard()
+   * console.log(text)
    */
   function getClipboard(): string;
   /**
    * 设置剪贴板内容
    * @param {string} text 要设置的剪贴板内容 键盘显示时才能设置
    * @returns {boolean} 如果成功返回 true，否则返回 false
+   * @example
+   * if (ime.setClipboard("hello")) {
+   *   console.log("剪贴板内容已设置")
+   * }
    */
   function setClipboard(text: string): boolean;
   /**
    * 切换键盘
    * @returns {boolean} 如果成功返回 true，否则返回 false
+   * @example
+   * if (ime.switchKeyboard()) {
+   *   console.log("键盘已切换")
+   * }
    */
   function switchKeyboard(): boolean;
 }

package/types/index.d.ts

@@ -8,7 +8,7 @@
 /// <reference path="ime.d.ts" />
 /// <reference path="logger.d.ts" />
 /// <reference path="media.d.ts" />
-/// <reference path="ocr.d.ts" />
+/// <reference path="paddleocr.d.ts" />
 /// <reference path="system.d.ts" />
 /// <reference path="thread.d.ts" />
 /// <reference path="ui.d.ts" />

package/types/logger.d.ts

@@ -1,38 +1,55 @@
+/**
+ * 日志模块 包含日志输出、日志等级设置等功能
+ */
 declare namespace logger {
   /**
-   * 设置日志等级
+   * 设置日志等级 开发环境默认debug 打包后默认info 可选值error、warn、debug、info、off
    * @param level 日志等级
+   * @example
+   * logger.setLoggerLevel("info");
    */
   function setLoggerLevel(
     level: "error" | "warn" | "debug" | "info" | "off"
   ): void;
   /**
-   * 设置是否输出到文件
+   * 设置是否输出到文件 默认开启
    * @param enabled 是否输出到文件
+   * @example
+   * logger.setLogToFile(true);
    */
   function setLogToFile(enabled: boolean): void;
   /**
-   * 重置日志文件
+   * 重置日志文件 会创建一个新的日志文件 避免一个日志文件太大
+   * @example
+   * logger.resetLogFile();
    */
   function resetLogFile(): void;
   /**
    * 调试日志
    * @param log 日志内容
+   * @example
+   * logger.debug("调试日志");
    */
   function debug(log: string): void;
   /**
    * 信息日志
    * @param log 日志内容
+   * @example
+   * logger.info("信息日志");
    */
   function info(log: string): void;
   /**
    * 警告日志
    * @param log 日志内容
+   * @example
+   * logger.warn("警告日志");
    */
   function warn(log: string): void;
   /**
    * 错误日志
    * @param log 日志内容
+   * @example
+   * logger.error("错误日志");
    */
   function error(log: string): void;
 }

package/types/media.d.ts

@@ -1,8 +1,19 @@
+/**
+ * 媒体模块 包含媒体操作、媒体内容读写等功能
+ */
 declare namespace media {
   /**
    * 保存图像到相册
    * @param img 图像ID
    * @returns 是否保存成功
+   * @example
+   * const imageId = image.readImage("screen.png")
+   * if (imageId) {
+   *   const saved = media.saveImageToAlbum(imageId)
+   *   if (saved) {
+   *     console.log("保存成功")
+   *   }
+   * }
    */
   function saveImageToAlbum(img: string): boolean;
 
@@ -10,18 +21,33 @@ declare namespace media {
    * 保存视频路径到相册
    * @param path 视频文件的路径
    * @returns 是否保存成功
+   * @example
+   * const saved = media.saveVideoToAlbumPath("video.mp4")
+   * if (saved) {
+   *   console.log("保存成功")
+   * }
    */
   function saveVideoToAlbumPath(path: string): boolean;
 
   /**
    * 清空相册中的图片
    * @returns 是否删除成功
+   * @example
+   * const deleted = media.deleteAllPhotos()
+   * if (deleted) {
+   *   console.log("删除成功")
+   * }
    */
   function deleteAllPhotos(): boolean;
 
   /**
    * 清空相册中的视频
    * @returns 是否删除成功
+   * @example
+   * const deleted = media.deleteAllVideos()
+   * if (deleted) {
+   *   console.log("删除成功")
+   * }
    */
   function deleteAllVideos(): boolean;
 
@@ -30,12 +56,22 @@ declare namespace media {
    * @param path 文件路径
    * @param loop 是否循环播放
    * @returns 是否播放成功
+   * @example
+   * const played = media.playMp3("music.mp3", true)
+   * if (played) {
+   *   console.log("播放成功")
+   * }
    */
   function playMp3(path: string, loop: boolean): boolean;
 
   /**
    * 停止播放mp3音乐
    * @returns 是否停止成功
+   * @example
+   * const stopped = media.stopMp3()
+   * if (stopped) {
+   *   console.log("停止成功")
+   * }
    */
   function stopMp3(): boolean;
 
@@ -44,6 +80,11 @@ declare namespace media {
    * @param path 文件路径
    * @param loop 是否循环播放
    * @returns 是否播放成功
+   * @example
+   * const played = media.playMp3WaitEnd("music.mp3", true)
+   * if (played) {
+   *   console.log("播放成功")
+   * }
    */
   function playMp3WaitEnd(path: string, loop: boolean): boolean;
 }

package/types/node.d.ts

@@ -1,3 +1,6 @@
+/**
+ * 节点模块 包含节点操作、节点内容读写等功能
+ */
 declare function createNodeSelector(params: {
   /**
    *  1 代表不管visible是true还是false都获取，2 代表只获取 visible=true的节点
@@ -137,6 +140,9 @@ declare interface NodeInfo {
   nextSiblings(): NodeInfo[];
 }
 
+/**
+ * 节点选择器 包含节点选择、节点操作等功能
+ */
 declare class NodeSelector {
   /**
    * 获取节点信息

package/types/{ocr.d.ts → paddleocr.d.ts}

@@ -1,10 +1,18 @@
-declare namespace ocr {
+/**
+ * 飞桨OCR模块 包含OCR识别、OCR模型加载等功能
+ */
+declare namespace paddleocr {
   /**
-   * 初始化OCR模型
+   * 初始化PP-OCRv5模型
    * @param useGpu 是否使用GPU，默认false
    * @returns 初始化是否成功
+   * @example
+   * const loaded = paddleocr.loadV5(true)
+   * if (loaded) {
+   *   console.log("加载成功")
+   * }
    */
-  function loadModel(useGpu: boolean): boolean;
+  function loadV5(useGpu: boolean): boolean;
   /**
    * 执行OCR识别
    * @param input 输入源（imageId、URL字符串、文件路径或"screen"，nil表示使用当前屏幕）
@@ -13,6 +21,11 @@ declare namespace ocr {
    * @param ex 边界框右下角x坐标
    * @param ey 边界框右下角y坐标
    * @returns 识别结果数组
+   * @example
+   * const results = paddleocr.recognize("screen", 0, 0, 100, 100)
+   * if (results.length > 0) {
+   *   console.log("识别到文本")
+   * }
    */
   function recognize(
     input: string | null,