ms-types 0.9.12 → 0.9.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-types",
-  "version": "0.9.12",
+  "version": "0.9.15",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/types/cloud.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 云控模块类型定义
+ * 提供主脚本侧连接云控、断开连接、判断连接状态、上报 Object 数据和监听服务端事件的能力。
+ */
+declare namespace cloud {
+  /**
+   * 连接云控服务器。
+   * @param url 完整 ws:// 或 wss:// 云控地址。
+   * @param deviceNo 可选设备编号，不传时沿用当前保存的设备编号。
+   * @returns URL 校验通过且连接请求已提交时返回 true。
+   * @description 只能在主脚本上下文调用；只影响当前运行期云控连接，不会写入设置页的持久化云控配置。
+   * @example
+   * const accepted = cloud.connect("wss://example.com/control", "device-001");
+   */
+  function connect(url: string, deviceNo?: string): boolean;
+
+  /**
+   * 判断云控是否已经连接成功。
+   * @returns 已连接时返回 true。
+   * @example
+   * if (cloud.isConnected()) {
+   *   cloud.report("status", { value: "ready" });
+   * }
+   */
+  function isConnected(): boolean;
+
+  /**
+   * 断开云控连接并停止自动重连。
+   * @example
+   * cloud.disconnect();
+   */
+  function disconnect(): void;
+
+  /**
+   * 上报普通 Object 到云控服务器。
+   * @param event 自定义事件名称。
+   * @param data 可 JSON 序列化的普通 Object。
+   * @returns 已连接且数据可写出时返回 true。
+   * @description 设备总览状态固定使用 cloud.report("cloud:status", data) 上报；data 的 key 必须是云控端已配置的自定义字段名，多余字段不会在设备总览显示。
+   * @example
+   * cloud.report("done", { value: 1 });
+   */
+  function report(event: string, data: Record<string, any>): boolean;
+
+  /**
+   * 监听服务端下发的 scriptEvent 事件（仅主线程调用，不能在线程脚本中调用）。
+   * @param callback 主脚本回调函数；传入 null 可取消监听。
+   * @example
+   * cloud.onEvent((event, data) => {
+   *   logi("server event:", event, data);
+   * });
+   */
+  function onEvent(
+    callback: ((event: string, data: Record<string, any>) => void) | null,
+  ): void;
+}

package/types/global.d.ts

@@ -79,18 +79,26 @@ declare const sharedState: {
 };
 
 /**
- * 设置停止回调（仅主线程调用）
+ * 设置停止回调（仅主线程调用，不能在线程脚本中调用）
  * @param callback 停止回调
- * @description 脚本执行完成或异常停止时调用，exit 退出不会触发
+ * @description 脚本执行停止时调用，success 表示正常停止，error 表示异常停止，stopped 表示手动停止
  * @example
- * setStopCallback(() => {
- *   logi("脚本执行完成");
+ * setStopCallback((status) => {
+ *   if (status === "success") {
+ *     logi("脚本执行完成");
+ *   } else if (status === "error") {
+ *     loge("脚本执行异常");
+ *   } else if (status === "stopped") {
+ *     logi("脚本手动停止");
+ *   }
  * });
  */
-declare function setStopCallback(callback: () => void): void;
+declare function setStopCallback(
+  callback: (status: "success" | "error" | "stopped") => void,
+): void;
 
 /**
- * 设置异常停止回调（仅主线程调用）
+ * 设置异常停止回调（仅主线程调用，不能在线程脚本中调用）
  * @param callback 异常停止回调
  * @description 脚本执行异常停止时调用
  * @example
@@ -192,7 +200,10 @@ declare function getCpuAutoThrottle(): boolean;
  * @example
  * const delay = setCpuThrottleDelay(3, 30);
  */
-declare function setCpuThrottleDelay(minMs: number, maxMs: number): { minMs: number; maxMs: number };
+declare function setCpuThrottleDelay(
+  minMs: number,
+  maxMs: number,
+): { minMs: number; maxMs: number };
 
 /**
  * 获取 CPU 限流延迟范围（毫秒）

package/types/index.d.ts

@@ -1,5 +1,6 @@
 /// <reference path="action.d.ts" />
 /// <reference path="appleOcr.d.ts" />
+/// <reference path="cloud.d.ts" />
 /// <reference path="config.d.ts" />
 /// <reference path="cryptoUtils.d.ts" />
 /// <reference path="device.d.ts" />

package/types/ui.d.ts

@@ -111,8 +111,8 @@ declare namespace ui {
   function show(): void;
 
   /**
-   * 设置事件回调函数
-   * @param onEvent 事件回调函数
+   * 设置事件回调函数（仅主线程调用，不能在线程脚本中调用）
+   * @param onEvent 事件回调函数，传入 null 会取消监听
    * @example
    * ui.onEvent((event, data) => {
    *   // 接收网页发送的事件
@@ -120,7 +120,7 @@ declare namespace ui {
    * })
    */
   function onEvent(
-    event: (event: string, data: Record<string, any>) => void,
+    event: ((event: string, data: Record<string, any>) => void) | null,
   ): void;
 
   /**

package/types/zh/index.d.ts

@@ -3,6 +3,7 @@
 /// <reference path="节点模块.d.ts" />
 /// <reference path="卡密模块.d.ts" />
 /// <reference path="媒体模块.d.ts" />
+/// <reference path="云控模块.d.ts" />
 /// <reference path="配置模块.d.ts" />
 /// <reference path="苹果OCR.d.ts" />
 /// <reference path="全局模块.d.ts" />

package/types/zh//344/272/221/346/216/247/346/250/241/345/235/227.d.ts

@@ -0,0 +1,54 @@
+/// <reference path="全局模块.d.ts" />
+
+declare namespace $云控 {
+  /**
+   * 连接云控服务器。
+   * @param 地址 完整 ws:// 或 wss:// 云控地址。
+   * @param 设备编号 可选设备编号，不传时沿用当前保存的设备编号。
+   * @returns URL 校验通过且连接请求已提交时返回 true。
+   * @description 只能在主脚本上下文调用；只影响当前运行期云控连接，不会写入设置页的持久化云控配置。
+   * @example
+   * const 已提交 = $云控.连接("wss://example.com/control", "device-001");
+   */
+  function 连接(地址: 字符串, 设备编号?: 字符串): 布尔值;
+
+  /**
+   * 判断云控是否已经连接成功。
+   * @returns 已连接时返回 true。
+   * @example
+   * if ($云控.是否已连接()) {
+   *   $云控.上报数据("status", { value: "ready" });
+   * }
+   */
+  function 是否已连接(): 布尔值;
+
+  /**
+   * 断开云控连接并停止自动重连。
+   * @example
+   * $云控.断开连接();
+   */
+  function 断开连接(): 无返回值;
+
+  /**
+   * 上报普通 Object 到云控服务器。
+   * @param 事件 自定义事件名称。
+   * @param 数据 可 JSON 序列化的普通 Object。
+   * @returns 已连接且数据可写出时返回 true。
+   * @description 设备总览状态固定使用 $云控.上报数据("cloud:status", 数据) 上报；数据的 key 必须是云控端已配置的自定义字段名，多余字段不会在设备总览显示。
+   * @example
+   * $云控.上报数据("done", { value: 1 });
+   */
+  function 上报数据(事件: 字符串, 数据: 字典<任意类型>): 布尔值;
+
+  /**
+   * 监听服务端下发的 scriptEvent 事件（仅主线程调用，不能在线程脚本中调用）。
+   * @param 回调 主脚本回调函数；传入 null 可取消监听。
+   * @example
+   * $云控.监听事件回调((事件, 数据) => {
+   *   $打印信息日志("server event:", 事件, 数据);
+   * });
+   */
+  function 监听事件回调(
+    回调: ((事件: 字符串, 数据: 字典<任意类型>) => 无返回值) | null
+  ): 无返回值;
+}

package/types/zh//345/205/250/345/261/200/346/250/241/345/235/227.d.ts

@@ -78,18 +78,26 @@ declare const $共享状态: {
 };
 
 /**
- * 设置停止回调（仅主线程调用）
+ * 设置停止回调（仅主线程调用，不能在线程脚本中调用）
  * @param callback 停止回调
- * @description 脚本执行完成或异常停止时调用，exit 退出不会触发
+ * @description 脚本执行停止时调用，success 表示正常停止，error 表示异常停止，stopped 表示手动停止
  * @example
- * $设置停止回调(() => {
- *   $打印信息日志("脚本执行完成");
+ * $设置停止回调((状态) => {
+ *   if (状态 === "success") {
+ *     $打印信息日志("脚本执行完成");
+ *   } else if (状态 === "error") {
+ *     $打印错误日志("脚本执行异常");
+ *   } else if (状态 === "stopped") {
+ *     $打印信息日志("脚本手动停止");
+ *   }
  * });
  */
-declare const $设置停止回调: (回调: () => 无返回值) => 无返回值;
+declare const $设置停止回调: (
+  回调: (状态: "success" | "error" | "stopped") => 无返回值,
+) => 无返回值;
 
 /**
- * 设置异常停止回调（仅主线程调用）
+ * 设置异常停止回调（仅主线程调用，不能在线程脚本中调用）
  * @param callback 异常停止回调
  * @description 脚本执行异常停止时调用
  * @example

package/types/zh//350/247/206/345/233/276/346/250/241/345/235/227.d.ts

@@ -10,8 +10,8 @@ declare namespace $视图 {
   function 显示(): 无返回值;
 
   /**
-   * 设置事件回调函数
-   * @param onEvent 事件回调函数
+   * 设置事件回调函数（仅主线程调用，不能在线程脚本中调用）
+   * @param onEvent 事件回调函数，传入 null 会取消监听
    * @example
    * $视图.监听事件回调((事件名称, 数据) => {
    *   // 接收网页发送的事件
@@ -19,7 +19,7 @@ declare namespace $视图 {
    * })
    */
   function 监听事件回调(
-    回调函数: (事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值
+    回调函数: ((事件名称: 字符串, 数据: 字典<任意类型>) => 无返回值) | null
   ): 无返回值;
 
   /**