@ray-js/components 1.7.55 → 1.7.56-beta.1

package/lib/Animated/animation.d.ts

@@ -0,0 +1,47 @@
+interface IAnimation {
+  // transform
+  translate(x?: number, y?: number): this
+  translateX(x?: number): this
+  translateY(y?: number): this
+  translateZ(z?: number): this
+
+  rotate(angle: number): this
+  rotateX(angle: number): this
+  rotateY(angle: number): this
+  rotateZ(angle: number): this
+  rotate3d(x: number, y: number, z: number, angle: number): this
+
+  scale(x?: number, y?: number): this
+  scaleX(x?: number): this
+  scaleY(y?: number): this
+  scaleZ(z?: number): this
+  scale3d(x?: number, y?: number, z?: number): this
+
+  skew(x?: number, y?: number): this
+  skewX(x?: number): this
+  skewY(y?: number): this
+
+  matrix(...args: number[]): this
+  matrix3d(...args: number[]): this
+
+  // style
+  opacity(opacity: number): this
+  width(value: number | string): this
+  height(value: number | string): this
+  top(value: number | string): this
+  left(value: number | string): this
+  right(value: number | string): this
+  bottom(value: number | string): this
+  backgroundColor(value: string): this
+
+  // step / export
+  step(
+    options?: Partial<{
+      transformOrigin: string
+      duration: number
+      timingFunction: string
+      delay: number
+    }>
+  ): this
+  export(): { actions: any[] }
+}

package/lib/Animated/index.js

@@ -0,0 +1,295 @@
+import _extends from "@babel/runtime/helpers/esm/extends";
+import _objectWithoutProperties from "@babel/runtime/helpers/esm/objectWithoutProperties";
+const _excluded = ["finish"];
+import "core-js/modules/es.regexp.exec.js";
+import "core-js/modules/es.string.replace.js";
+import "core-js/modules/esnext.iterator.constructor.js";
+import "core-js/modules/esnext.iterator.for-each.js";
+import "core-js/modules/esnext.iterator.map.js";
+import "core-js/modules/web.dom-collections.iterator.js";
+/**
+ * Animated - 纯净底层动画组件
+ *
+ * 只提供三个核心方法：
+ * - setProperty(property, value): 设置动画属性
+ * - setStyle(style): 设置样式
+ * - setText(text): 设置文本内容
+ *
+ * 可以配合任何动画库使用（GSAP、Anime.js、Framer Motion 等）
+ */
+import React, { forwardRef, useImperativeHandle, useRef, useMemo, useCallback } from 'react';
+import TyAnimatedComponent from './native/ty-animated';
+
+// 小程序 API 声明
+
+/**
+ * 样式对象转 CSS 字符串
+ */
+function styleToString(style) {
+  return Object.entries(style).map(_ref => {
+    let [key, value] = _ref;
+    const cssKey = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+    return "".concat(cssKey, ":").concat(value);
+  }).join(';');
+}
+
+/**
+ * 基础 Animated 组件
+ */
+const AnimatedBase = /*#__PURE__*/forwardRef((props, ref) => {
+  const {
+    children,
+    className,
+    style,
+    id,
+    mode = 'view',
+    onAnimationStart,
+    onAnimationEnd,
+    // 核心触摸事件（只保留最常用的三个）
+    onClick,
+    onTouchStart,
+    onTouchEnd
+  } = props;
+  const callbackRef = useRef(onAnimationEnd);
+  const componentIdRef = useRef(id || "animated-".concat(Math.random().toString(36).slice(2, 11)));
+
+  // 提取文本内容（当 mode='text' 时）
+  const textContent = useMemo(() => {
+    if (mode !== 'text' || !children) return undefined;
+    if (typeof children === 'string' || typeof children === 'number') {
+      return String(children);
+    }
+    return undefined;
+  }, [mode, children]);
+  useImperativeHandle(ref, () => {
+    /**
+     * 获取 DOM 实例
+     */
+    const getDomInstance = () => {
+      try {
+        var _getCurrentPages;
+        const pages = (_getCurrentPages = getCurrentPages) === null || _getCurrentPages === void 0 ? void 0 : _getCurrentPages();
+        if (!pages || pages.length === 0) return null;
+        const currentPage = pages[pages.length - 1];
+        if (!(currentPage !== null && currentPage !== void 0 && currentPage.selectComponent)) return null;
+        return currentPage.selectComponent("#".concat(componentIdRef.current));
+      } catch (error) {
+        console.error('[Animated] 获取组件实例失败:', error);
+        return null;
+      }
+    };
+    return {
+      /**
+       * 设置样式（直通通道）
+       * 用途：设置静态样式，绕过 React/Ray 层，提升性能
+       * @example
+       * ref.current.setStyle({ color: 'red', fontSize: '16px', border: '1px solid #ccc' })
+       */
+      setStyle(styleValue) {
+        var _inst$setCustomStyle;
+        const inst = getDomInstance();
+        if (!inst) return;
+
+        // 防止传入 undefined 或空值
+        if (styleValue === undefined || styleValue === null) return;
+        const styleString = typeof styleValue === 'string' ? styleValue : styleToString(styleValue);
+        if (!styleString) return;
+        (_inst$setCustomStyle = inst.setCustomStyle) === null || _inst$setCustomStyle === void 0 || _inst$setCustomStyle.call(inst, styleString);
+      },
+      /**
+       * 设置文本内容（仅 mode='text' 时可用）
+       * 不触发 React 重渲染
+       */
+      setText(text) {
+        var _inst$__applyText;
+        // 运行时检查：只有 Text 组件才能调用 setText
+        if (mode !== 'text') {
+          console.error('[Animated] setText 只能在 Animated.Text 组件上使用');
+          return;
+        }
+        const inst = getDomInstance();
+        if (!inst) {
+          console.warn('[Animated] setText: 无法获取组件实例');
+          return;
+        }
+        (_inst$__applyText = inst.__applyText) === null || _inst$__applyText === void 0 || _inst$__applyText.call(inst, text);
+      },
+      /**
+       * 使用小程序原生动画 API
+       * 这是性能最优的动画方式
+       *
+       * @example
+       * ref.current?.animate((anim) => {
+       *   anim.translateX(100).scale(1.2).step({ duration: 300 })
+       * }, { transformOrigin: 'center center' })
+       */
+      animate(callback, options) {
+        var _inst$__apply;
+        const inst = getDomInstance();
+        if (!inst) {
+          console.warn('[Animated] animate: 无法获取组件实例');
+          return;
+        }
+        const _ref2 = options || {},
+          {
+            finish
+          } = _ref2,
+          option = _objectWithoutProperties(_ref2, _excluded);
+        if (finish && typeof finish === 'function') {
+          callbackRef.current = event => {
+            finish(event);
+            callbackRef.current = null;
+          };
+        }
+        (_inst$__apply = inst.__apply) === null || _inst$__apply === void 0 || _inst$__apply.call(inst, callback, option);
+      },
+      /**
+       * 获取元素的布局位置和尺寸信息
+       * 基于小程序 SelectorQuery.boundingClientRect API
+       */
+      getBoundingClientRect() {
+        return new Promise(resolve => {
+          try {
+            // 检查小程序 API 是否存在
+            if (typeof ty === 'undefined' || !ty.createSelectorQuery) {
+              console.error('[Animated] getBoundingClientRect: ty.createSelectorQuery 不存在');
+              resolve(null);
+              return;
+            }
+            const query = ty.createSelectorQuery();
+            query.select("#".concat(componentIdRef.current)).boundingClientRect(rect => {
+              resolve(rect || null);
+            }).exec();
+          } catch (error) {
+            console.error('[Animated] getBoundingClientRect 执行失败:', error);
+            resolve(null);
+          }
+        });
+      },
+      /**
+       * 获取元素的详细信息（包括样式、属性等）
+       * 基于小程序 SelectorQuery.fields API
+       */
+      getFields(fields) {
+        return new Promise(resolve => {
+          try {
+            // 检查小程序 API 是否存在
+            if (typeof ty === 'undefined' || !ty.createSelectorQuery) {
+              console.error('[Animated] getFields: ty.createSelectorQuery 不存在');
+              resolve(null);
+              return;
+            }
+            const query = ty.createSelectorQuery();
+            query.select("#".concat(componentIdRef.current)).fields(fields, res => {
+              resolve(res || null);
+            }).exec();
+          } catch (error) {
+            console.error('[Animated] getFields 执行失败:', error);
+            resolve(null);
+          }
+        });
+      },
+      /**
+       * 获取元素的计算后样式
+       * 便捷方法，专门用于查询样式
+       */
+      getComputedStyle(styleNames) {
+        return new Promise(resolve => {
+          try {
+            // 检查小程序 API 是否存在
+            if (typeof ty === 'undefined' || !ty.createSelectorQuery) {
+              console.error('[Animated] getComputedStyle: ty.createSelectorQuery 不存在');
+              resolve(null);
+              return;
+            }
+            const query = ty.createSelectorQuery();
+            query.select("#".concat(componentIdRef.current)).fields({
+              computedStyle: styleNames
+            }, res => {
+              if (!res) {
+                resolve(null);
+                return;
+              }
+
+              // 提取样式信息，过滤掉非样式字段
+              const styles = {};
+              styleNames.forEach(styleName => {
+                if (res[styleName] !== undefined) {
+                  styles[styleName] = res[styleName];
+                }
+              });
+              resolve(Object.keys(styles).length > 0 ? styles : null);
+            }).exec();
+          } catch (error) {
+            console.error('[Animated] getComputedStyle 执行失败:', error);
+            resolve(null);
+          }
+        });
+      }
+    };
+  }, []);
+
+  // 处理 customStyle，避免传入 undefined
+  const customStyleValue = useMemo(() => {
+    if (!style) return undefined;
+    return typeof style === 'object' ? styleToString(style) : style;
+  }, [style]);
+  const handleAnimationEnd = useCallback(event => {
+    if (callbackRef.current) {
+      callbackRef.current(event);
+      callbackRef.current = null;
+    }
+    if (onAnimationEnd) {
+      onAnimationEnd();
+    }
+  }, [onAnimationEnd, callbackRef.current]);
+  const eventBindings = {};
+  if (onClick) eventBindings['bind:click'] = onClick;
+  if (onTouchStart) eventBindings['bind:touchstart'] = onTouchStart;
+  if (onTouchEnd) eventBindings['bind:touchend'] = onTouchEnd;
+  if (onAnimationStart) eventBindings['bind:animationbegin'] = onAnimationStart;
+  eventBindings['bind:animationfinish'] = handleAnimationEnd;
+  return (
+    /*#__PURE__*/
+    // @ts-ignore - 小程序自定义组件
+    React.createElement(TyAnimatedComponent, _extends({
+      id: componentIdRef.current,
+      __mode: mode,
+      customClass: className
+    }, customStyleValue ? {
+      customStyle: customStyleValue
+    } : {}, mode === 'text' && textContent !== undefined ? {
+      __text: textContent
+    } : {}, eventBindings), mode === 'view' ? children : null)
+  );
+});
+AnimatedBase.displayName = 'AnimatedBase';
+
+/**
+ * Animated.View 组件（不包含 setText）
+ */
+const AnimatedView = /*#__PURE__*/forwardRef((props, ref) => /*#__PURE__*/React.createElement(AnimatedBase, _extends({}, props, {
+  mode: "view",
+  ref: ref
+})));
+AnimatedView.displayName = 'Animated.View';
+
+/**
+ * Animated.Text 组件（包含 setText）
+ */
+const AnimatedText = /*#__PURE__*/forwardRef((props, ref) => /*#__PURE__*/React.createElement(AnimatedBase, _extends({}, props, {
+  mode: "text",
+  ref: ref
+})));
+AnimatedText.displayName = 'Animated.Text';
+
+/**
+ * 默认导出
+ */
+const Animated = {
+  View: AnimatedView,
+  Text: AnimatedText
+};
+export default Animated;
+
+// 导出类型

package/lib/Animated/native/ty-animated/index.d.ts

@@ -0,0 +1,5 @@
+import * as React from 'react';
+declare const TyAnimated: React.ComponentType<any>;
+export default TyAnimated;
+
+

package/lib/Animated/native/ty-animated/index.js

@@ -0,0 +1,170 @@
+// @ts-nocheck
+/**
+ * TyAnimated - 高性能动画组件（小程序原生层）
+ */
+
+// 小程序原生组件注册
+Component({
+  properties: {
+    __mode: {
+      type: String,
+      value: 'view'
+    },
+    __text: {
+      type: String,
+      value: ''
+    },
+    __style: {
+      type: String,
+      value: ''
+    },
+    __className: {
+      type: String,
+      value: ''
+    },
+    // 兼容 FastView 接口
+    customStyle: {
+      type: String,
+      value: '',
+      observer: function (v) {
+        this.setData({
+          __style: v
+        });
+      }
+    },
+    customClass: {
+      type: String,
+      value: '',
+      observer: function (v) {
+        this.setData({
+          __className: v
+        });
+      }
+    },
+    onAnimationStart: {
+      type: null,
+      value: null
+    },
+    // 动画结束回调函数
+    onAnimationEnd: {
+      type: null,
+      value: null
+    }
+  },
+  // 定义外部事件
+  externalClasses: [],
+  data: {
+    __text: '',
+    __style: '',
+    __className: '',
+    __animData: null // 动画数据
+  },
+  lifetimes: {
+    attached() {
+      // 组件初始化
+    },
+    detached() {
+      // 清理工作
+    }
+  },
+  methods: {
+    /**
+     * 事件处理器
+     */
+    __handleTiggerEvent(eventName, e) {
+      // 触发自定义事件，让外部可以监听
+      this.triggerEvent(eventName, e, {
+        // bubbles: true,
+        composed: true
+      });
+    },
+    /**
+     * 创建 IntersectionObserver
+     */
+    createIntersectionObserver(options) {
+      try {
+        // @ts-ignore
+        if (typeof ty !== 'undefined' && ty.createIntersectionObserver) {
+          return ty.createIntersectionObserver(this, options);
+        }
+      } catch (e) {
+        console.error('createIntersectionObserver error:', e);
+      }
+      return null;
+    },
+    /**
+     * 获取小程序的 createAnimation 方法
+     */
+    _getCreateAnimation() {
+      try {
+        // @ts-ignore
+        if (typeof ty !== 'undefined' && ty.createAnimation) {
+          return ty.createAnimation;
+        }
+      } catch (e) {
+        // ignore
+      }
+      return null;
+    },
+    setCustomStyle(value) {
+      // 防止传入 undefined 或 null 导致小程序报错
+      if (value === undefined || value === null) {
+        console.warn('[TyAnimatedComponent] setCustomStyle: value is undefined or null, ignored');
+        return;
+      }
+      this.setData({
+        __style: value,
+        customStyle: value
+      });
+    },
+    /**
+     * 设置文本内容（__mode='text' 时使用）
+     */
+    __applyText(text) {
+      if (typeof text === 'string') {
+        this.setData({
+          __text: text
+        });
+      }
+    },
+    /**
+     * 核心方法：直接应用 Animation 对象
+     * @param {Function} fn - 接收 Animation 实例的回调函数
+     * @param {Object} options - 动画选项，包括 transformOrigin
+     *
+     * 使用示例：
+     * comp.__apply((anim) => {
+     *   anim.opacity(0.5).scale(0.8).step();
+     *   return anim.export();
+     * }, { transformOrigin: 'top left' });
+     */
+    __apply(fn) {
+      let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      const createAnimation = this._getCreateAnimation();
+      if (!createAnimation) {
+        return;
+      }
+      const anim = createAnimation(options);
+
+      // 执行用户的动画配置
+      const exported = fn(anim);
+
+      // 应用动画数据
+      const animData = exported || anim.export();
+      this.setData({
+        __animData: animData
+      });
+    },
+    // 核心触摸事件处理（只保留最常用的）
+    __onClick(e) {
+      this.__handleTiggerEvent('click', e);
+    },
+    __onTouchStart(e) {
+      this.__handleTiggerEvent('touchstart', e);
+    },
+    __onTouchEnd(e) {
+      this.__handleTiggerEvent('touchend', e);
+    }
+  }
+});
+export default 'ty-animated-component';

package/lib/Animated/native/ty-animated/index.json

@@ -0,0 +1,4 @@
+{
+  "component": true,
+  "usingComponents": {}
+}

package/lib/Animated/native/ty-animated/index.tyml

@@ -0,0 +1,26 @@
+<block>
+  <view
+    wx:if="{{__mode==='view'}}"
+    id="root"
+    class="container {{__className}} {{customClass}}"
+    style="{{__style}};{{customStyle}}"
+    animation="{{__animData}}"
+    bindtap="__onClick"
+    bindtouchstart="__onTouchStart"
+    bindtouchend="__onTouchEnd"
+  >
+    <slot></slot>
+  </view>
+  <text
+    wx:else
+    id="rootText"
+    class="container {{__className}} {{customClass}}"
+    style="{{__style}};{{customStyle}}"
+    animation="{{__animData}}"
+    bindtap="__onClick"
+    bindtouchstart="__onTouchStart"
+    bindtouchend="__onTouchEnd"
+  >{{__text}}</text>
+</block>
+
+

package/lib/Animated/native/ty-animated/index.tyss

@@ -0,0 +1,3 @@
+.container { display: block; }
+
+

package/lib/Animated/types.d.ts

@@ -0,0 +1,277 @@
+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 {
+    /**
+     * 直接设置样式（无动画）
+     *
+     * @param style - 样式对象或 CSS 字符串
+     *
+     * @example
+     * ```tsx
+     * ref.current?.setStyle({ opacity: 0.5, color: 'red' })
+     * ref.current?.setStyle('transform: translateX(100px);')
+     * ```
+     */
+    setStyle: (style: React.CSSProperties | string) => void;
+    /**
+     * 使用小程序原生动画 API
+     * 这是性能最优的动画方式
+     *
+     * @param callback - 动画配置回调，接收小程序动画对象
+     * @param options - 动画选项
+     *
+     * @example
+     * ```tsx
+     * // 单个动画
+     * ref.current?.animate((anim) => {
+     *   anim.translateX(100).scale(1.2).step({ duration: 300, timingFunction: 'ease-out' })
+     * })
+     *
+     * // 序列动画
+     * ref.current?.animate((anim) => {
+     *   anim.translateX(100).step({ duration: 300 })
+     *   anim.scale(1.2).step({ duration: 200 })
+     *   anim.rotate(360).step({ duration: 500 })
+     * })
+     *
+     * // 设置 transformOrigin
+     * ref.current?.animate((anim) => {
+     *   anim.scaleX(0.5).step({ duration: 300 })
+     * }, { transformOrigin: 'left center' })
+     * ```
+     */
+    animate: (callback: (anim: IAnimation) => any, options?: TOptions & {
+        finish: (event: EventType) => void;
+    }) => 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/types.js

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

package/lib/ScrollView/ScrollView.d.ts

@@ -1,4 +1,4 @@
 import React from 'react';
 import { ScrollViewProps } from '@ray-js/adapter';
-declare const ScrollView: React.FC<ScrollViewProps>;
+declare const ScrollView: React.ForwardRefExoticComponent<ScrollViewProps & React.RefAttributes<any>>;
 export default ScrollView;

package/lib/ScrollView/ScrollView.js

@@ -6,7 +6,7 @@ import React from 'react';
 import { useEventListener } from 'ahooks';
 import { ScrollView as ScrollViewDef } from '@ray-js/adapter';
 import handleProps from '../utils/handleProps';
-const ScrollView = props => {
+const ScrollView = /*#__PURE__*/React.forwardRef((props, ref) => {
   const {
       onScroll,
       onScrollToUpper,
@@ -14,6 +14,9 @@ const ScrollView = props => {
     } = props,
     restProps = _objectWithoutProperties(props, _excluded);
   const currentNode = React.useRef(null);
+
+  // 使用传入的 ref 或内部的 ref
+  const scrollRef = ref || currentNode;
   useEventListener('scroll', e => {
     onScroll === null || onScroll === void 0 || onScroll(_objectSpread(_objectSpread(_objectSpread({}, e), {}, {
       type: 'scroll'
@@ -21,7 +24,7 @@ const ScrollView = props => {
       origin: e
     }));
   }, {
-    target: currentNode
+    target: scrollRef
   });
   useEventListener('scrolltoupper', e => {
     onScrollToUpper === null || onScrollToUpper === void 0 || onScrollToUpper(_objectSpread(_objectSpread(_objectSpread({}, e), {}, {
@@ -30,7 +33,7 @@ const ScrollView = props => {
       origin: e
     }));
   }, {
-    target: currentNode
+    target: scrollRef
   });
   useEventListener('scrolltolower', e => {
     onScrollToLower === null || onScrollToLower === void 0 || onScrollToLower(_objectSpread(_objectSpread(_objectSpread({}, e), {}, {
@@ -39,15 +42,15 @@ const ScrollView = props => {
       origin: e
     }));
   }, {
-    target: currentNode
+    target: scrollRef
   });
   return (
     /*#__PURE__*/
     // @ts-ignore
     React.createElement("v-scroll-view", _extends({}, handleProps(restProps), {
-      ref: currentNode
+      ref: scrollRef
     }), props.children)
   );
-};
+});
 ScrollView.defaultProps = ScrollViewDef.defaultProps;
 export default ScrollView;

package/lib/ScrollView/ScrollView.thing.d.ts

@@ -1,4 +1,4 @@
 import * as React from 'react';
 import type { ScrollViewProps } from '@ray-js/adapter';
-declare const ScrollView: React.FC<ScrollViewProps>;
+declare const ScrollView: React.ForwardRefExoticComponent<ScrollViewProps & React.RefAttributes<any>>;
 export default ScrollView;

package/lib/ScrollView/ScrollView.thing.js

@@ -4,13 +4,16 @@ const _excluded = ["style"];
 import * as React from 'react';
 import { inlineStyle } from '@ray-js/framework-shared';
 import { ScrollView as RemaxScrollView } from '@ray-js/adapter';
-const ScrollView = props => {
+const ScrollView = /*#__PURE__*/React.forwardRef((props, ref) => {
   const {
       style
     } = props,
     restProps = _objectWithoutProperties(props, _excluded);
+  // @ts-ignore - RemaxScrollView 支持 ref，但类型定义可能不完整
   return /*#__PURE__*/React.createElement(RemaxScrollView, _extends({
+    ref: ref,
     style: inlineStyle(style)
   }, restProps));
-};
+});
+ScrollView.displayName = 'ScrollView';
 export default ScrollView;

package/lib/index.d.ts

@@ -33,3 +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';

package/lib/index.js

@@ -32,4 +32,5 @@ export { default as Progress } from './Progress';
 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 SvgRender } from './SvgRender';
+export { default as Animated } from './Animated';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/components",
-  "version": "1.7.55",
+  "version": "1.7.56-beta.1",
   "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.55",
-    "@ray-js/framework-shared": "1.7.55",
+    "@ray-js/adapter": "1.7.56-beta.1",
+    "@ray-js/framework-shared": "1.7.56-beta.1",
     "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.55"
+    "@ray-js/cli": "1.7.56-beta.1"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "gitHead": "99c603c95b6dc57833bd51784cf28c93a4d36b96"
+  "gitHead": "e1d99bcbd08502ade11590cf19ea8c3d01f41cbb"
 }