@seakoi/native-ui 1.1.2 → 1.2.0

package/src/components/base/carousel/carousel.tsx

@@ -4,32 +4,36 @@ import {
   Animated,
   type LayoutChangeEvent,
   type StyleProp,
-  StyleSheet,
   View,
   type ViewStyle,
 } from 'react-native';
 
 import { useTheme } from '#native-provider';
 
+import { CarouselIndicator } from './carousel-indicator';
+import { CarouselSlides } from './carousel-slides';
 import {
   useCarouselAutoplay,
   useCarouselIndex,
-  useCarouselIndicator,
   useCarouselLifecycle,
   useCarouselPanResponder,
   useCarouselPosition,
-  useCarouselSlides,
   useCarouselSwipe,
 } from './hooks';
 import { useCarouselStyles } from './style';
 import type { CarouselProps } from './types';
-import { getDefaultTotal, isRenderPropChildren } from './utils';
 
 interface LayoutState {
   width: number;
   height: number;
 }
 
+/**
+ * 虚拟渲染触发阈值
+ * 当轮播项数量超过此值时启用虚拟渲染优化
+ */
+const VIRTUAL_RENDER_THRESHOLD = 10;
+
 /**
  * 轮播图组件
  *
@@ -38,26 +42,31 @@ interface LayoutState {
  * @example
  * ```tsx
  * // 基础用法
- * <Carousel>
- *   <Carousel.Item><View /></Carousel.Item>
- *   <Carousel.Item><View /></Carousel.Item>
- * </Carousel>
+ * <Carousel
+ *   data={[1, 2, 3]}
+ *   renderItem={(item) => <View><Text>{item}</Text></View>}
+ * />
  *
  * // 循环播放和自动轮播
- * <Carousel loop autoplay autoplayInterval={3000}>
- *   {items.map(item => <Carousel.Item key={item.id}>{item.content}</Carousel.Item>)}
- * </Carousel>
+ * <Carousel
+ *   data={items}
+ *   renderItem={(item) => <View>{item.content}</View>}
+ *   loop
+ *   autoplay
+ *   autoplayInterval={3000}
+ * />
  *
  * // 虚拟渲染（大量数据）
- * <Carousel total={1000}>
- *   {(index) => <Carousel.Item><Text>{index}</Text></Carousel.Item>}
- * </Carousel>
+ * <Carousel
+ *   data={largeDataArray}
+ *   renderItem={(item, index) => <View><Text>{index}: {item}</Text></View>}
+ * />
  * ```
  *
  * @param props - 组件属性
  * @returns 轮播图组件
  */
-export const Carousel = (props: CarouselProps) => {
+export const Carousel = <Data = unknown,>(props: CarouselProps<Data>) => {
   const {
     defaultIndex = 0,
     allowTouchMove = true,
@@ -73,8 +82,8 @@ export const Carousel = (props: CarouselProps) => {
     stuckAtBoundary = true,
     rubberband = true,
     virtualOverscan = 2,
-    total: totalProp,
-    children,
+    data,
+    renderItem,
     style,
     blockNativeResponder = true,
     ref,
@@ -83,27 +92,31 @@ export const Carousel = (props: CarouselProps) => {
   const styles = useCarouselStyles();
   const theme = useTheme();
 
+  // 使用 state 存储 layout，使依赖更明确
   const [layout, setLayout] = useState<LayoutState>({ width: 0, height: 0 });
-  const [dragging, setDragging] = useState(false);
-  const [animating, setAnimating] = useState(false);
 
-  const normalizedSlideSize = useMemo(() => {
-    if (!Number.isFinite(slideSize)) return 100;
-    return clamp(slideSize, 0, 100);
-  }, [slideSize]);
+  // 分离拖动和动画状态，避免状态冲突
+  const [isDragging, setIsDragging] = useState(false);
+  const [isAnimating, setIsAnimating] = useState(false);
 
-  const normalizedTrackOffset = useMemo(() => {
+  // 合并归一化计算，减少 useMemo 调用
+  const { normalizedSlideSize, normalizedTrackOffset } = useMemo(() => {
+    const slideSize_ = Number.isFinite(slideSize) ? clamp(slideSize, 0, 100) : 100;
+    let trackOffset_: number;
     if (stuckAtBoundary) {
-      return 100 - normalizedSlideSize;
+      trackOffset_ = 100 - slideSize_;
+    } else {
+      trackOffset_ = Number.isFinite(trackOffset)
+        ? clamp(trackOffset, 0, 100 - slideSize_)
+        : 0;
     }
-    if (!Number.isFinite(trackOffset)) return 0;
-    return clamp(trackOffset, 0, 100 - normalizedSlideSize);
-  }, [normalizedSlideSize, trackOffset, stuckAtBoundary]);
+    return {
+      normalizedSlideSize: slideSize_,
+      normalizedTrackOffset: trackOffset_,
+    };
+  }, [slideSize, trackOffset, stuckAtBoundary]);
 
-  const total = useMemo(() => {
-    const normalizedDefault = getDefaultTotal(children);
-    return totalProp ?? normalizedDefault;
-  }, [children, totalProp]);
+  const total = data.length;
 
   const loopEnabled = loop && total > 1;
 
@@ -129,17 +142,15 @@ export const Carousel = (props: CarouselProps) => {
 
   const extTotal = loopEnabled ? total + clonesBefore + clonesAfter : total;
 
-  const slidePixels = useMemo(() => {
+  // 合并像素计算，减少重复的 trackSize 获取
+  const { slidePixels, trackOffsetPixels } = useMemo(() => {
     const trackSize = direction === 'horizontal' ? layout.width : layout.height;
-    if (trackSize <= 0) return 0;
-    return trackSize * (normalizedSlideSize / 100);
-  }, [direction, layout.height, layout.width, normalizedSlideSize]);
-
-  const trackOffsetPixels = useMemo(() => {
-    const trackSize = direction === 'horizontal' ? layout.width : layout.height;
-    if (trackSize <= 0) return 0;
-    return trackSize * (normalizedTrackOffset / 100);
-  }, [direction, layout.height, layout.width, normalizedTrackOffset]);
+    if (trackSize <= 0) return { slidePixels: 0, trackOffsetPixels: 0 };
+    return {
+      slidePixels: trackSize * (normalizedSlideSize / 100),
+      trackOffsetPixels: trackSize * (normalizedTrackOffset / 100),
+    };
+  }, [direction, layout, normalizedSlideSize, normalizedTrackOffset]);
 
   const {
     current,
@@ -167,6 +178,15 @@ export const Carousel = (props: CarouselProps) => {
   const { position, positionValueRef, animateTo, setPositionImmediate } =
     useCarouselPosition();
 
+  // 状态设置函数
+  const setDragging = useCallback((dragging: boolean) => {
+    setIsDragging(dragging);
+  }, []);
+
+  const setAnimating = useCallback((animating: boolean) => {
+    setIsAnimating(animating);
+  }, []);
+
   // 切换逻辑
   const { swipeNext, swipePrev, swipeToExtIndex } = useCarouselSwipe({
     total,
@@ -191,7 +211,7 @@ export const Carousel = (props: CarouselProps) => {
     autoplay,
     autoplayInterval,
     total,
-    dragging,
+    dragging: isDragging,
     current,
     swipeNext,
     swipePrev,
@@ -213,8 +233,10 @@ export const Carousel = (props: CarouselProps) => {
   const onLayoutTrack = useCallback((e: LayoutChangeEvent) => {
     const { width, height } = e.nativeEvent.layout;
     setLayout(prev => {
-      if (prev.width === width && prev.height === height) return prev;
-      return { width, height };
+      if (prev.width !== width || prev.height !== height) {
+        return { width, height };
+      }
+      return prev;
     });
   }, []);
 
@@ -248,20 +270,20 @@ export const Carousel = (props: CarouselProps) => {
   }, [direction, position, trackOffsetPixels]);
 
   // 计算虚拟渲染的范围
-  // 注意: extIndexRef 的变化不会触发重新计算，
-  // 通过 dragging 和 animating 状态的变化来触发虚拟范围的更新
+  // 使用 current 状态而不是 extIndexRef，确保虚拟范围与当前索引同步
   const virtualRange = useMemo(() => {
     if (total <= 0 || slidePixels <= 0) {
       return null;
     }
 
-    const isVirtual =
-      isRenderPropChildren(children) && typeof totalProp === 'number';
+    const isVirtual = total > VIRTUAL_RENDER_THRESHOLD;
+    const isInteracting = isDragging || isAnimating;
     const effectiveOverscan = isVirtual
-      ? Math.max(virtualOverscan, dragging || animating ? 1 : 0)
+      ? Math.max(virtualOverscan, isInteracting ? 1 : 0)
       : virtualOverscan;
 
-    const currentExtIndex = extIndexRef.current;
+    // 使用 current 计算 extIndex，确保响应式更新
+    const currentExtIndex = loopEnabled ? current + clonesBefore : current;
     const start = isVirtual
       ? clamp(currentExtIndex - effectiveOverscan, 0, extTotal - 1)
       : 0;
@@ -273,88 +295,56 @@ export const Carousel = (props: CarouselProps) => {
   }, [
     total,
     slidePixels,
-    children,
-    totalProp,
     virtualOverscan,
-    dragging,
-    animating,
-    extIndexRef, // 保留以表明依赖关系，虽然不会触发更新
-    extTotal,
-  ]);
-
-  // 计算滑块包装器样式
-  const slideWrapperStyle: ViewStyle = useMemo(() => {
-    return direction === 'horizontal'
-      ? { width: slidePixels, height: '100%' }
-      : { height: slidePixels, width: '100%' };
-  }, [direction, slidePixels]);
-
-  // 计算虚拟渲染的占位空间样式
-  const spacerStyles = useMemo(() => {
-    if (!virtualRange) return null;
-
-    const { start, end } = virtualRange;
-    const leadingSize = start * slidePixels;
-    const trailingSize = (extTotal - end - 1) * slidePixels;
-
-    return {
-      leading:
-        direction === 'horizontal'
-          ? { width: leadingSize }
-          : { height: leadingSize },
-      trailing:
-        direction === 'horizontal'
-          ? { width: trailingSize }
-          : { height: trailingSize },
-      leadingSize,
-      trailingSize,
-    };
-  }, [virtualRange, slidePixels, extTotal, direction]);
-
-  const { renderSlides } = useCarouselSlides({
-    children,
-    total,
-    virtualRange,
+    isDragging,
+    isAnimating,
+    current,
     loopEnabled,
     clonesBefore,
-    slideWrapperStyle,
-    spacerStyles,
-    slideStyles: styles,
-  });
+    extTotal,
+  ]);
 
-  const { renderIndicator } = useCarouselIndicator({
-    indicator,
-    indicatorProps,
-    total,
-    current,
-    activeColor: theme.palette.brand7,
-    inactiveColor: theme.palette.fontGray5,
-    styles,
-  });
+  const trackInnerStyle =
+    direction === 'horizontal'
+      ? styles.trackInnerHorizontal
+      : styles.trackInnerVertical;
 
-  const trackInnerStyle: ViewStyle = useMemo(() => {
-    return direction === 'horizontal'
-      ? { flexDirection: 'row', height: '100%' }
-      : { flexDirection: 'column', width: '100%' };
-  }, [direction]);
+  // 边界情况处理：空数据
+  if (!data || data.length === 0) {
+    return null;
+  }
 
   return (
-    <View style={StyleSheet.flatten([styles.container, style])}>
+    <View style={[styles.container, style]}>
       <View
         style={styles.track}
         onLayout={onLayoutTrack}
         {...panResponder?.panHandlers}
       >
         <Animated.View
-          style={StyleSheet.flatten([
-            styles.trackInner,
-            trackInnerStyle,
-            trackTransformStyle,
-          ])}
+          style={[styles.trackInner, trackInnerStyle, trackTransformStyle]}
         >
-          {renderSlides()}
+          <CarouselSlides<Data>
+            data={data}
+            renderItem={renderItem}
+            total={total}
+            virtualRange={virtualRange}
+            loopEnabled={loopEnabled}
+            clonesBefore={clonesBefore}
+            direction={direction}
+            slidePixels={slidePixels}
+            extTotal={extTotal}
+          />
         </Animated.View>
-        {renderIndicator()}
+        <CarouselIndicator
+          indicator={indicator}
+          indicatorProps={indicatorProps}
+          total={total}
+          current={current}
+          activeColor={theme.palette.brand7}
+          inactiveColor={theme.palette.fontGray5}
+          styles={styles}
+        />
       </View>
     </View>
   );

package/src/components/base/carousel/hooks/index.ts

@@ -1,8 +1,6 @@
 export { useCarouselAutoplay } from './use-carousel-autoplay';
 export { useCarouselIndex } from './use-carousel-index';
-export { useCarouselIndicator } from './use-carousel-indicator';
 export { useCarouselLifecycle } from './use-carousel-lifecycle';
 export { useCarouselPanResponder } from './use-carousel-pan-responder';
 export { useCarouselPosition } from './use-carousel-position';
-export { useCarouselSlides } from './use-carousel-slides';
 export { useCarouselSwipe } from './use-carousel-swipe';

package/src/components/base/carousel/hooks/use-carousel-index.ts

@@ -2,9 +2,10 @@ import { useMemoizedFn } from 'ahooks';
 import { clamp } from 'lodash-es';
 import { useCallback, useRef, useState } from 'react';
 
-import { RUBBERBAND_DAMPING } from '#components/base/carousel/constants';
-
-import { getBoundaryIndexRange } from '../utils';
+/**
+ * 橡皮筋效果阻尼系数
+ */
+const RUBBERBAND_DAMPING = 0.35;
 
 interface UseCarouselIndexParams {
   total: number;
@@ -126,12 +127,15 @@ export const useCarouselIndex = (params: UseCarouselIndexParams) => {
     if (slidePixels <= 0) return nextPosition;
     if (total <= 0) return 0;
 
-    const { min, max } = getBoundaryIndexRange({
-      total,
-      slideSize: normalizedSlideSize,
-      trackOffset: normalizedTrackOffset,
-      stuckAtBoundary,
-    });
+    // 计算轮播边界索引范围
+    let min = 0;
+    let max = total - 1;
+    if (stuckAtBoundary) {
+      const slideRatio = normalizedSlideSize / 100;
+      const offsetRatio = normalizedTrackOffset / 100;
+      min = 0 + offsetRatio / (slideRatio || 1);
+      max = total - 1 - (1 - slideRatio - offsetRatio) / (slideRatio || 1);
+    }
     const minPos = min * slidePixels;
     const maxPos = max * slidePixels;
 

package/src/components/base/carousel/hooks/use-carousel-lifecycle.ts

@@ -64,6 +64,7 @@ export const useCarouselLifecycle = (params: UseCarouselLifecycleParams) => {
     if (slidePixels > 0) {
       setPositionImmediate(getBoundedPosition(extIndex * slidePixels));
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     defaultIndex,
     getExtIndexFromIndex,
@@ -72,8 +73,7 @@ export const useCarouselLifecycle = (params: UseCarouselLifecycleParams) => {
     slidePixels,
     total,
     updateCurrent,
-    reportIndexRef,
-    extIndexRef,
+    // refs 不需要在依赖数组中，它们的引用永远不变
   ]);
 
   // 响应 slidePixels 变化
@@ -81,5 +81,6 @@ export const useCarouselLifecycle = (params: UseCarouselLifecycleParams) => {
     if (slidePixels <= 0) return;
     const extIndex = extIndexRef.current;
     setPositionImmediate(getBoundedPosition(extIndex * slidePixels));
-  }, [getBoundedPosition, setPositionImmediate, slidePixels, extIndexRef]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [getBoundedPosition, setPositionImmediate, slidePixels]);
 };

package/src/components/base/carousel/hooks/use-carousel-pan-responder.ts

@@ -1,12 +1,20 @@
 import { clamp } from 'lodash-es';
-import { type RefObject, useMemo } from 'react';
+import { type RefObject, useMemo, useRef } from 'react';
 import {
   type Animated,
   PanResponder,
   type PanResponderInstance,
 } from 'react-native';
 
-import { GESTURE_MIN_DISTANCE, VELOCITY_PROJECTION_FACTOR } from '../constants';
+/**
+ * 手势识别最小移动距离（像素）
+ */
+const GESTURE_MIN_DISTANCE = 5;
+
+/**
+ * 速度投影系数（用于计算惯性滑动距离）
+ */
+const VELOCITY_PROJECTION_FACTOR = 2000;
 
 interface UseCarouselPanResponderParams {
   allowTouchMove: boolean;
@@ -76,6 +84,26 @@ export const useCarouselPanResponder = (
     swipeToExtIndex,
   } = params;
 
+  // 使用 ref 存储回调，减少 PanResponder 重建
+  const callbacksRef = useRef({
+    setDragging,
+    setAnimating,
+    updateCurrent,
+    getIndexFromExtIndex,
+    getBoundedPosition,
+    swipeToExtIndex,
+  });
+
+  // 更新回调 ref
+  callbacksRef.current = {
+    setDragging,
+    setAnimating,
+    updateCurrent,
+    getIndexFromExtIndex,
+    getBoundedPosition,
+    swipeToExtIndex,
+  };
+
   return useMemo(() => {
     if (!allowTouchMove) return null;
     if (total <= 1) return null;
@@ -92,8 +120,8 @@ export const useCarouselPanResponder = (
     return PanResponder.create({
       onMoveShouldSetPanResponder: shouldSet,
       onPanResponderGrant: () => {
-        setDragging(true);
-        setAnimating(false);
+        callbacksRef.current.setDragging(true);
+        callbacksRef.current.setAnimating(false);
         position.current.stopAnimation();
         startPosition = positionValueRef.current;
       },
@@ -117,7 +145,7 @@ export const useCarouselPanResponder = (
           }
         }
 
-        const bounded = getBoundedPosition(nextPosition);
+        const bounded = callbacksRef.current.getBoundedPosition(nextPosition);
         position.current.setValue(bounded);
         positionValueRef.current = bounded;
 
@@ -127,10 +155,12 @@ export const useCarouselPanResponder = (
           extTotal - 1,
         );
         extIndexRef.current = nextExtIndex;
-        updateCurrent(getIndexFromExtIndex(nextExtIndex));
+        callbacksRef.current.updateCurrent(
+          callbacksRef.current.getIndexFromExtIndex(nextExtIndex),
+        );
       },
       onPanResponderRelease: (_evt, gestureState) => {
-        setDragging(false);
+        callbacksRef.current.setDragging(false);
         const velocity = axis === 'x' ? gestureState.vx : gestureState.vy;
         position.current.stopAnimation(value => {
           const baseIndex = value / slidePixels;
@@ -141,12 +171,12 @@ export const useCarouselPanResponder = (
           const maxAdj = minAdj + 1;
           const rounded = Math.round(projectedIndex);
           const adjacent = clamp(rounded, minAdj, maxAdj);
-          swipeToExtIndex(adjacent);
+          callbacksRef.current.swipeToExtIndex(adjacent);
         });
       },
       onPanResponderTerminate: () => {
-        setDragging(false);
-        swipeToExtIndex(extIndexRef.current);
+        callbacksRef.current.setDragging(false);
+        callbacksRef.current.swipeToExtIndex(extIndexRef.current);
       },
       onPanResponderTerminationRequest: () => false,
       onShouldBlockNativeResponder: () => blockNativeResponder,
@@ -158,15 +188,9 @@ export const useCarouselPanResponder = (
     direction,
     extTotal,
     extIndexRef,
-    getBoundedPosition,
-    getIndexFromExtIndex,
     position,
     positionValueRef,
-    setAnimating,
-    setDragging,
     slidePixels,
-    swipeToExtIndex,
     total,
-    updateCurrent,
   ]);
 };

package/src/components/base/carousel/hooks/use-carousel-position.ts

@@ -1,7 +1,10 @@
 import { useCallback, useRef } from 'react';
 import { Animated, Easing } from 'react-native';
 
-import { CAROUSEL_ANIMATION_DURATION } from '../constants';
+/**
+ * 轮播图动画时长（毫秒）
+ */
+const CAROUSEL_ANIMATION_DURATION = 300;
 
 /**
  * 轮播图位置和动画控制 Hook

package/src/components/base/carousel/index.ts

@@ -1,8 +1,6 @@
 import { Carousel as _Carousel } from './carousel';
-import { CarouselItem } from './carousel-item';
 
 export * from './carousel';
-export * from './carousel-item';
 export type * from './types';
 
-export const Carousel = Object.assign(_Carousel, { Item: CarouselItem });
+export const Carousel = _Carousel;

package/src/components/base/carousel/style/index.ts

@@ -16,6 +16,18 @@ export const useCarouselStyles = createThemedStyles(theme => ({
     flexGrow: 0,
     flexShrink: 0,
   },
+  trackInnerHorizontal: {
+    flexDirection: 'row',
+    height: '100%',
+    flexGrow: 0,
+    flexShrink: 0,
+  },
+  trackInnerVertical: {
+    flexDirection: 'column',
+    width: '100%',
+    flexGrow: 0,
+    flexShrink: 0,
+  },
   slide: {
     flexGrow: 0,
     flexShrink: 0,

package/src/components/base/carousel/types.ts

@@ -1,4 +1,4 @@
-import type { ReactElement, ReactNode, Ref } from 'react';
+import type { ReactNode, Ref } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 
 /** Carousel 组件暴露的实例方法 */
@@ -12,7 +12,7 @@ export interface CarouselRef {
 }
 
 /** Carousel 组件属性 */
-export interface CarouselProps {
+export interface CarouselProps<Data = unknown> {
   /**
    * 初始展示的索引
    * 该属性是响应式的，当值变化时轮播会跳转到对应索引
@@ -101,26 +101,21 @@ export interface CarouselProps {
 
   /**
    * 虚拟渲染时前后额外渲染的滑块个数
-   * 仅在使用 render prop 且传入 total 时生效
    * @default 2
    */
   virtualOverscan?: number;
 
   /**
-   * 总滑块数量
-   * 使用 render prop children 时需要手动传入
+   * 数据源数组
    */
-  total?: number;
+  data: Data[];
 
   /**
-   * 滑块内容
-   * - 直接传入 CarouselItem 列表
-   * - 或者传入 render prop，根据索引返回节点
+   * 渲染每一项的函数
+   * @param item - 数据项
+   * @param index - 索引
    */
-  children?:
-    | ReactElement<CarouselItemProps>
-    | ReactElement<CarouselItemProps>[]
-    | ((index: number) => ReactElement<CarouselItemProps>);
+  renderItem: (item: Data, index: number) => ReactNode;
 
   /**
    * 是否阻断原生手势响应
@@ -134,11 +129,3 @@ export interface CarouselProps {
 
   ref?: Ref<CarouselRef>;
 }
-
-/** CarouselItem 组件属性 */
-export interface CarouselItemProps {
-  /** 滑块内容 */
-  children?: ReactNode;
-  /** 滑块容器样式 */
-  style?: StyleProp<ViewStyle>;
-}