ms-types 0.9.13 → 0.9.16

package/package.json

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

package/types/cloud.d.ts

@@ -8,7 +8,7 @@ declare namespace cloud {
    * @param url 完整 ws:// 或 wss:// 云控地址。
    * @param deviceNo 可选设备编号，不传时沿用当前保存的设备编号。
    * @returns URL 校验通过且连接请求已提交时返回 true。
-   * @description 只能在主脚本上下文调用；只影响当前运行期云控连接，不会写入设置页的持久化云控配置。
+   * @description 只能在主脚本上下文调用；只影响当前运行期云控连接，不会写入设置页的持久化云控配置；授权卡密模式不可用。
    * @example
    * const accepted = cloud.connect("wss://example.com/control", "device-001");
    */
@@ -36,6 +36,7 @@ declare namespace cloud {
    * @param event 自定义事件名称。
    * @param data 可 JSON 序列化的普通 Object。
    * @returns 已连接且数据可写出时返回 true。
+   * @description 设备总览状态固定使用 cloud.report("cloud:status", data) 上报；data 的 key 必须是云控端已配置的自定义字段名，多余字段不会在设备总览显示。
    * @example
    * cloud.report("done", { value: 1 });
    */

package/types/global.d.ts

@@ -81,13 +81,21 @@ 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;
 
 /**
  * 设置异常停止回调（仅主线程调用，不能在线程脚本中调用）
@@ -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/media.d.ts

@@ -87,9 +87,9 @@ declare namespace media {
   function stopMp3(): boolean;
 
   /**
-   * 同步播放MP3音乐（播放一次并等待结束）
+   * 同步播放MP3音乐（播放一次并等待结束；系统音频中断、停止或被新播放替换时立即返回 false）
    * @param path 文件路径
-   * @returns 是否播放成功
+   * @returns 是否正常播放到结尾
    * @example
    * const played = media.playMp3WaitEnd("music.mp3")
    * if (played) {

package/types/netCard.d.ts

@@ -25,8 +25,19 @@ declare namespace netCard {
     expireTime: string;
   }
 
+  /**
+   * 判断当前是否为授权卡密模式
+   * @returns 当前 App 处于授权卡密模式返回 true，否则返回 false
+   * @example
+   * if (netCard.isAuthCardMode()) {
+   *   logi("当前为授权卡密模式，不需要重复调用 verify")
+   * }
+   */
+  function isAuthCardMode(): boolean;
+
   /**
    * 验证卡密
+   * 授权卡密模式下，App 打开加密 UI 或运行脚本前会完成授权和卡密验证，脚本侧调用直接返回 true
    * @param cardNo 卡密
    * @returns 是否验证成功
    * @example

package/types/ui.d.ts

@@ -75,6 +75,12 @@ declare namespace ms {
    */
   function getServerDeviceId(): Promise<string>;
 
+  /**
+   * 获取当前软件包缓存的授权卡密
+   * @returns 有缓存的授权卡密时返回卡密字符串，没有缓存时返回空字符串
+   */
+  function getAuthCardNo(): Promise<string>;
+
   /**
    * 获取Agent状态
    * @returns 如果Agent正在运行返回true，否则返回false

package/types/utils.d.ts

@@ -7,7 +7,7 @@ declare namespace utils {
    * @param format 格式化字符串
    * @returns 格式化后的时间字符串
    * @example
-   * utils.timeFormat("yyyy-MM-dd hh:mm:ss")
+   * utils.timeFormat("yyyy-MM-dd HH:mm:ss")
    */
   function timeFormat(format: string): string;
   /**

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

@@ -6,7 +6,7 @@ declare namespace $云控 {
    * @param 地址 完整 ws:// 或 wss:// 云控地址。
    * @param 设备编号 可选设备编号，不传时沿用当前保存的设备编号。
    * @returns URL 校验通过且连接请求已提交时返回 true。
-   * @description 只能在主脚本上下文调用；只影响当前运行期云控连接，不会写入设置页的持久化云控配置。
+   * @description 只能在主脚本上下文调用；只影响当前运行期云控连接，不会写入设置页的持久化云控配置；授权卡密模式不可用。
    * @example
    * const 已提交 = $云控.连接("wss://example.com/control", "device-001");
    */
@@ -34,6 +34,7 @@ declare namespace $云控 {
    * @param 事件 自定义事件名称。
    * @param 数据 可 JSON 序列化的普通 Object。
    * @returns 已连接且数据可写出时返回 true。
+   * @description 设备总览状态固定使用 $云控.上报数据("cloud:status", 数据) 上报；数据的 key 必须是云控端已配置的自定义字段名，多余字段不会在设备总览显示。
    * @example
    * $云控.上报数据("done", { value: 1 });
    */

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

@@ -80,13 +80,21 @@ 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") => 无返回值,
+) => 无返回值;
 
 /**
  * 设置异常停止回调（仅主线程调用，不能在线程脚本中调用）

package/types/zh//345/215/241/345/257/206/346/250/241/345/235/227.d.ts

@@ -30,8 +30,19 @@ declare namespace $卡密 {
     expireTime: string;
   }
 
+  /**
+   * 判断当前是否为授权卡密模式
+   * @returns 当前 App 处于授权卡密模式返回 true，否则返回 false
+   * @example
+   * if ($卡密.是否授权卡密模式()) {
+   *   $打印信息日志("当前为授权卡密模式，不需要重复调用验证")
+   * }
+   */
+  function 是否授权卡密模式(): 布尔值;
+
   /**
    * 验证卡密
+   * 授权卡密模式下，App 打开加密 UI 或运行脚本前会完成授权和卡密验证，脚本侧调用直接返回 true
    * @param 卡密
    * @returns 是否验证成功
    * @example

package/types/zh//345/252/222/344/275/223/346/250/241/345/235/227.d.ts

@@ -88,9 +88,9 @@ declare namespace $媒体 {
   function 停止播放MP3音乐(): 布尔值;
 
   /**
-   * 同步播放MP3音乐（播放一次并等待结束）
+   * 同步播放MP3音乐（播放一次并等待结束；系统音频中断、停止或被新播放替换时立即返回 false）
    * @param 文件路径
-   * @returns 是否播放成功
+   * @returns 是否正常播放到结尾
    * @example
    * const 是否播放成功 = $媒体.同步播放MP3音乐("music.mp3")
    * if (是否播放成功) {

package/types/zh//345/267/245/345/205/267/346/250/241/345/235/227.d.ts

@@ -9,7 +9,7 @@ declare namespace $工具 {
    * @param format 格式化字符串
    * @returns 格式化后的时间字符串
    * @example
-   * $工具.获取当前时间字符串("yyyy-MM-dd hh:mm:ss")
+   * $工具.获取当前时间字符串("yyyy-MM-dd HH:mm:ss")
    */
   function 获取当前时间字符串(格式化字符串: 字符串): 字符串;
   /**