@ray-js/components 1.7.56-beta.5 → 1.7.56-beta.7

package/lib/Animated-old/types.d.ts

@@ -0,0 +1,312 @@
+import type React from 'react';
+/**
+ * 触摸事件处理器（只保留核心事件）
+ *
+ * 注：只提供最常用的三个事件（onClick, onTouchStart, onTouchEnd）
+ * 如需其他事件（如 onLongPress, onTouchMove 等），请在 Animated 的子元素上直接绑定
+ */
+export interface TouchEventHandler {
+    onClick?: (e: TouchEvent) => any;
+    onTouchStart?: (e: TouchEvent) => any;
+    onTouchEnd?: (e: TouchEvent) => any;
+}
+interface TargetType {
+    id: string;
+    offsetLeft: number;
+    offsetTop: number;
+    paths: any;
+    uid: any;
+    dataset: {
+        [key: string]: any;
+    };
+}
+export interface EventType {
+    type: string;
+    target: TargetType;
+    currentTarget: TargetType;
+    timestamp: number;
+    stopPropagation: () => void;
+    detail: any;
+}
+export type timing = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'step-start' | 'step-end';
+export type TOptions = {
+    duration?: number;
+    timingFunction?: timing;
+    delay?: number;
+    transformOrigin?: string;
+};
+/**
+ * 元素边界信息
+ */
+export interface BoundingClientRect {
+    /** 元素的 ID */
+    id: string;
+    /** dataset 数据 */
+    dataset: Record<string, any>;
+    /** 左边界坐标 */
+    left: number;
+    /** 右边界坐标 */
+    right: number;
+    /** 上边界坐标 */
+    top: number;
+    /** 下边界坐标 */
+    bottom: number;
+    /** 元素宽度 */
+    width: number;
+    /** 元素高度 */
+    height: number;
+}
+/**
+ * 元素查询字段配置
+ */
+export interface NodeFields {
+    /** 是否返回节点 id */
+    id?: boolean;
+    /** 是否返回节点 dataset */
+    dataset?: boolean;
+    /** 是否返回节点布局位置（left right top bottom） */
+    rect?: boolean;
+    /** 是否返回节点尺寸（width height） */
+    size?: boolean;
+    /** 是否返回节点的 scrollLeft scrollTop */
+    scrollOffset?: boolean;
+    /** 指定属性名列表，返回节点对应属性名的当前属性值 */
+    properties?: string[];
+    /** 指定样式名列表，返回节点对应样式名的当前值 */
+    computedStyle?: string[];
+    /** 是否返回节点对应的 Node 实例 */
+    node?: boolean;
+}
+/**
+ * Animated.View 组件的 Ref 类型（不包含 setText）
+ *
+ * @example
+ * ```tsx
+ * import { useRef } from 'react'
+ * import Animated, { type AnimatedViewRef } from '@/components/animated'
+ *
+ * const boxRef = useRef<AnimatedViewRef>(null)
+ * boxRef.current?.setStyle({ opacity: 0.5 })
+ * boxRef.current?.animate((anim) => {
+ *   anim.translateX(100).step({ duration: 300 })
+ * })
+ * ```
+ */
+export interface AnimatedViewRef {
+    /**
+     * 直接设置样式（无动画）
+     *
+     * 优势：不受 React 重渲染影响，可以在动画过程中随时调用 setState
+     * 而不用担心样式被覆盖或闪烁问题
+     *
+     * 注意：
+     * - 会清除动画数据并设置样式
+     * - 如果动画正在执行，会中断动画
+     * - 返回 Promise，可以等待样式应用完成
+     *
+     * @param style - 样式对象或 CSS 字符串
+     * @param callback - 可选的回调函数，样式应用完成后调用
+     * @returns Promise<void> - 样式应用完成后 resolve
+     *
+     * @example
+     * ```tsx
+     * // 基本使用
+     * ref.current?.setStyle({ opacity: 0.5, color: 'red' })
+     *
+     * // 等待样式应用完成
+     * await ref.current?.setStyle({ opacity: 0 })
+     *
+     * // 如果需要获取 rect，单独调用
+     * await ref.current?.setStyle({ opacity: 0 })
+     * const rect = await ref.current?.getBoundingClientRect()
+     *
+     * // 使用回调
+     * ref.current?.setStyle({ color: 'red' }, () => {
+     *   console.log('样式已应用')
+     * })
+     * ```
+     */
+    setStyle: (style: React.CSSProperties | string, callback?: () => void) => Promise<void>;
+    /**
+     * 创建动画对象
+     * 使用小程序原生动画 API，这是性能最优的动画方式
+     *
+     * @param options - 动画配置（可选）
+     * @param options.duration - 动画持续时间（毫秒），默认 400
+     * @param options.timingFunction - 缓动函数，默认 'linear'
+     * @param options.delay - 动画延迟时间（毫秒），默认 0
+     * @param options.transformOrigin - 变换原点，默认 '50% 50% 0'
+     * @returns Animation 实例，包含所有动画方法和 play() 方法
+     *
+     * @example
+     * ```tsx
+     * // 基本使用
+     * const animation = ref.current.animate()
+     * animation.translateX(100).step({ duration: 300 })
+     * await animation.play()
+     * console.log('动画完成！')
+     *
+     * // 链式调用
+     * const animation = ref.current
+     *   .animate({ transformOrigin: '50% 50%' })
+     *   .translateX(100)
+     *   .scale(1.2)
+     *   .step({ duration: 300 })
+     * await animation.play()
+     *
+     * // 多段动画
+     * const animation = ref.current.animate()
+     * animation.translateX(100).step({ duration: 300 })
+     * animation.translateY(100).step({ duration: 300 })
+     * animation.scale(1.5).step({ duration: 300 })
+     * await animation.play()
+     *
+     * // 复用动画
+     * const slideIn = ref.current.animate().translateX(100).step({ duration: 300 })
+     * await slideIn.play() // 第一次
+     * await slideIn.play() // 第二次
+     * ```
+     */
+    animate: (options?: TOptions) => IAnimation & {
+        play(): Promise<void>;
+    };
+    /**
+   * 获取元素的布局位置和尺寸信息
+   * 基于小程序 SelectorQuery.boundingClientRect API
+   *
+   * @returns Promise<BoundingClientRect | null>
+   *
+   * @example
+   * ```tsx
+   * const rect = await boxRef.current?.getBoundingClientRect()
+   * console.log(rect?.left, rect?.top, rect?.width, rect?.height)
+   *
+   * // 使用位置信息实现动画
+   * if (rect) {
+   *   const centerX = window.innerWidth / 2 - rect.left - rect.width / 2
+   *   const centerY = window.innerHeight / 2 - rect.top - rect.height / 2
+   *   boxRef.current?.animate((anim) => {
+   *     anim.translateX(centerX).translateY(centerY).scale(2).step({ duration: 300 })
+   *   })
+   * }
+   * ```
+   */
+    getBoundingClientRect: () => Promise<BoundingClientRect | null>;
+    /**
+     * 获取元素的详细信息（包括样式、属性等）
+     * 基于小程序 SelectorQuery.fields API
+     *
+     * @param fields - 查询字段配置
+     * @returns Promise<any>
+     *
+     * @example
+     * ```tsx
+     * // 获取元素的位置和计算后的样式
+     * const info = await boxRef.current?.getFields({
+     *   rect: true,
+     *   size: true,
+     *   computedStyle: ['backgroundColor', 'transform']
+     * })
+     * console.log(info?.backgroundColor, info?.transform)
+     * ```
+     */
+    getFields: (fields: NodeFields) => Promise<any>;
+    /**
+     * 获取元素的计算后样式（computed style）
+     * 这是一个便捷方法，内部调用 getFields
+     *
+     * 使用注意事项：
+     * 1. width/height 限制：通过 CSS 自动布局的元素，width/height 通常返回 'auto'
+     *    - 错误用法：用 getComputedStyle 获取实际像素尺寸
+     *    - 正确用法：使用 getBoundingClientRect() 获取实际尺寸
+     *
+     * 2. 内联样式限制：通过 React style 属性设置的样式可能无法查询
+     *    - 原因：小程序查询的是最终渲染的 CSS，不是 JS 设置的内联样式
+     *
+     * 3. 适用场景：
+     *    - 查询 transform 动画状态（动画执行中）
+     *    - 查询 opacity 等动画属性
+     *    - 查询通过 CSS 类设置的样式
+     *    - 查询元素实际尺寸（用 getBoundingClientRect）
+     *    - 查询通过 style={{ }} 设置的背景色等
+     *
+     * @param styleNames - 样式名称数组
+     * @returns Promise<Record<string, any> | null> - 返回样式对象
+     *
+     * @example
+     * ```tsx
+     * // 正确示例：查询动画相关样式
+     * const styles = await boxRef.current?.getComputedStyle([
+     *   'transform',
+     *   'opacity'
+     * ])
+     *
+     * console.log(styles?.transform)  // 'matrix(1.5, 0, 0, 1.5, 100, 50)'
+     * console.log(styles?.opacity)    // '0.8'
+     *
+     * // 根据当前 transform 决定下一步动画
+     * if (styles?.transform !== 'none') {
+     *   // 当前有 transform，恢复原位
+     *   boxRef.current?.animate((anim) => {
+     *     anim.translateX(0).translateY(0).scale(1).step({ duration: 300 })
+     *   })
+     * }
+     *
+     * // 错误示例：查询尺寸
+     * const styles = await boxRef.current?.getComputedStyle(['width', 'height'])
+     * console.log(styles?.width)  // 可能返回 'auto'，不是实际像素值
+     *
+     * // 正确做法：使用 getBoundingClientRect
+     * const rect = await boxRef.current?.getBoundingClientRect()
+     * console.log(rect?.width)  // 335 (实际像素值)
+     * ```
+     */
+    getComputedStyle: (styleNames: string[]) => Promise<Record<string, any> | null>;
+}
+/**
+ * Animated.Text 组件的 Ref 类型（包含 setText）
+ *
+ * @example
+ * ```tsx
+ * import { useRef } from 'react'
+ * import Animated, { type AnimatedTextRef } from '@/components/animated'
+ *
+ * const textRef = useRef<AnimatedTextRef>(null)
+ * textRef.current?.setText('新文本')
+ * textRef.current?.animate((anim) => {
+ *   anim.opacity(0.5).step({ duration: 300 })
+ * })
+ * ```
+ */
+export interface AnimatedTextRef extends AnimatedViewRef {
+    /**
+     * 直接设置文本内容（仅 Animated.Text 可用）
+     * 直接操作底层组件，不触发 React 重渲染
+     *
+     * @param text - 文本内容
+     *
+     * @example
+     * ```tsx
+     * <Animated.Text ref={textRef}>0</Animated.Text>
+     * // 更新文本
+     * textRef.current?.setText('100')
+     * ```
+     */
+    setText: (text: string) => void;
+}
+/**
+ * Animated 组件 Props
+ */
+export interface AnimatedProps extends TouchEventHandler {
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    id?: string;
+    /** 组件模式：'view' 为容器模式（默认），'text' 为文本模式 */
+    mode?: 'view' | 'text';
+    /** 动画开始回调 */
+    onAnimationStart?: () => void;
+    /** 动画结束回调 */
+    onAnimationEnd?: () => void;
+}
+export {};

package/lib/Animated-old/types.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -33,5 +33,5 @@ export { default as Iframe } from './Iframe';
 export { default as Modal } from './Modal';
 export { default as Video } from './Video';
 export { default as SvgRender } from './SvgRender';
-export { default as Animated } from './Animated';
-export type { AnimatedViewRef, AnimatedTextRef, AnimatedProps } from './Animated';
+export { default as Animated } from './Animated ';
+export type { AnimatedViewRef, AnimatedTextRef, AnimatedProps } from './Animated ';

package/lib/index.js

@@ -33,4 +33,4 @@ export { default as Iframe } from './Iframe';
 export { default as Modal } from './Modal';
 export { default as Video } from './Video';
 export { default as SvgRender } from './SvgRender';
-export { default as Animated } from './Animated';
+export { default as Animated } from './Animated ';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/components",
-  "version": "1.7.56-beta.5",
+  "version": "1.7.56-beta.7",
   "description": "Ray basic components",
   "keywords": [
     "ray"
@@ -29,8 +29,8 @@
   "dependencies": {
     "@ray-core/macro": "^0.4.9",
     "@ray-core/wechat": "^0.4.9",
-    "@ray-js/adapter": "1.7.56-beta.5",
-    "@ray-js/framework-shared": "1.7.56-beta.5",
+    "@ray-js/adapter": "1.7.56-beta.7",
+    "@ray-js/framework-shared": "1.7.56-beta.7",
     "ahooks": "^3.8.5",
     "clsx": "^1.2.1",
     "core-js": "^3.43.0",
@@ -40,11 +40,11 @@
     "style-to-object": "^0.3.0"
   },
   "devDependencies": {
-    "@ray-js/cli": "1.7.56-beta.5"
+    "@ray-js/cli": "1.7.56-beta.7"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "gitHead": "504d74785b7f6ed42a0e20d929a77e9df4971bf8"
+  "gitHead": "4af5e87574c24597a6da1112bc3c40bf27df713c"
 }