@ray-js/api 1.7.70 → 1.7.72

package/lib/nativeRouters/gw.js

@@ -1,26 +1,75 @@
 import { nativeRouter } from './common';
 /**
  * 打开 ZigBee 网关面板配网子设备(旧版)
- * @param params { gwId?: string }
- * @returns
+ * @param params - 网关参数
+ * @param params.gwId 网关 ID
+ * @returns void
+ * @public
+ * @since @ray-js/ray 1.7.60
+ * @example
+ * ```typescript
+ * import { openPresentGatewayCategroy } from '@ray-js/ray';
+ *
+ * const openGatewayCategory = async () => {
+ *   try {
+ *     await openPresentGatewayCategroy({ gwId: 'gateway_001' });
+ *     console.log('已打开网关配网子设备页面');
+ *   } catch (err) {
+ *     console.error('打开失败:', err);
+ *   }
+ * };
+ * ```
+ * @deprecated 请使用 openDeviceGWSubSearchConfigure 代替
  */
 export function openPresentGatewayCategroy(params) {
   return nativeRouter('presentGatewayCategroy', params);
 }
 
 /**
- * 打开网关面板配网子设备 - 搜索配网(新版)
- * @param params { gwId?: string }
- * @returns
+ * 打开网关面板搜索配网页面，用于搜索并添加子设备
+ * @param params - 网关参数
+ * @param params.gwId 网关 ID
+ * @returns void
+ * @public
+ * @since @ray-js/ray 1.7.60
+ * @example
+ * ```typescript
+ * import { openDeviceGWSubSearchConfigure } from '@ray-js/ray';
+ *
+ * const openSearchPage = async () => {
+ *   try {
+ *     await openDeviceGWSubSearchConfigure({ gwId: 'gateway_001' });
+ *     console.log('已打开搜索配网页面');
+ *   } catch (err) {
+ *     console.error('打开失败:', err);
+ *   }
+ * };
+ * ```
  */
 export function openDeviceGWSubSearchConfigure(params) {
   return nativeRouter('device_only_search_config_gw_sub', params);
 }
 
 /**
- * 打开网关面板配网子设备 - 配网帮助列表(新版)
- * @param params { gwId?: string }
- * @returns
+ * 打开网关面板配网子设备帮助列表页面
+ * @param params - 网关参数
+ * @param params.gwId 网关 ID
+ * @returns void
+ * @public
+ * @since @ray-js/ray 1.7.60
+ * @example
+ * ```typescript
+ * import { openDeviceGWSubHelpList } from '@ray-js/ray';
+ *
+ * const openHelpList = async () => {
+ *   try {
+ *     await openDeviceGWSubHelpList({ gwId: 'gateway_001' });
+ *     console.log('已打开配网帮助列表');
+ *   } catch (err) {
+ *     console.error('打开失败:', err);
+ *   }
+ * };
+ * ```
  */
 export function openDeviceGWSubHelpList(params) {
   return nativeRouter('device_gw_sub_device_help_list', params);

package/lib/nativeRouters/outdoors.d.ts

@@ -3,9 +3,22 @@ type OpenOutdoorCyclingNavigationParams = {
     devId?: string;
 } & ICommon;
 /**
- * 打开骑行导航页面
- * @param params {devId: string}
- * @returns
+ * 跳转骑行导航页面
+ *
+ * @public
+ * @since @ray-js/ray 1.4.29
+ * @param params - 请求参数
+ * @remarks 当前功能仅在智慧出行 App 开通使用，开发者工具环境无法使用，需要打包后或真机调试使用
+ * @example 基础用法
+ * ```ts
+ * import { openOutdoorCyclingNavigation } from '@ray-js/ray';
+ *
+ * openOutdoorCyclingNavigation({
+ *   devId: 'your_device_id',
+ * }).then(() => {
+ *   console.log('已跳转骑行导航页面');
+ * });
+ * ```
  */
 export declare function openOutdoorCyclingNavigation(params?: OpenOutdoorCyclingNavigationParams): Promise<void>;
 type OpenAdditionalUnlockMethodsParams = {

package/lib/nativeRouters/outdoors.js

@@ -1,8 +1,21 @@
 import { nativeRouter } from './common';
 /**
- * 打开骑行导航页面
- * @param params {devId: string}
- * @returns
+ * 跳转骑行导航页面
+ *
+ * @public
+ * @since @ray-js/ray 1.4.29
+ * @param params - 请求参数
+ * @remarks 当前功能仅在智慧出行 App 开通使用，开发者工具环境无法使用，需要打包后或真机调试使用
+ * @example 基础用法
+ * ```ts
+ * import { openOutdoorCyclingNavigation } from '@ray-js/ray';
+ *
+ * openOutdoorCyclingNavigation({
+ *   devId: 'your_device_id',
+ * }).then(() => {
+ *   console.log('已跳转骑行导航页面');
+ * });
+ * ```
  */
 export function openOutdoorCyclingNavigation(params) {
   return nativeRouter('tsod_cycling_navigation', params);

package/lib/nativeRouters/remoteGroup.d.ts

@@ -18,5 +18,28 @@ type OpenZigbeeLocalGroupParams = {
      */
     codes: string;
 } & ICommon;
+/**
+ * 跳转 Zigbee 遥控器群组配对页面
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @remarks 当前仅针对 Zigbee 的部分品类开通了此类能力
+ * @example 基础用法
+ * ```ts
+ * import { openZigbeeLocalGroup } from '@ray-js/ray';
+ *
+ * openZigbeeLocalGroup({
+ *   deviceId: 'your_device_id',
+ *   localId: '1234',
+ *   categoryCode: '7001',
+ *   codes: 'dj',
+ * }).then(() => {
+ *   console.log('已跳转群组配对页面');
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
+ */
 export declare function openZigbeeLocalGroup(params?: OpenZigbeeLocalGroupParams): Promise<void>;
 export {};

package/lib/nativeRouters/remoteGroup.js

@@ -1,5 +1,28 @@
 import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import { nativeRouter } from './common';
+/**
+ * 跳转 Zigbee 遥控器群组配对页面
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @remarks 当前仅针对 Zigbee 的部分品类开通了此类能力
+ * @example 基础用法
+ * ```ts
+ * import { openZigbeeLocalGroup } from '@ray-js/ray';
+ *
+ * openZigbeeLocalGroup({
+ *   deviceId: 'your_device_id',
+ *   localId: '1234',
+ *   categoryCode: '7001',
+ *   codes: 'dj',
+ * }).then(() => {
+ *   console.log('已跳转群组配对页面');
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
+ */
 export function openZigbeeLocalGroup(params) {
   const realParams = _objectSpread({}, params);
   // 统一成 TTT 的 deviceId 写法，但实际入参为 devId

package/lib/nativeRouters/root.d.ts

@@ -22,11 +22,30 @@ type OpenMoreService = {} & ICommon;
  */
 export declare function openMoreService(params?: OpenMoreService): Promise<void>;
 type OpenAppHelpCenter = {
+    /** 业务编码 */
     bizCode?: string;
+    /** 页面标识 */
     key?: string;
 } & ICommon;
 /**
  * 跳转到App帮助与反馈页
+ * @param params - 帮助中心页面参数，可指定业务编码和页面标识
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @example
+ * ```ts
+ * openAppHelpCenter({
+ *   bizCode: 'help_center',
+ *   key: 'main_page',
+ *   success() {
+ *     console.log('跳转帮助中心成功');
+ *   },
+ *   fail(err) {
+ *     console.log('跳转失败', err);
+ *   },
+ * });
+ * ```
+ * @public
+ * @since @ray-js/ray 1.4.48
  */
 export declare function openAppHelpCenter(params?: OpenAppHelpCenter): Promise<void>;
 type OpenMessageCenter = {

package/lib/nativeRouters/root.js

@@ -32,6 +32,23 @@ export function openMoreService(params) {
 
 /**
  * 跳转到App帮助与反馈页
+ * @param params - 帮助中心页面参数，可指定业务编码和页面标识
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @example
+ * ```ts
+ * openAppHelpCenter({
+ *   bizCode: 'help_center',
+ *   key: 'main_page',
+ *   success() {
+ *     console.log('跳转帮助中心成功');
+ *   },
+ *   fail(err) {
+ *     console.log('跳转失败', err);
+ *   },
+ * });
+ * ```
+ * @public
+ * @since @ray-js/ray 1.4.48
  */
 export function openAppHelpCenter(params) {
   const _ref = params || {},

package/lib/openGroupCreate/index.d.ts

@@ -1,12 +1,21 @@
 interface OpenGroupCreateParams {
+    /** 设备 ID */
     deviceId: string;
+    /** 名称 */
     name?: string;
+    /** 子功能显示类型 */
     type?: string;
+    /** 子功能分组类型 */
     optionType?: string;
+    /** 子功能来源 */
     from?: 'RN' | '小程序' | 'APP';
+    /** 排序 */
     order?: number;
+    /** 是否显示 */
     isShow?: boolean;
+    /** 接口调用成功的回调函数 */
     success?: () => void;
+    /** 接口调用失败的回调函数 */
     fail?: (err?: {
         errorMsg: string;
         errorCode: string | number;
@@ -15,15 +24,51 @@ interface OpenGroupCreateParams {
             errorMsg: string;
         };
     }) => void;
+    /** 接口调用结束的回调函数（调用成功、失败都会执行） */
     complete?: () => void;
 }
 interface OnOpenSubFunctionCallbackParams {
+    /** 回调数据 */
     data: {
+        /** 群组创建结果，true 表示创建成功 */
         groupCreateResult: boolean;
     };
+    /** 子功能标识 */
     id: 'group_create';
+    /** 是否隐藏 */
     isHide: boolean;
 }
+/**
+ * 监听创建群组结果
+ * @param callback - 创建群组结果的回调函数
+ * @example
+ * ```ts
+ * onOpenGroupCreate((res) => {
+ *   console.log('群组创建结果:', res.data.groupCreateResult);
+ * });
+ * ```
+ * @public
+ * @since @ray-js/ray 1.4.21
+ */
 export declare function onOpenGroupCreate(callback: (res: OnOpenSubFunctionCallbackParams) => void): void;
+/**
+ * 打开创建群组页面
+ * @param params - 创建群组的参数
+ * @returns 打开创建群组页面的 Promise，成功时 resolve，失败时 reject
+ * @example
+ * ```ts
+ * openGroupCreate({
+ *   deviceId: 'xxxx',
+ *   success() {
+ *     console.log('打开创建群组页面成功');
+ *   },
+ *   fail(err) {
+ *     console.log('打开创建群组页面失败', err);
+ *   },
+ * });
+ * ```
+ * @public
+ * @since @ray-js/ray 1.4.20
+ */
 export declare function openGroupCreate(params: OpenGroupCreateParams): Promise<void>;
 export {};

package/lib/openGroupCreate/index.js

@@ -1,6 +1,18 @@
 import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import _objectWithoutProperties from "@babel/runtime/helpers/esm/objectWithoutProperties";
 const _excluded = ["deviceId", "success", "fail", "complete"];
+/**
+ * 监听创建群组结果
+ * @param callback - 创建群组结果的回调函数
+ * @example
+ * ```ts
+ * onOpenGroupCreate((res) => {
+ *   console.log('群组创建结果:', res.data.groupCreateResult);
+ * });
+ * ```
+ * @public
+ * @since @ray-js/ray 1.4.21
+ */
 export function onOpenGroupCreate(callback) {
   ty.device.onSubFunctionDataChange(res => {
     if (res.id === 'group_create') {
@@ -8,6 +20,26 @@ export function onOpenGroupCreate(callback) {
     }
   });
 }
+
+/**
+ * 打开创建群组页面
+ * @param params - 创建群组的参数
+ * @returns 打开创建群组页面的 Promise，成功时 resolve，失败时 reject
+ * @example
+ * ```ts
+ * openGroupCreate({
+ *   deviceId: 'xxxx',
+ *   success() {
+ *     console.log('打开创建群组页面成功');
+ *   },
+ *   fail(err) {
+ *     console.log('打开创建群组页面失败', err);
+ *   },
+ * });
+ * ```
+ * @public
+ * @since @ray-js/ray 1.4.20
+ */
 export function openGroupCreate(params) {
   const {
       deviceId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/api",
-  "version": "1.7.70",
+  "version": "1.7.72",
   "description": "Ray universal api",
   "keywords": [
     "ray"
@@ -29,8 +29,8 @@
     "watch": "ray start --type=component"
   },
   "dependencies": {
-    "@ray-js/framework": "1.7.70",
-    "@ray-js/router": "1.7.70",
+    "@ray-js/framework": "1.7.72",
+    "@ray-js/router": "1.7.72",
     "base64-browser": "^1.0.1",
     "query-string": "^7.1.3"
   },
@@ -38,7 +38,7 @@
     "@ray-js/wechat": "^0.3.13"
   },
   "devDependencies": {
-    "@ray-js/cli": "1.7.70",
+    "@ray-js/cli": "1.7.72",
     "art-template": "^4.13.4",
     "fs-extra": "^10.1.0",
     "miniprogram-api-typings": "^3.12.3",
@@ -48,5 +48,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "gitHead": "93b0befc6a22e7c788b9af473c36f757813f310a"
+  "gitHead": "06415e2d0f0de0a3f27af53a0fece495cf4d9078"
 }