@ray-js/api 1.7.69 → 1.7.71

package/lib/getCustomConfig/index.thing.js

@@ -1,3 +1,65 @@
+/**
+ * 获取小程序自定义配置信息。此接口用于获取在开发者后台配置的自定义业务配置，支持多种数据类型（链接、布尔值、数字、字符串）。
+ *
+ * 自定义配置支持模板配置和实例配置的分层管理，实例配置优先于模板配置。配置修改后会自动同步到云端，小程序可以通过此接口获取最新的配置信息。
+ *
+ * @public
+ * @since 基础库 2.0.0
+ * @since @ray-js/ray 1.7.29
+ * @param options - 参数对象，包含 success / fail / complete 回调；不传时返回 Promise
+ * @returns 不传回调时返回 Promise，resolve 值为自定义配置键值对对象
+ * @error {7} API Internal processing failed
+ * @example 回调方式
+ * ```tsx
+ * import React from 'react';
+ * import { View, Button, Text, getCustomConfig } from '@ray-js/ray';
+ *
+ * export default function Demo() {
+ *   const handleGetConfig = () => {
+ *     getCustomConfig({
+ *       success(config) {
+ *         console.log('自定义配置:', config);
+ *       },
+ *       fail(err) {
+ *         console.error('获取失败:', err.errorMsg);
+ *       },
+ *     });
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <Button onClick={handleGetConfig}>获取自定义配置(回调)</Button>
+ *     </View>
+ *   );
+ * }
+ * ```
+ * @example Promise 方式
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Button, Text, getCustomConfig } from '@ray-js/ray';
+ *
+ * export default function Demo() {
+ *   const [config, setConfig] = useState('');
+ *
+ *   const handleGetConfig = async () => {
+ *     try {
+ *       const result = await getCustomConfig();
+ *       setConfig(JSON.stringify(result));
+ *       console.log('自定义配置:', result);
+ *     } catch (err) {
+ *       console.error('获取失败:', err);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <Button onClick={handleGetConfig}>获取自定义配置(Promise)</Button>
+ *       {config && <Text style={{ marginTop: 10 }}>{config}</Text>}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
 const getCustomConfig = function (options) {
   return ty.getCustomConfig(options);
 };

package/lib/getCustomConfig/index.wechat.d.ts

@@ -1,3 +1,6 @@
-import type { TGetCustomConfig } from './type';
-declare const getCustomConfig: TGetCustomConfig;
+import type { GetCustomConfigParams } from './type';
+declare const getCustomConfig: {
+    (params: GetCustomConfigParams): void;
+    (): Promise<Record<string, unknown>>;
+};
 export default getCustomConfig;

package/lib/getCustomConfig/type.d.ts

@@ -1,22 +1,33 @@
-interface GeneralCallbackResult {
+/** 自定义配置项的值类型，支持字符串、数字、布尔值 */
+export type CustomConfigValue = 
+/** 字符串 */
+string
+/** 数字 */
+ | number
+/** 布尔值 */
+ | boolean
+/** 链接(特殊字符串) */
+ | string;
+/** getCustomConfig 失败回调参数 */
+export interface GetCustomConfigError {
+    /** 错误信息 */
     errorMsg: string;
+    /** 错误码 */
     errorCode: string;
+    /** 错误扩展 */
     innerError?: {
+        /** 错误扩展码 */
         errorCode: string;
+        /** 错误扩展信息 */
         errorMsg: string;
     };
 }
-type IAnyObject = Record<string, any>;
-/**
- * 异步回调方法的通用阐述
- */
-type AsyncApiOptions<S, F extends GeneralCallbackResult = GeneralCallbackResult> = {
-    success?: (res: S) => void;
-    fail?: (res: F) => void;
-    complete?: (res: S | F) => void;
-};
-export type TGetCustomConfig<T = IAnyObject> = {
-    (options?: AsyncApiOptions<T>): void;
-    (): Promise<T>;
-};
-export {};
+/** getCustomConfig 的参数 */
+export interface GetCustomConfigParams {
+    /** 接口调用成功的回调函数，参数为各配置项的键值对 */
+    success?: (config: Record<string, CustomConfigValue>) => void;
+    /** 接口调用失败的回调函数 */
+    fail?: (err: GetCustomConfigError) => void;
+    /** 接口调用结束的回调函数（调用成功、失败都会执行） */
+    complete?: (res: Record<string, CustomConfigValue> | GetCustomConfigError) => void;
+}

package/lib/getElementById/index.thing.d.ts

@@ -1 +1,42 @@
-export default function getElementById(id: string): Promise<WechatMiniprogram.NodesRef | null>;
+import type { NodesRef } from '../getBoundingClientRect/index.thing';
+/**
+ * 获取页面节点
+ *
+ * @public
+ * @since @ray-js/ray 0.5.10
+ * @param id - 节点的 id 属性值
+ * @returns 节点引用对象，节点不存在时返回 null
+ * @example 基础用法
+ * ```tsx
+ * import React from 'react';
+ * import { View, Button, Text, getElementById } from '@ray-js/ray';
+ *
+ * export default function Demo() {
+ *   const handleGetElement = async () => {
+ *     const element = await getElementById('targetView');
+ *     console.log('节点引用:', element);
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <View
+ *         id="targetView"
+ *         style={{
+ *           height: 100,
+ *           backgroundColor: '#1890ff',
+ *           display: 'flex',
+ *           alignItems: 'center',
+ *           justifyContent: 'center',
+ *         }}
+ *       >
+ *         <Text style={{ color: '#fff' }}>目标节点</Text>
+ *       </View>
+ *       <Button style={{ marginTop: 10 }} onClick={handleGetElement}>
+ *         获取节点引用
+ *       </Button>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export default function getElementById(id: string): Promise<NodesRef | null>;

package/lib/getElementById/index.thing.js

@@ -1,3 +1,43 @@
+/**
+ * 获取页面节点
+ *
+ * @public
+ * @since @ray-js/ray 0.5.10
+ * @param id - 节点的 id 属性值
+ * @returns 节点引用对象，节点不存在时返回 null
+ * @example 基础用法
+ * ```tsx
+ * import React from 'react';
+ * import { View, Button, Text, getElementById } from '@ray-js/ray';
+ *
+ * export default function Demo() {
+ *   const handleGetElement = async () => {
+ *     const element = await getElementById('targetView');
+ *     console.log('节点引用:', element);
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <View
+ *         id="targetView"
+ *         style={{
+ *           height: 100,
+ *           backgroundColor: '#1890ff',
+ *           display: 'flex',
+ *           alignItems: 'center',
+ *           justifyContent: 'center',
+ *         }}
+ *       >
+ *         <Text style={{ color: '#fff' }}>目标节点</Text>
+ *       </View>
+ *       <Button style={{ marginTop: 10 }} onClick={handleGetElement}>
+ *         获取节点引用
+ *       </Button>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
 export default function getElementById(id) {
   return new Promise(resolve => {
     const nodeRef = ty.createSelectorQuery().select("#".concat(id));

package/lib/index.d.ts

@@ -101,4 +101,7 @@ export * from './openGroupCreate';
  * 1.4.32 openCreateScene/openEditScene/openGuideScene/openAppScan/openConfigDevice/openUniversalCreateScene
  */
 export * from './nativeRouters';
+/**
+ * @public
+ */
 export declare const canIUse: typeof ty.canIUse;

package/lib/index.js

@@ -4,7 +4,7 @@ import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import { factory } from './utils';
 export * from './constants';
 export * from './all-kits';
-import { health as healthKit } from './HealthKit-6.5.0';
+import * as healthKit from './HealthKit-6.5.0';
 import { healthCloudApi } from './cloud';
 export const health = _objectSpread(_objectSpread({}, healthCloudApi), healthKit);
 export * from './lifecycles';
@@ -53,5 +53,7 @@ export * from './openGroupCreate';
  */
 export * from './nativeRouters';
 
-// 3.15.1 新增
+/**
+ * @public
+ */
 export const canIUse = factory('canIUse');

package/lib/nativeRouters/common.d.ts

@@ -1,14 +1,22 @@
 export type ErrorMsg = {
+    /** 错误信息 */
     errorMsg: string;
+    /** 错误码 */
     errorCode: string | number;
+    /** 错误扩展 */
     innerError: {
+        /** 错误扩展码 */
         errorCode: string | number;
+        /** 错误扩展信息 */
         errorMsg: string;
     };
 };
 export type ICommon = {
+    /** 接口调用成功的回调函数 */
     success?: () => void;
+    /** 接口调用失败的回调函数 */
     fail?: (err?: ErrorMsg) => void;
+    /** 接口调用结束的回调函数（调用成功、失败都会执行） */
     complete?: () => void;
 };
 export type RecordRest = {

package/lib/nativeRouters/device.d.ts

@@ -1,24 +1,156 @@
 import { ICommon } from './common';
 type OpenSceneCreateParams = {
+    /** 设备 ID */
     devId?: string;
 } & ICommon;
+/**
+ * 跳转创建场景页面
+ * @param params - 创建场景参数
+ * @param params.devId 设备 ID
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openSceneCreate } from '@ray-js/ray';
+ *
+ * const createScene = async () => {
+ *   try {
+ *     await openSceneCreate({ devId: 'device_001' });
+ *     console.log('已跳转创建场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
 export declare function openSceneCreate(params?: OpenSceneCreateParams): Promise<void>;
-export declare const openCreateScene: typeof openSceneCreate;
+/**
+ * 跳转创建场景页面
+ * @param params - 创建场景参数
+ * @param params.devId 设备 ID
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openCreateScene } from '@ray-js/ray';
+ *
+ * const createScene = async () => {
+ *   try {
+ *     await openCreateScene({ devId: 'device_001' });
+ *     console.log('已跳转创建场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
+export declare function openCreateScene(params?: OpenSceneCreateParams): Promise<void>;
+/**
+ * 跳转创建一键执行类型的场景页面
+ * @param params - 通用参数
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.5.17
+ * @example
+ * ```typescript
+ * import { openCreateTapToRunScene } from '@ray-js/ray';
+ *
+ * const createTapToRun = async () => {
+ *   try {
+ *     await openCreateTapToRunScene();
+ *     console.log('已跳转创建一键执行场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
 export declare function openCreateTapToRunScene(params?: ICommon): Promise<void>;
 export declare function openUniversalCreateScene(params?: OpenSceneCreateParams): Promise<void>;
 type OpenSceneEdit = {
+    /** 设备 ID */
     devId?: string;
+    /** 场景 ID */
     sceneId?: string;
 } & ICommon;
+/**
+ * 跳转编辑场景页面
+ * @param params - 编辑场景参数
+ * @param params.devId 设备 ID
+ * @param params.sceneId 场景 ID
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openSceneEdit } from '@ray-js/ray';
+ *
+ * const editScene = async () => {
+ *   try {
+ *     await openSceneEdit({
+ *       devId: 'device_001',
+ *       sceneId: 'scene_001',
+ *     });
+ *     console.log('已跳转编辑场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
 export declare function openSceneEdit(params?: OpenSceneEdit): Promise<void>;
-export declare const openEditScene: typeof openSceneEdit;
+/**
+ * 跳转编辑场景页面
+ * @param params - 编辑场景参数
+ * @param params.devId 设备 ID
+ * @param params.sceneId 场景 ID
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openEditScene } from '@ray-js/ray';
+ *
+ * const editScene = async () => {
+ *   try {
+ *     await openEditScene({
+ *       devId: 'device_001',
+ *       sceneId: 'scene_001',
+ *     });
+ *     console.log('已跳转编辑场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
+export declare function openEditScene(params?: OpenSceneEdit): Promise<void>;
 type OpenGuideScene = {
+    /** 操作类型，'add' 为新增，'edit' 为编辑 */
     action?: 'add' | 'edit';
 } & ICommon;
 /**
- * 打开APP引导场景页
- * @param params { action?: 'add' | 'edit', success?: () => void, fail?: (err?: { errorMsg: string, errorCode: string | number, innerError: { errorCode: string | number, errorMsg: string } }) => void, complete?: () => void, [key: string]: string | boolean | number }
- * @returns
+ * 跳转场景引导页面
+ * @param params - 引导页参数
+ * @param params.action 操作类型，'add' 为新增，'edit' 为编辑
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openGuideScene } from '@ray-js/ray';
+ *
+ * const guideScene = async () => {
+ *   try {
+ *     await openGuideScene({ action: 'add' });
+ *     console.log('已跳转场景引导页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
  */
 export declare function openGuideScene(params?: OpenGuideScene): Promise<void>;
 type OpenConfigDevice = {

package/lib/nativeRouters/device.js

@@ -1,11 +1,74 @@
 import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import { nativeRouter } from './common';
+/**
+ * 跳转创建场景页面
+ * @param params - 创建场景参数
+ * @param params.devId 设备 ID
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openSceneCreate } from '@ray-js/ray';
+ *
+ * const createScene = async () => {
+ *   try {
+ *     await openSceneCreate({ devId: 'device_001' });
+ *     console.log('已跳转创建场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
 export function openSceneCreate(params) {
   return nativeRouter('createScene', params);
 }
-export const openCreateScene = openSceneCreate;
 
-// App 基线 5.13.0 以上开始支持
+/**
+ * 跳转创建场景页面
+ * @param params - 创建场景参数
+ * @param params.devId 设备 ID
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openCreateScene } from '@ray-js/ray';
+ *
+ * const createScene = async () => {
+ *   try {
+ *     await openCreateScene({ devId: 'device_001' });
+ *     console.log('已跳转创建场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
+export function openCreateScene(params) {
+  return nativeRouter('createScene', params);
+}
+/**
+ * 跳转创建一键执行类型的场景页面
+ * @param params - 通用参数
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.5.17
+ * @example
+ * ```typescript
+ * import { openCreateTapToRunScene } from '@ray-js/ray';
+ *
+ * const createTapToRun = async () => {
+ *   try {
+ *     await openCreateTapToRunScene();
+ *     console.log('已跳转创建一键执行场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
 export function openCreateTapToRunScene(params) {
   const p = _objectSpread({
     biz_type: 'click_execution'
@@ -18,14 +81,83 @@ export function openUniversalCreateScene(params) {
   const url = ty.getSystemInfoSync().platform === 'android' ? 'createSmartScene' : 'createScene';
   return nativeRouter(url, params);
 }
+/**
+ * 跳转编辑场景页面
+ * @param params - 编辑场景参数
+ * @param params.devId 设备 ID
+ * @param params.sceneId 场景 ID
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openSceneEdit } from '@ray-js/ray';
+ *
+ * const editScene = async () => {
+ *   try {
+ *     await openSceneEdit({
+ *       devId: 'device_001',
+ *       sceneId: 'scene_001',
+ *     });
+ *     console.log('已跳转编辑场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
 export function openSceneEdit(params) {
   return nativeRouter('editScene', params);
 }
-export const openEditScene = openSceneEdit;
+
 /**
- * 打开APP引导场景页
- * @param params { action?: 'add' | 'edit', success?: () => void, fail?: (err?: { errorMsg: string, errorCode: string | number, innerError: { errorCode: string | number, errorMsg: string } }) => void, complete?: () => void, [key: string]: string | boolean | number }
- * @returns
+ * 跳转编辑场景页面
+ * @param params - 编辑场景参数
+ * @param params.devId 设备 ID
+ * @param params.sceneId 场景 ID
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openEditScene } from '@ray-js/ray';
+ *
+ * const editScene = async () => {
+ *   try {
+ *     await openEditScene({
+ *       devId: 'device_001',
+ *       sceneId: 'scene_001',
+ *     });
+ *     console.log('已跳转编辑场景页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
+ */
+export function openEditScene(params) {
+  return nativeRouter('editScene', params);
+}
+/**
+ * 跳转场景引导页面
+ * @param params - 引导页参数
+ * @param params.action 操作类型，'add' 为新增，'edit' 为编辑
+ * @returns 跳转结果的 Promise，成功时 resolve，失败时 reject
+ * @public
+ * @since @ray-js/ray 1.4.32
+ * @example
+ * ```typescript
+ * import { openGuideScene } from '@ray-js/ray';
+ *
+ * const guideScene = async () => {
+ *   try {
+ *     await openGuideScene({ action: 'add' });
+ *     console.log('已跳转场景引导页面');
+ *   } catch (err) {
+ *     console.error('跳转失败:', err);
+ *   }
+ * };
+ * ```
  */
 export function openGuideScene(params) {
   return nativeRouter('thing_add_scene', params);

package/lib/nativeRouters/gw.d.ts

@@ -1,23 +1,73 @@
 import { ICommon } from './common';
 type GwIdParams = {
+    /** 网关 ID */
     gwId?: string;
 } & ICommon;
 /**
  * 打开 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 declare function openPresentGatewayCategroy(params?: GwIdParams): Promise<void>;
 /**
- * 打开网关面板配网子设备 - 搜索配网(新版)
- * @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 declare function openDeviceGWSubSearchConfigure(params?: GwIdParams): Promise<void>;
 /**
- * 打开网关面板配网子设备 - 配网帮助列表(新版)
- * @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 declare function openDeviceGWSubHelpList(params?: GwIdParams): Promise<void>;
 export {};