@ray-js/api 1.7.69 → 1.7.71

package/lib/cloud/timer.js

@@ -178,6 +178,23 @@ const getLastTimerPeriod = params => {
 
 /**
  * 获取天文定时列表
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 天文定时列表数组
+ * @example 基础用法
+ * ```ts
+ * import { getAstronomicalList } from '@ray-js/ray';
+ *
+ * getAstronomicalList({
+ *   bizId: 'vdevo160456552237748',
+ * }).then((response) => {
+ *   console.log('天文定时列表:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 const getAstronomicalList = params => {
   return requestCloud({
@@ -189,17 +206,32 @@ const getAstronomicalList = params => {
 
 /**
  * 添加天文定时
- * @param {string} bizId 设备 ID 或群组 ID
- * @param {number} bizType 0:设备; 1:设备群组
- * @param {string} loops 周期
- * @param {any} dps dp 点，json 格式
- * @param {number} astronomicalType 天文类型， 0:日出; 1:日落
- * @param {string} timezone 时区
- * @param {string} date 日期 yyyyMMdd
- * @param {string} time 偏移时间，“HH:mm” 24 进制
- * @param {number} offsetType 偏移类型，-1 : 向前; 0 正常; 1 : 向后
- * @param {number} lat 纬度
- * @param {number} lon 经度
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 新添加天文定时的 ID
+ * @example 基础用法
+ * ```ts
+ * import { addAstronomical } from '@ray-js/ray';
+ *
+ * addAstronomical({
+ *   astronomicalType: 1,
+ *   bizId: 'vdevo160456552237748',
+ *   bizType: 0,
+ *   dps: { 1: true },
+ *   lat: 30.300694,
+ *   lon: 120.068634,
+ *   loops: '1111111',
+ *   offsetType: -1,
+ *   time: '00:04',
+ *   timezone: '+08:00',
+ * }).then((response) => {
+ *   console.log('新增天文定时 ID:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 const addAstronomical = params => {
   return requestCloud({
@@ -211,17 +243,33 @@ const addAstronomical = params => {
 
 /**
  * 修改天文定时
- * @param {string} bizId 设备 ID 或群组 ID
- * @param {number} bizType 0:设备; 1:设备群组
- * @param {string} loops 周期
- * @param {any} dps dp 点，json 格式
- * @param {number} astronomicalType 天文类型， 0:日出; 1:日落
- * @param {string} timezone 时区
- * @param {string} date 日期 yyyyMMdd
- * @param {string} time 偏移时间，“HH:mm” 24 进制
- * @param {number} offsetType 偏移类型，-1 : 向前; 0 正常; 1 : 向后
- * @param {number} lat 纬度
- * @param {number} lon 经度
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 是否成功修改天文定时
+ * @example 基础用法
+ * ```ts
+ * import { updateAstronomical } from '@ray-js/ray';
+ *
+ * updateAstronomical({
+ *   id: 8642566,
+ *   astronomicalType: 1,
+ *   bizId: 'vdevo160456552237748',
+ *   bizType: 0,
+ *   dps: { 1: true },
+ *   lat: 30.300694,
+ *   lon: 120.068634,
+ *   loops: '1111111',
+ *   offsetType: -1,
+ *   time: '00:04',
+ *   timezone: '+08:00',
+ * }).then((response) => {
+ *   console.log('修改结果:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 const updateAstronomical = params => {
   return requestCloud({
@@ -232,9 +280,25 @@ const updateAstronomical = params => {
 };
 
 /**
- * 修改天文定时使能
- * @param {string} id 定时任务id
- * @param {number} status 0:关闭；1开启
+ * 修改天文定时使能状态
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 是否成功修改状态
+ * @example 基础用法
+ * ```ts
+ * import { updateAstronomicalStatus } from '@ray-js/ray';
+ *
+ * updateAstronomicalStatus({
+ *   id: '8642566',
+ *   status: 0,
+ * }).then((response) => {
+ *   console.log('修改状态结果:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 const updateAstronomicalStatus = params => {
   return requestCloud({
@@ -246,7 +310,21 @@ const updateAstronomicalStatus = params => {
 
 /**
  * 删除天文定时
- * @param {string} id 定时任务 id
+ *
+ * @public
+ * @since @ray-js/ray 1.5.2
+ * @param params - 请求参数
+ * @returns 是否成功删除天文定时
+ * @example 基础用法
+ * ```ts
+ * import { removeAstronomical } from '@ray-js/ray';
+ *
+ * removeAstronomical({ id: '8642566' }).then((response) => {
+ *   console.log('删除结果:', response);
+ * }).catch((err) => {
+ *   console.error(err);
+ * });
+ * ```
  */
 const removeAstronomical = params => {
   return requestCloud({

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

@@ -1 +1,47 @@
-export default function (): any;
+interface AppInstance {
+    /** 获取应用全局数据 */
+    getData: () => Record<string, unknown>;
+    /** 设置应用全局数据 */
+    setData: (data: Record<string, unknown>) => void;
+    /** 开发者自定义的属性和方法 */
+    [key: string]: any;
+}
+/**
+ * 获取应用唯一 App 实例，实例对象为 `src/App.tsx`
+ *
+ * @public
+ * @since @ray-js/ray 0.5.10
+ * @returns App 实例对象
+ * @example 读写全局数据
+ * ```tsx
+ * import React from 'react';
+ * import { View, Button, getApp } from '@ray-js/ray';
+ *
+ * export default function Demo() {
+ *   const app = getApp();
+ *
+ *   const handleGetGlobalData = () => {
+ *     const globalData = app.getData();
+ *     console.log('globalData:', globalData);
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <Button onClick={handleGetGlobalData}>
+ *         获取全局数据
+ *       </Button>
+ *       <Button
+ *         style={{ marginTop: 10 }}
+ *         onClick={() => {
+ *           app.setData({ theme: 'dark' });
+ *         }}
+ *       >
+ *         修改全局数据
+ *       </Button>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export default function getApp(): AppInstance;
+export {};

package/lib/getApp/index.thing.js

@@ -1,3 +1,41 @@
-export default function () {
-  return getApp();
+const _getApp = getApp;
+/**
+ * 获取应用唯一 App 实例，实例对象为 `src/App.tsx`
+ *
+ * @public
+ * @since @ray-js/ray 0.5.10
+ * @returns App 实例对象
+ * @example 读写全局数据
+ * ```tsx
+ * import React from 'react';
+ * import { View, Button, getApp } from '@ray-js/ray';
+ *
+ * export default function Demo() {
+ *   const app = getApp();
+ *
+ *   const handleGetGlobalData = () => {
+ *     const globalData = app.getData();
+ *     console.log('globalData:', globalData);
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <Button onClick={handleGetGlobalData}>
+ *         获取全局数据
+ *       </Button>
+ *       <Button
+ *         style={{ marginTop: 10 }}
+ *         onClick={() => {
+ *           app.setData({ theme: 'dark' });
+ *         }}
+ *       >
+ *         修改全局数据
+ *       </Button>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export default function getApp() {
+  return _getApp();
 }

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

@@ -1,9 +1,109 @@
+/** 节点布局信息，由 boundingClientRect 回调返回 */
+export interface BoundingClientRectResult {
+    /** 节点 id */
+    id: string;
+    /** 节点 dataset */
+    dataset: Record<string, unknown>;
+    /** 左边界坐标 */
+    left: number;
+    /** 右边界坐标 */
+    right: number;
+    /** 上边界坐标 */
+    top: number;
+    /** 下边界坐标 */
+    bottom: number;
+    /** 节点宽度 */
+    width: number;
+    /** 节点高度 */
+    height: number;
+}
+/** 节点滚动位置信息，由 scrollOffset 回调返回 */
+export interface ScrollOffsetResult {
+    /** 节点 id */
+    id: string;
+    /** 节点 dataset */
+    dataset: Record<string, unknown>;
+    /** 横向滚动位置 */
+    scrollLeft: number;
+    /** 纵向滚动位置 */
+    scrollTop: number;
+}
+/** SelectorQuery 查询链，支持 exec 执行 */
+export interface SelectorQueryChain {
+    /** 执行查询 */
+    exec(callback?: (results: unknown[]) => void): void;
+}
+/** 节点引用对象，通过 ty.createSelectorQuery().select() 获取 */
+export interface NodesRef {
+    /** 获取节点布局位置（left, right, top, bottom, width, height） */
+    boundingClientRect(callback?: (result: BoundingClientRectResult) => void): SelectorQueryChain;
+    /** 获取节点滚动位置（scrollLeft, scrollTop） */
+    scrollOffset(callback?: (result: ScrollOffsetResult) => void): SelectorQueryChain;
+    /** 获取节点指定字段信息 */
+    fields(fields: Record<string, boolean>, callback?: (result: Record<string, unknown>) => void): SelectorQueryChain;
+}
+/** 节点坐标信息 */
 export interface Rect {
+    /** 节点右边界坐标 */
     right: number;
+    /** 节点左边界坐标 */
     left: number;
+    /** 节点上边界坐标 */
     top: number;
+    /** 节点下边界坐标 */
     bottom: number;
+    /** 节点宽度 */
     width: number;
+    /** 节点高度 */
     height: number;
 }
-export default function getBoundingClientRect(ref: WechatMiniprogram.NodesRef): Promise<Rect | null>;
+/**
+ * 获取节点的坐标信息
+ *
+ * @public
+ * @since @ray-js/ray 0.5.10
+ * @param ref - 通过 getElementById 获取的节点引用
+ * @returns 包含节点坐标和尺寸信息的 Rect 对象，节点不存在时返回 null
+ * @example 基础用法
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Button, Text, getBoundingClientRect, getElementById } from '@ray-js/ray';
+ *
+ * export default function Demo() {
+ *   const [info, setInfo] = useState('');
+ *
+ *   const handleGetRect = async () => {
+ *     const element = await getElementById('targetBox');
+ *     if (element) {
+ *       const rect = await getBoundingClientRect(element);
+ *       if (rect) {
+ *         setInfo(`宽:${rect.width} 高:${rect.height} 左:${rect.left} 上:${rect.top}`);
+ *       }
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <View
+ *         id="targetBox"
+ *         style={{
+ *           width: 200,
+ *           height: 100,
+ *           backgroundColor: '#1890ff',
+ *           display: 'flex',
+ *           alignItems: 'center',
+ *           justifyContent: 'center',
+ *         }}
+ *       >
+ *         <Text style={{ color: '#fff' }}>目标区域</Text>
+ *       </View>
+ *       <Button style={{ marginTop: 10 }} onClick={handleGetRect}>
+ *         获取坐标信息
+ *       </Button>
+ *       {info && <Text style={{ marginTop: 10 }}>{info}</Text>}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export default function getBoundingClientRect(ref: NodesRef): Promise<Rect | null>;

package/lib/getBoundingClientRect/index.thing.js

@@ -1,4 +1,63 @@
 import "core-js/modules/es.regexp.exec.js";
+/** 节点布局信息，由 boundingClientRect 回调返回 */
+
+/** 节点滚动位置信息，由 scrollOffset 回调返回 */
+
+/** SelectorQuery 查询链，支持 exec 执行 */
+
+/** 节点引用对象，通过 ty.createSelectorQuery().select() 获取 */
+
+/** 节点坐标信息 */
+
+/**
+ * 获取节点的坐标信息
+ *
+ * @public
+ * @since @ray-js/ray 0.5.10
+ * @param ref - 通过 getElementById 获取的节点引用
+ * @returns 包含节点坐标和尺寸信息的 Rect 对象，节点不存在时返回 null
+ * @example 基础用法
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Button, Text, getBoundingClientRect, getElementById } from '@ray-js/ray';
+ *
+ * export default function Demo() {
+ *   const [info, setInfo] = useState('');
+ *
+ *   const handleGetRect = async () => {
+ *     const element = await getElementById('targetBox');
+ *     if (element) {
+ *       const rect = await getBoundingClientRect(element);
+ *       if (rect) {
+ *         setInfo(`宽:${rect.width} 高:${rect.height} 左:${rect.left} 上:${rect.top}`);
+ *       }
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <View
+ *         id="targetBox"
+ *         style={{
+ *           width: 200,
+ *           height: 100,
+ *           backgroundColor: '#1890ff',
+ *           display: 'flex',
+ *           alignItems: 'center',
+ *           justifyContent: 'center',
+ *         }}
+ *       >
+ *         <Text style={{ color: '#fff' }}>目标区域</Text>
+ *       </View>
+ *       <Button style={{ marginTop: 10 }} onClick={handleGetRect}>
+ *         获取坐标信息
+ *       </Button>
+ *       {info && <Text style={{ marginTop: 10 }}>{info}</Text>}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
 export default function getBoundingClientRect(ref) {
   return new Promise(resolve => {
     ref.boundingClientRect(rect => {

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

@@ -1,21 +1,46 @@
-interface PageInstance {
+/** 页面实例对象 */
+export interface PageInstance {
+    /** 页面唯一标识 */
+    pageId: string;
+    /** 页面路径 */
     route: string;
+    /** 页面参数对象（跳转时传递的 query 参数） */
+    options?: Record<string, unknown>;
+    /** 页面数据对象 */
+    data?: Record<string, unknown>;
     [key: string]: any;
 }
 /**
- * getCurrentPages(): PageObject[]获取当前页面栈。数组中第一个元素为首页，最后一个元素为当前页面。
- * 注意事项
+ * 获取当前页面栈。返回一个数组，数组中的元素为页面栈中的页面对象，数组第一个元素为首页，最后一个元素为当前页面。
+ *
+ * @public
+ * @since @ray-js/ray 0.2.0
+ * @returns 页面栈数组，每个元素为 PageInstance 对象
+ * @remarks
  * 1. 不要尝试修改页面栈，会导致路由以及页面状态错误。
- * 2. 不要在 App.onLaunch 的时候调用 getCurrentPages()，此时 page 还没有生成。
- * @example
- * // page/index.js
- * Page({
- *   onLoad() {
- *     const pageInsts = getCurrentPages();
- *     const currentPagePath = pageInsts[pageInsts.length - 1].route;
- *     consoe.log('currentPagePath ===> ', currentPagePath);
- *   },
- * });
+ * 2. 不要在 App.onLaunch 的时候调用 getCurrentPages()，此时 page 还没有生成。
+ * @example 基础用法
+ * ```tsx
+ * import React from 'react';
+ * import { View, Button, getCurrentPages } from '@ray-js/ray';
+ *
+ * export default function Home() {
+ *   const handleGetPages = () => {
+ *     const pages = getCurrentPages();
+ *     console.log('当前页面栈长度:', pages.length);
+ *     console.log('当前页面:', pages[pages.length - 1]);
+ *
+ *     pages.forEach((page, index) => {
+ *       console.log(`页面 ${index}:`, page.route);
+ *     });
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <Button onClick={handleGetPages}>获取页面栈</Button>
+ *     </View>
+ *   );
+ * }
+ * ```
  */
-export default function (): PageInstance[];
-export {};
+export default function getCurrentPages(): PageInstance[];

package/lib/getCurrentPages/index.thing.js

@@ -1,20 +1,41 @@
+/** 页面实例对象 */
+
+const _getCurrentPages = getCurrentPages;
+
 /**
- * getCurrentPages(): PageObject[]获取当前页面栈。数组中第一个元素为首页，最后一个元素为当前页面。
- * 注意事项
+ * 获取当前页面栈。返回一个数组，数组中的元素为页面栈中的页面对象，数组第一个元素为首页，最后一个元素为当前页面。
+ *
+ * @public
+ * @since @ray-js/ray 0.2.0
+ * @returns 页面栈数组，每个元素为 PageInstance 对象
+ * @remarks
  * 1. 不要尝试修改页面栈，会导致路由以及页面状态错误。
- * 2. 不要在 App.onLaunch 的时候调用 getCurrentPages()，此时 page 还没有生成。
- * @example
- * // page/index.js
- * Page({
- *   onLoad() {
- *     const pageInsts = getCurrentPages();
- *     const currentPagePath = pageInsts[pageInsts.length - 1].route;
- *     consoe.log('currentPagePath ===> ', currentPagePath);
- *   },
- * });
+ * 2. 不要在 App.onLaunch 的时候调用 getCurrentPages()，此时 page 还没有生成。
+ * @example 基础用法
+ * ```tsx
+ * import React from 'react';
+ * import { View, Button, getCurrentPages } from '@ray-js/ray';
+ *
+ * export default function Home() {
+ *   const handleGetPages = () => {
+ *     const pages = getCurrentPages();
+ *     console.log('当前页面栈长度:', pages.length);
+ *     console.log('当前页面:', pages[pages.length - 1]);
+ *
+ *     pages.forEach((page, index) => {
+ *       console.log(`页面 ${index}:`, page.route);
+ *     });
+ *   };
+ *
+ *   return (
+ *     <View style={{ padding: 20 }}>
+ *       <Button onClick={handleGetPages}>获取页面栈</Button>
+ *     </View>
+ *   );
+ * }
+ * ```
  */
-
-export default function () {
+export default function getCurrentPages() {
   // @ts-ignore
-  return getCurrentPages();
+  return _getCurrentPages();
 }

package/lib/getCustomConfig/index.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/index.thing.d.ts

@@ -1,3 +1,69 @@
-import type { TGetCustomConfig } from './type';
-declare const getCustomConfig: TGetCustomConfig;
+import type { CustomConfigValue, GetCustomConfigParams } from './type';
+interface GetCustomConfig {
+    (options: GetCustomConfigParams): void;
+    (): Promise<Record<string, CustomConfigValue>>;
+}
+/**
+ * 获取小程序自定义配置信息。此接口用于获取在开发者后台配置的自定义业务配置，支持多种数据类型（链接、布尔值、数字、字符串）。
+ *
+ * 自定义配置支持模板配置和实例配置的分层管理，实例配置优先于模板配置。配置修改后会自动同步到云端，小程序可以通过此接口获取最新的配置信息。
+ *
+ * @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>
+ *   );
+ * }
+ * ```
+ */
+declare const getCustomConfig: GetCustomConfig;
 export default getCustomConfig;