@seakoi/native-ui 1.0.0 → 1.1.0

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

@@ -0,0 +1,691 @@
+import { clamp } from 'lodash-es';
+import React, {
+  forwardRef,
+  type ReactElement,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import {
+  Animated,
+  Easing,
+  type LayoutChangeEvent,
+  PanResponder,
+  type PanResponderInstance,
+  type StyleProp,
+  StyleSheet,
+  View,
+  type ViewStyle,
+} from 'react-native';
+
+import {
+  getDefaultTotal,
+  isRenderPropChildren,
+  normalizeChildren,
+} from '#components/base/carousel/utils';
+import { useTheme } from '#native-provider';
+
+import { useCarouselStyles } from './style';
+import type { CarouselProps, CarouselRef } from './types';
+
+const getBoundaryIndexRange = ({
+  total,
+  slideSize,
+  trackOffset,
+  stuckAtBoundary,
+}: {
+  total: number;
+  slideSize: number;
+  trackOffset: number;
+  stuckAtBoundary: boolean;
+}) => {
+  if (total <= 0) return { min: 0, max: 0 };
+  if (!stuckAtBoundary) return { min: 0, max: total - 1 };
+
+  const slideRatio = slideSize / 100;
+  const offsetRatio = trackOffset / 100;
+
+  const min = 0 + offsetRatio / (slideRatio || 1);
+  const max = total - 1 - (1 - slideRatio - offsetRatio) / (slideRatio || 1);
+  return { min, max };
+};
+
+interface LayoutState {
+  width: number;
+  height: number;
+}
+
+/**
+ * 轮播图
+ */
+export const Carousel = forwardRef<CarouselRef, CarouselProps>((props, ref) => {
+  const {
+    defaultIndex = 0,
+    allowTouchMove = true,
+    autoplay = false,
+    autoplayInterval = 3000,
+    loop = false,
+    direction = 'horizontal',
+    onIndexChange,
+    indicatorProps,
+    indicator,
+    slideSize = 100,
+    trackOffset = 0,
+    stuckAtBoundary = true,
+    rubberband = true,
+    virtualOverscan = 2,
+    total: totalProp,
+    children,
+    style,
+  } = props;
+
+  const styles = useCarouselStyles();
+  const theme = useTheme();
+
+  const [layout, setLayout] = useState<LayoutState>({ width: 0, height: 0 });
+  const [dragging, setDragging] = useState(false);
+  const [animating, setAnimating] = useState(false);
+  const [current, setCurrent] = useState(0);
+
+  const position = useRef(new Animated.Value(0));
+  const positionValueRef = useRef(0);
+
+  const normalizedSlideSize = useMemo(() => {
+    if (!Number.isFinite(slideSize)) return 100;
+    return clamp(slideSize, 0, 100);
+  }, [slideSize]);
+
+  const normalizedTrackOffset = useMemo(() => {
+    if (stuckAtBoundary) {
+      return 100 - normalizedSlideSize;
+    }
+    if (!Number.isFinite(trackOffset)) return 0;
+    return clamp(trackOffset, 0, 100 - normalizedSlideSize);
+  }, [normalizedSlideSize, trackOffset, stuckAtBoundary]);
+
+  const total = useMemo(() => {
+    const normalizedDefault = getDefaultTotal(children);
+    return totalProp ?? normalizedDefault;
+  }, [children, totalProp]);
+
+  const loopEnabled = loop && total > 1;
+  // 若是非全屏的轮播项，则在循环播放开启的情况下，则会在下一轮展示第一项时看见下一项为空白（或闪烁），这需要额外渲染更多的项（与offset、slideSize相关）
+  const clonesBefore = loopEnabled
+    ? Math.max(
+        1,
+        normalizedSlideSize > 0
+          ? Math.ceil(normalizedTrackOffset / normalizedSlideSize) + 1
+          : 1,
+      )
+    : 0;
+  const clonesAfter = loopEnabled
+    ? Math.max(
+        1,
+        normalizedSlideSize > 0
+          ? Math.ceil(
+              (100 - normalizedTrackOffset - normalizedSlideSize) /
+                normalizedSlideSize,
+            ) + 1
+          : 1,
+      )
+    : 0;
+  const extTotal = loopEnabled ? total + clonesBefore + clonesAfter : total;
+
+  const slidePixels = 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]);
+
+  const extIndexRef = useRef(0);
+  const reportIndexRef = useRef<number | null>(null);
+
+  const staticSlides = useMemo(() => {
+    if (isRenderPropChildren(children)) return [];
+    return normalizeChildren(children, total);
+  }, [children, total]);
+
+  const updateCurrent = useCallback(
+    (next: number) => {
+      const normalized = total > 0 ? clamp(next, 0, total - 1) : 0;
+      setCurrent(normalized);
+    },
+    [total],
+  );
+
+  const maybeReportIndex = useCallback(
+    (index: number) => {
+      if (!onIndexChange) return;
+      if (reportIndexRef.current === index) return;
+      reportIndexRef.current = index;
+      onIndexChange(index);
+    },
+    [onIndexChange],
+  );
+
+  const getExtIndexFromIndex = useCallback(
+    (index: number) => {
+      if (!loopEnabled) return index;
+      return clamp(index, 0, total - 1) + clonesBefore;
+    },
+    [clonesBefore, loopEnabled, total],
+  );
+
+  const getIndexFromExtIndex = useCallback(
+    (extIndex: number) => {
+      if (!loopEnabled) return clamp(extIndex, 0, total - 1);
+      if (extIndex < clonesBefore) {
+        return (((extIndex - clonesBefore) % total) + total) % total;
+      }
+      if (extIndex >= clonesBefore + total) {
+        return (extIndex - clonesBefore - total) % total;
+      }
+      return extIndex - clonesBefore;
+    },
+    [clonesBefore, loopEnabled, total],
+  );
+
+  const getTargetExtIndexForIndex = useCallback(
+    (targetIndex: number) => {
+      if (!loopEnabled) return clamp(targetIndex, 0, total - 1);
+
+      const currentExt = extIndexRef.current;
+      const normalizedTarget = clamp(targetIndex, 0, total - 1);
+      const targetExt = normalizedTarget + clonesBefore;
+
+      if (currentExt === clonesBefore && normalizedTarget === total - 1)
+        return clonesBefore - 1;
+      if (currentExt === clonesBefore + total - 1 && normalizedTarget === 0)
+        return clonesBefore + total;
+      return targetExt;
+    },
+    [clonesBefore, loopEnabled, total],
+  );
+
+  const getBoundedPosition = useCallback(
+    (nextPosition: number) => {
+      if (loopEnabled) return nextPosition;
+      if (slidePixels <= 0) return nextPosition;
+      if (total <= 0) return 0;
+
+      const { min, max } = getBoundaryIndexRange({
+        total,
+        slideSize: normalizedSlideSize,
+        trackOffset: normalizedTrackOffset,
+        stuckAtBoundary,
+      });
+      const minPos = min * slidePixels;
+      const maxPos = max * slidePixels;
+
+      if (nextPosition < minPos) {
+        if (!rubberband) return minPos;
+        return minPos - (minPos - nextPosition) * 0.35;
+      }
+      if (nextPosition > maxPos) {
+        if (!rubberband) return maxPos;
+        return maxPos + (nextPosition - maxPos) * 0.35;
+      }
+      return nextPosition;
+    },
+    [
+      loopEnabled,
+      rubberband,
+      slidePixels,
+      normalizedSlideSize,
+      stuckAtBoundary,
+      total,
+      normalizedTrackOffset,
+    ],
+  );
+
+  const animateTo = useCallback((toValue: number, onFinished?: () => void) => {
+    const listenerId = position.current.addListener(({ value }) => {
+      positionValueRef.current = value;
+    });
+    Animated.timing(position.current, {
+      toValue,
+      duration: 300,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start(({ finished }) => {
+      position.current.removeListener(listenerId);
+      if (finished) {
+        positionValueRef.current = toValue;
+        onFinished?.();
+      }
+    });
+  }, []);
+
+  const setPositionImmediate = useCallback((toValue: number) => {
+    position.current.stopAnimation();
+    position.current.setValue(toValue);
+    positionValueRef.current = toValue;
+  }, []);
+
+  const finalizeLoopJumpIfNeeded = useCallback(() => {
+    if (!loopEnabled) return;
+    const currentExt = extIndexRef.current;
+    if (currentExt < clonesBefore) {
+      const targetExt = currentExt + total;
+      extIndexRef.current = targetExt;
+      if (slidePixels > 0) setPositionImmediate(targetExt * slidePixels);
+      return;
+    }
+    if (currentExt >= clonesBefore + total) {
+      const targetExt = currentExt - total;
+      extIndexRef.current = targetExt;
+      if (slidePixels > 0) setPositionImmediate(targetExt * slidePixels);
+    }
+  }, [clonesBefore, loopEnabled, setPositionImmediate, slidePixels, total]);
+
+  const swipeToExtIndex = useCallback(
+    (targetExtIndex: number) => {
+      if (total <= 0) return;
+      if (slidePixels <= 0) {
+        extIndexRef.current = clamp(targetExtIndex, 0, extTotal - 1);
+        setAnimating(false);
+        updateCurrent(getIndexFromExtIndex(extIndexRef.current));
+        return;
+      }
+
+      const boundedExtIndex = clamp(targetExtIndex, 0, extTotal - 1);
+      extIndexRef.current = boundedExtIndex;
+
+      const nextIndex = getIndexFromExtIndex(boundedExtIndex);
+      updateCurrent(nextIndex);
+
+      const rawPosition = boundedExtIndex * slidePixels;
+      const toPosition = getBoundedPosition(rawPosition);
+
+      setAnimating(true);
+      animateTo(toPosition, () => {
+        finalizeLoopJumpIfNeeded();
+        const normalizedIndex = getIndexFromExtIndex(extIndexRef.current);
+        updateCurrent(normalizedIndex);
+        maybeReportIndex(normalizedIndex);
+        setAnimating(false);
+      });
+    },
+    [
+      animateTo,
+      extTotal,
+      finalizeLoopJumpIfNeeded,
+      getBoundedPosition,
+      getIndexFromExtIndex,
+      maybeReportIndex,
+      slidePixels,
+      total,
+      updateCurrent,
+    ],
+  );
+
+  const swipeTo = useCallback(
+    (index: number) => {
+      if (total <= 0) return;
+      const targetIndex = clamp(Math.round(index), 0, total - 1);
+      const targetExtIndex = getTargetExtIndexForIndex(targetIndex);
+      swipeToExtIndex(targetExtIndex);
+    },
+    [getTargetExtIndexForIndex, swipeToExtIndex, total],
+  );
+
+  const swipeNext = useCallback(() => {
+    if (total <= 1) return;
+    let currentExt = extIndexRef.current;
+    // 若当前处于 after-clone 区域（快速连击导致 finalizeLoopJumpIfNeeded 尚未执行），
+    // 立即将位置平移回真实 item 区域（视觉内容相同，不可感知），再继续前进
+    if (clonesBefore > 0 && currentExt >= clonesBefore + total) {
+      currentExt -= total;
+      extIndexRef.current = currentExt;
+      if (slidePixels > 0) setPositionImmediate(currentExt * slidePixels);
+    }
+    swipeToExtIndex(currentExt + 1);
+  }, [clonesBefore, setPositionImmediate, slidePixels, swipeToExtIndex, total]);
+
+  const swipePrev = useCallback(() => {
+    if (total <= 1) return;
+    let currentExt = extIndexRef.current;
+    // 若当前处于 before-clone 区域（快速连击导致 finalizeLoopJumpIfNeeded 尚未执行），
+    // 立即将位置平移回真实 item 区域（视觉内容相同，不可感知），再继续后退
+    if (clonesBefore > 0 && currentExt < clonesBefore) {
+      currentExt += total;
+      extIndexRef.current = currentExt;
+      if (slidePixels > 0) setPositionImmediate(currentExt * slidePixels);
+    }
+    swipeToExtIndex(currentExt - 1);
+  }, [clonesBefore, setPositionImmediate, slidePixels, swipeToExtIndex, total]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      swipeTo,
+      swipeNext,
+      swipePrev,
+    }),
+    [swipeNext, swipePrev, swipeTo],
+  );
+
+  useEffect(() => {
+    if (total <= 0) {
+      updateCurrent(0);
+      reportIndexRef.current = null;
+      extIndexRef.current = 0;
+      setPositionImmediate(0);
+      return;
+    }
+
+    const normalizedDefault = clamp(Math.round(defaultIndex), 0, total - 1);
+    updateCurrent(normalizedDefault);
+    reportIndexRef.current = normalizedDefault;
+
+    const extIndex = getExtIndexFromIndex(normalizedDefault);
+    extIndexRef.current = extIndex;
+    if (slidePixels > 0) {
+      setPositionImmediate(getBoundedPosition(extIndex * slidePixels));
+    }
+  }, [
+    defaultIndex,
+    getExtIndexFromIndex,
+    getBoundedPosition,
+    setPositionImmediate,
+    slidePixels,
+    total,
+    updateCurrent,
+  ]);
+
+  useEffect(() => {
+    if (slidePixels <= 0) return;
+    const extIndex = extIndexRef.current;
+    setPositionImmediate(getBoundedPosition(extIndex * slidePixels));
+  }, [getBoundedPosition, setPositionImmediate, slidePixels]);
+
+  // 每当 current 变化时，若允许自动轮播 且 开启了自动轮播，则执行轮播
+  useEffect(() => {
+    if (!autoplay) return;
+    if (total <= 1) return;
+    if (dragging) return;
+    if (autoplayInterval <= 0) return;
+
+    const timer = setTimeout(() => {
+      if (autoplay === 'reverse') swipePrev();
+      else swipeNext();
+    }, autoplayInterval);
+
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [autoplay, autoplayInterval, dragging, swipeNext, swipePrev, total, current]);
+
+  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 };
+    });
+  }, []);
+
+  const panResponder: PanResponderInstance | null = useMemo(() => {
+    if (!allowTouchMove) return null;
+    if (total <= 1) return null;
+    if (slidePixels <= 0) return null;
+
+    let startPosition = 0;
+    const axis = direction === 'horizontal' ? 'x' : 'y';
+
+    const shouldSet = (_: unknown, gestureState: { dx: number; dy: number }) => {
+      const primary = axis === 'x' ? gestureState.dx : gestureState.dy;
+      // const secondary = axis === 'x' ? gestureState.dy : gestureState.dx;
+      if (Math.abs(primary) < 5) return false;
+      // return Math.abs(primary) >= Math.abs(secondary);
+      return true;
+    };
+
+    return PanResponder.create({
+      onMoveShouldSetPanResponder: shouldSet,
+      onPanResponderGrant: () => {
+        setDragging(true);
+        setAnimating(false);
+        position.current.stopAnimation();
+        startPosition = positionValueRef.current;
+      },
+      onPanResponderMove: (_evt, gestureState) => {
+        const delta = axis === 'x' ? gestureState.dx : gestureState.dy;
+        let nextPosition = startPosition - delta;
+
+        // loop 开启时，拖动到最外层有效克隆中心之外则循环偏移，保证视口内始终有内容
+        // minPos/maxPos 是 outermost before/after clone 的中心位置，由 clonesBefore 公式保证此范围内视口始终被覆盖
+        if (extTotal > total && slidePixels > 0) {
+          const totalPixels = total * slidePixels;
+          const minPos = (clonesBefore - 1) * slidePixels;
+          const maxPos = (clonesBefore + total) * slidePixels;
+          while (nextPosition < minPos) {
+            nextPosition += totalPixels;
+            startPosition += totalPixels;
+          }
+          while (nextPosition > maxPos) {
+            nextPosition -= totalPixels;
+            startPosition -= totalPixels;
+          }
+        }
+
+        const bounded = getBoundedPosition(nextPosition);
+        position.current.setValue(bounded);
+        positionValueRef.current = bounded;
+
+        const nextExtIndex = clamp(
+          Math.round(bounded / slidePixels),
+          0,
+          extTotal - 1,
+        );
+        extIndexRef.current = nextExtIndex;
+        updateCurrent(getIndexFromExtIndex(nextExtIndex));
+      },
+      onPanResponderRelease: (_evt, gestureState) => {
+        setDragging(false);
+        const velocity = axis === 'x' ? gestureState.vx : gestureState.vy;
+        position.current.stopAnimation(value => {
+          const baseIndex = value / slidePixels;
+          const projectedIndex = (value - velocity * 2000) / slidePixels;
+
+          const minAdj = Math.floor(baseIndex);
+          const maxAdj = minAdj + 1;
+          const rounded = Math.round(projectedIndex);
+          const adjacent = clamp(rounded, minAdj, maxAdj);
+          swipeToExtIndex(adjacent);
+        });
+      },
+      onPanResponderTerminate: () => {
+        setDragging(false);
+        swipeToExtIndex(extIndexRef.current);
+      },
+      onPanResponderTerminationRequest: () => false,
+      onShouldBlockNativeResponder: () => true,
+    });
+  }, [
+    allowTouchMove,
+    clonesBefore,
+    direction,
+    extTotal,
+    getBoundedPosition,
+    getIndexFromExtIndex,
+    slidePixels,
+    swipeToExtIndex,
+    total,
+    updateCurrent,
+  ]);
+
+  const trackTransformStyle: StyleProp<ViewStyle> = useMemo(() => {
+    const translate = Animated.add(
+      Animated.multiply(position.current, -1),
+      trackOffsetPixels,
+    );
+    return direction === 'horizontal'
+      ? { transform: [{ translateX: translate }] }
+      : { transform: [{ translateY: translate }] };
+  }, [direction, trackOffsetPixels]);
+
+  const renderSlides = useCallback(() => {
+    if (total <= 0) return null;
+    if (slidePixels <= 0) return null;
+
+    const isVirtual =
+      isRenderPropChildren(children) && typeof totalProp === 'number';
+    const effectiveOverscan = isVirtual
+      ? Math.max(virtualOverscan, dragging || animating ? 1 : 0)
+      : virtualOverscan;
+
+    const currentExtIndex = extIndexRef.current;
+    const start = isVirtual
+      ? clamp(currentExtIndex - effectiveOverscan, 0, extTotal - 1)
+      : 0;
+    const end = isVirtual
+      ? clamp(currentExtIndex + effectiveOverscan, 0, extTotal - 1)
+      : extTotal - 1;
+
+    const leadingSize = start * slidePixels;
+    const trailingSize = (extTotal - end - 1) * slidePixels;
+
+    const leadSpacerStyle: ViewStyle =
+      direction === 'horizontal' ? { width: leadingSize } : { height: leadingSize };
+    const trailSpacerStyle: ViewStyle =
+      direction === 'horizontal'
+        ? { width: trailingSize }
+        : { height: trailingSize };
+
+    const slideWrapperBaseStyle: ViewStyle =
+      direction === 'horizontal'
+        ? { width: slidePixels, height: '100%' }
+        : { height: slidePixels, width: '100%' };
+
+    const getElementForExtIndex = (extIndex: number) => {
+      const logicalIndex = loopEnabled
+        ? getIndexFromExtIndex(extIndex)
+        : clamp(extIndex, 0, total - 1);
+
+      if (isRenderPropChildren(children)) return children(logicalIndex);
+      return staticSlides[logicalIndex];
+    };
+
+    const slideElements: ReactElement[] = [];
+    for (let extIndex = start; extIndex <= end; extIndex += 1) {
+      const element = getElementForExtIndex(extIndex);
+      if (!element) continue;
+      slideElements.push(
+        <View key={extIndex} style={[styles.slide, slideWrapperBaseStyle]}>
+          {element}
+        </View>,
+      );
+    }
+
+    const leadSpacer =
+      isVirtual && leadingSize > 0 ? <View style={leadSpacerStyle} /> : null;
+    const trailSpacer =
+      isVirtual && trailingSize > 0 ? <View style={trailSpacerStyle} /> : null;
+
+    return (
+      <>
+        {leadSpacer}
+        {slideElements}
+        {trailSpacer}
+      </>
+    );
+  }, [
+    children,
+    direction,
+    extTotal,
+    getIndexFromExtIndex,
+    dragging,
+    animating,
+    loopEnabled,
+    slidePixels,
+    staticSlides,
+    styles.slide,
+    total,
+    totalProp,
+    virtualOverscan,
+  ]);
+
+  const renderIndicator = useCallback(() => {
+    if (indicator === false) return null;
+    if (total <= 1) return null;
+
+    if (typeof indicator === 'function') {
+      return indicator(total, current);
+    }
+
+    const activeColor = indicatorProps?.color ?? theme.palette.brand7;
+    const inactiveColor = theme.palette.fontGray5;
+
+    return (
+      <View
+        style={StyleSheet.flatten([
+          styles.indicatorContainer,
+          indicatorProps?.style,
+        ])}
+      >
+        {Array.from({ length: total }, (_, i) => {
+          const isActive = i === current;
+          return (
+            <View
+              key={i}
+              style={StyleSheet.flatten([
+                styles.indicatorDot,
+                { backgroundColor: isActive ? activeColor : inactiveColor },
+                isActive && styles.indicatorDotActive,
+              ])}
+            />
+          );
+        })}
+      </View>
+    );
+  }, [
+    current,
+    indicator,
+    indicatorProps?.color,
+    indicatorProps?.style,
+    styles.indicatorContainer,
+    styles.indicatorDot,
+    styles.indicatorDotActive,
+    theme.palette.brand7,
+    theme.palette.fontGray5,
+    total,
+  ]);
+
+  const trackInnerStyle: ViewStyle = useMemo(() => {
+    return direction === 'horizontal'
+      ? { flexDirection: 'row', height: '100%' }
+      : { flexDirection: 'column', width: '100%' };
+  }, [direction]);
+
+  return (
+    <View style={StyleSheet.flatten([styles.container, style])}>
+      <View
+        style={styles.track}
+        onLayout={onLayoutTrack}
+        {...panResponder?.panHandlers}
+      >
+        <Animated.View
+          style={StyleSheet.flatten([
+            styles.trackInner,
+            trackInnerStyle,
+            trackTransformStyle,
+          ])}
+        >
+          {renderSlides()}
+        </Animated.View>
+        {renderIndicator()}
+      </View>
+    </View>
+  );
+});
+
+Carousel.displayName = 'Carousel';

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

@@ -0,0 +1,8 @@
+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 });