@xhsreds/reds-rn-next 0.9.1-beta202510291556 → 0.9.1-feat-swiper202511031535

package/src/components/Swiper/SwiperPagerView.tsx

@@ -0,0 +1,286 @@
+import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { StyleSheet } from "react-native";
+import PagerView from "react-native-pager-view";
+import type { PagerViewOnPageSelectedEvent, PageScrollStateChangedNativeEvent } from "react-native-pager-view";
+import { LazyPage } from "./LazyPage";
+import type { SwiperProps, SwiperRef } from "./types";
+import { prepareInfiniteData, shouldJumpForInfinite, getRealIndex, getDisplayIndex } from "./utils";
+
+/**
+ * PagerView-based Swiper implementation
+ */
+function SwiperPagerViewComponent<T>(props: SwiperProps<T>, ref: React.Ref<SwiperRef>) {
+  const {
+    data,
+    renderItem,
+    keyExtractor,
+    infinite = false,
+    initialPage = 0,
+    cloneCount = 2,
+    lazyMountWindow = 2,
+    removeClippedPages = false,
+    unmountThreshold,
+    onPageChange,
+    onNext,
+    onPrev,
+    onPageScrollStateChanged,
+    style,
+    pageMargin,
+    offscreenPageLimit,
+    scrollEnabled = true,
+    overdrag,
+    renderPlaceholder,
+  } = props;
+
+  // Refs
+  const pagerRef = useRef<PagerView>(null);
+  const currentPageRef = useRef<number>(initialPage);
+  const isJumpingRef = useRef<boolean>(false);
+  const pendingJumpRef = useRef<number | null>(null);
+  const scrollStateRef = useRef<"idle" | "dragging" | "settling">("idle");
+
+  // State
+  const [currentPage, setCurrentPage] = useState(initialPage);
+  const [mountedPages, setMountedPages] = useState<Set<number>>(new Set());
+  const [unmountPages, setUnmountPages] = useState<Set<number>>(new Set());
+
+  // Prepare data for infinite scrolling
+  const {
+    displayData,
+    offset,
+    cloneCount: actualCloneCount,
+  } = useMemo(() => {
+    return prepareInfiniteData(data, infinite, cloneCount);
+  }, [data, infinite, cloneCount]);
+
+  // Calculate adjusted initial page for infinite mode
+  const adjustedInitialPage = useMemo(() => {
+    return infinite ? getDisplayIndex(initialPage, offset) : initialPage;
+  }, [infinite, initialPage, offset]);
+
+  /**
+   * Update which pages should be mounted/unmounted based on current page
+   */
+  const updateMountedPages = useCallback(
+    (centerPage: number) => {
+      const newMounted = new Set<number>();
+      const newUnmount = new Set<number>();
+
+      // Scale mount window with clone count for better fast scrolling
+      const effectiveMountWindow = Math.max(lazyMountWindow, Math.min(10, Math.ceil(actualCloneCount / 10)));
+
+      // Calculate unmount threshold (default: 3x mount window)
+      const effectiveUnmountThreshold = unmountThreshold ?? effectiveMountWindow * 3;
+
+      // Mount pages within the window
+      for (let i = centerPage - effectiveMountWindow; i <= centerPage + effectiveMountWindow; i++) {
+        if (i >= 0 && i < displayData.length) {
+          newMounted.add(i);
+        }
+      }
+
+      // Mark pages for unmounting if removeClippedPages is enabled
+      if (removeClippedPages) {
+        for (let i = 0; i < displayData.length; i++) {
+          const distance = Math.abs(i - centerPage);
+          if (distance > effectiveUnmountThreshold) {
+            newUnmount.add(i);
+          }
+        }
+      }
+
+      console.log("Mounted pages:", Array.from(newMounted));
+      console.log("Unmount pages:", Array.from(newUnmount));
+
+      setMountedPages(newMounted);
+      setUnmountPages(newUnmount);
+    },
+    [lazyMountWindow, displayData.length, actualCloneCount, unmountThreshold, removeClippedPages],
+  );
+
+  /**
+   * Handle page selection from PagerView
+   */
+  const handlePageSelected = useCallback(
+    (event: PagerViewOnPageSelectedEvent) => {
+      const newDisplayPage = event.nativeEvent.position;
+
+      if (isJumpingRef.current) {
+        return;
+      }
+
+      const realIndex = getRealIndex(newDisplayPage, offset, data.length);
+      const prevDisplayPage = currentPageRef.current;
+
+      setCurrentPage(realIndex);
+      currentPageRef.current = newDisplayPage;
+
+      updateMountedPages(newDisplayPage);
+
+      onPageChange?.(realIndex);
+
+      if (newDisplayPage > prevDisplayPage) {
+        onNext?.(realIndex);
+      } else if (newDisplayPage < prevDisplayPage) {
+        onPrev?.(realIndex);
+      }
+
+      // Handle infinite scroll jump
+      if (infinite && data.length >= 3) {
+        const jumpResult = shouldJumpForInfinite(newDisplayPage, data.length, offset, actualCloneCount);
+
+        if (jumpResult.shouldJump && jumpResult.jumpTo !== undefined) {
+          pendingJumpRef.current = jumpResult.jumpTo;
+        }
+      }
+    },
+    [data.length, offset, actualCloneCount, infinite, onPageChange, onNext, onPrev, updateMountedPages],
+  );
+
+  /**
+   * Handle scroll state changes
+   */
+  const handlePageScrollStateChanged = useCallback(
+    (event: PageScrollStateChangedNativeEvent) => {
+      const state = event.nativeEvent.pageScrollState;
+      scrollStateRef.current = state;
+      onPageScrollStateChanged?.(state);
+
+      // Execute pending jump when scroll becomes idle
+      if (state === "idle" && pendingJumpRef.current !== null) {
+        const targetPage = pendingJumpRef.current;
+        pendingJumpRef.current = null;
+
+        isJumpingRef.current = true;
+
+        requestAnimationFrame(() => {
+          pagerRef.current?.setPageWithoutAnimation(targetPage);
+          currentPageRef.current = targetPage;
+
+          setTimeout(() => {
+            isJumpingRef.current = false;
+          }, 50);
+        });
+      }
+    },
+    [onPageScrollStateChanged],
+  );
+
+  /**
+   * Initialize mounted pages on mount
+   */
+  useEffect(() => {
+    updateMountedPages(adjustedInitialPage);
+  }, [adjustedInitialPage, updateMountedPages]);
+
+  /**
+   * Expose ref methods for programmatic control
+   */
+  useImperativeHandle(
+    ref,
+    () => ({
+      goToPage: (index: number, animated = true) => {
+        const clampedIndex = Math.max(0, Math.min(index, data.length - 1));
+        const displayIndex = infinite ? getDisplayIndex(clampedIndex, offset) : clampedIndex;
+
+        if (animated) {
+          pagerRef.current?.setPage(displayIndex);
+        } else {
+          pagerRef.current?.setPageWithoutAnimation(displayIndex);
+        }
+      },
+
+      next: (animated = true) => {
+        const nextPage = currentPage + 1;
+
+        if (infinite) {
+          const displayIndex = getDisplayIndex(nextPage % data.length, offset);
+          if (animated) {
+            pagerRef.current?.setPage(currentPageRef.current + 1);
+          } else {
+            pagerRef.current?.setPageWithoutAnimation(currentPageRef.current + 1);
+          }
+        } else {
+          if (nextPage < data.length) {
+            if (animated) {
+              pagerRef.current?.setPage(nextPage);
+            } else {
+              pagerRef.current?.setPageWithoutAnimation(nextPage);
+            }
+          }
+        }
+      },
+
+      prev: (animated = true) => {
+        const prevPage = currentPage - 1;
+
+        if (infinite) {
+          const displayIndex = getDisplayIndex((prevPage + data.length) % data.length, offset);
+          if (animated) {
+            pagerRef.current?.setPage(currentPageRef.current - 1);
+          } else {
+            pagerRef.current?.setPageWithoutAnimation(currentPageRef.current - 1);
+          }
+        } else {
+          if (prevPage >= 0) {
+            if (animated) {
+              pagerRef.current?.setPage(prevPage);
+            } else {
+              pagerRef.current?.setPageWithoutAnimation(prevPage);
+            }
+          }
+        }
+      },
+
+      getCurrentPage: () => currentPage,
+    }),
+    [currentPage, data.length, infinite, offset],
+  );
+
+  // Handle empty data
+  if (data.length === 0) {
+    return null;
+  }
+
+  return (
+    <PagerView
+      ref={pagerRef}
+      style={[styles.pager, style]}
+      initialPage={adjustedInitialPage}
+      onPageSelected={handlePageSelected}
+      onPageScrollStateChanged={handlePageScrollStateChanged}
+      pageMargin={pageMargin}
+      offscreenPageLimit={offscreenPageLimit}
+      scrollEnabled={scrollEnabled}
+      overdrag={overdrag}
+    >
+      {displayData.map((item, displayIndex) => {
+        const realIndex = getRealIndex(displayIndex, offset, data.length);
+        const shouldMount = mountedPages.has(displayIndex);
+        const shouldUnmount = unmountPages.has(displayIndex);
+        const key = keyExtractor?.(item, realIndex) ?? `swiper-page-${displayIndex}`;
+
+        return (
+          <LazyPage
+            key={key}
+            shouldMount={shouldMount}
+            shouldUnmount={shouldUnmount}
+            placeholder={renderPlaceholder?.(realIndex)}
+          >
+            {renderItem(item, realIndex)}
+          </LazyPage>
+        );
+      })}
+    </PagerView>
+  );
+}
+
+const styles = StyleSheet.create({
+  pager: {
+    flex: 1,
+  },
+});
+
+export const SwiperPagerView = forwardRef(SwiperPagerViewComponent) as <T>(
+  props: SwiperProps<T> & { ref?: React.Ref<SwiperRef> },
+) => React.ReactElement;

package/src/components/Swiper/demo/index.tsx

@@ -0,0 +1,146 @@
+import React, { useRef, useState } from "react";
+import { View, Text, StyleSheet, ScrollView, Image, TouchableOpacity } from "react-native";
+import { Swiper } from "@xhs/reds-rn-next";
+import type { SwiperRef } from "@xhs/reds-rn-next";
+
+const styles = StyleSheet.create({
+  container: {
+    paddingBottom: 100,
+  },
+  swiper: {
+    height: 300,
+    width: "100%",
+  },
+  page: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  pageText: {
+    fontSize: 24,
+    fontWeight: "bold",
+    color: "#fff",
+  },
+  controls: {
+    flexDirection: "row",
+    justifyContent: "center",
+    gap: 10,
+    marginTop: 20,
+  },
+  button: {
+    backgroundColor: "#007AFF",
+    padding: 10,
+    borderRadius: 5,
+  },
+  buttonText: {
+    color: "#fff",
+    fontWeight: "600",
+  },
+  section: {
+    marginBottom: 30,
+  },
+  sectionTitle: {
+    fontSize: 16,
+    fontWeight: "600",
+    marginBottom: 10,
+    paddingHorizontal: 16,
+  },
+});
+
+const colors = ["#FF6B6B", "#4ECDC4", "#45B7D1", "#FFA07A", "#98D8C8"];
+
+const images = [
+  "https://picasso-static.xiaohongshu.com/fe-platform/c699a29f67e6f8b01355d1b0d30ddbcd35795991.png",
+  "https://picasso-static.xiaohongshu.com/fe-platform/84f5deb8733b7f6c04a858162c40632a2777e98d.png",
+  "https://picasso-static.xiaohongshu.com/fe-platform/1ea6cde32ec6af0a5886eaf7fd9351cacaaa00dd.png",
+];
+
+export default function SwiperDemo() {
+  const [currentPage, setCurrentPage] = useState(0);
+  const swiperRef = useRef<SwiperRef>(null);
+
+  return (
+    <ScrollView contentContainerStyle={styles.container}>
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Basic Swiper</Text>
+        <Swiper
+          data={colors}
+          renderItem={(color, index) => (
+            <View style={[styles.page, { backgroundColor: color }]}>
+              <Text style={styles.pageText}>Page {index + 1}</Text>
+            </View>
+          )}
+          style={styles.swiper}
+          onPageChange={(index) => setCurrentPage(index)}
+        />
+        <Text style={{ textAlign: "center", marginTop: 10 }}>Current Page: {currentPage + 1}</Text>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Infinite Scroll</Text>
+        <Swiper
+          data={colors.slice(0, 3)}
+          renderItem={(color, index) => (
+            <View style={[styles.page, { backgroundColor: color }]}>
+              <Text style={styles.pageText}>Infinite Page {index + 1}</Text>
+            </View>
+          )}
+          style={styles.swiper}
+          infinite={true}
+        />
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>With Images</Text>
+        <Swiper
+          data={images}
+          renderItem={(url) => (
+            <Image source={{ uri: url }} style={{ width: "100%", height: "100%" }} resizeMode="cover" />
+          )}
+          style={styles.swiper}
+        />
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Controlled Swiper</Text>
+        <Swiper
+          ref={swiperRef}
+          data={colors}
+          renderItem={(color, index) => (
+            <View style={[styles.page, { backgroundColor: color }]}>
+              <Text style={styles.pageText}>Controlled {index + 1}</Text>
+            </View>
+          )}
+          style={styles.swiper}
+          initialPage={1}
+        />
+        <View style={styles.controls}>
+          <TouchableOpacity style={styles.button} onPress={() => swiperRef.current?.prev()}>
+            <Text style={styles.buttonText}>Previous</Text>
+          </TouchableOpacity>
+          <TouchableOpacity style={styles.button} onPress={() => swiperRef.current?.goToPage(0)}>
+            <Text style={styles.buttonText}>First</Text>
+          </TouchableOpacity>
+          <TouchableOpacity style={styles.button} onPress={() => swiperRef.current?.next()}>
+            <Text style={styles.buttonText}>Next</Text>
+          </TouchableOpacity>
+        </View>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>FlatList Implementation</Text>
+        <Swiper
+          data={colors}
+          renderItem={(color, index) => (
+            <View style={[styles.page, { backgroundColor: color }]}>
+              <Text style={styles.pageText}>FlatList {index + 1}</Text>
+            </View>
+          )}
+          style={styles.swiper}
+          implementation="flatlist"
+          infinite={true}
+        />
+      </View>
+    </ScrollView>
+  );
+}

package/src/components/Swiper/doc/index.mdx

@@ -0,0 +1,49 @@
+import BaseDemo from "!!raw-loader!../demo/index.tsx";
+
+## 演示
+
+### 基础用法
+
+::BaseDemo::
+
+## API
+
+### Props
+
+| 属性               | 描述                                | 类型                                  | 默认值      |
+| ------------------ | ----------------------------------- | ------------------------------------- | ----------- |
+| data               | 数据数组                            | T[]                                   | -           |
+| renderItem         | 渲染每一项的函数                    | (item: T, index: number) => ReactNode | -           |
+| keyExtractor       | 列表项的 key 提取函数               | (item: T, index: number) => string    | -           |
+| infinite           | 是否启用无限/循环滚动               | boolean                               | false       |
+| initialPage        | 初始显示的页面索引                  | number                                | 0           |
+| implementation     | 实现方式: 'pagerView' 或 'flatlist' | 'pagerView' | 'flatlist'         | 'pagerView' |
+| cloneCount         | 无限滚动时每端克隆的项数            | number                                | 2           |
+| lazyMountWindow    | 当前页面每侧加载的页面数            | number                                | 2           |
+| removeClippedPages | 是否卸载远离当前位置的页面          | boolean                               | false       |
+| unmountThreshold   | 卸载页面的距离阈值                  | number                                | -           |
+| style              | 容器样式                            | ViewStyle                             | -           |
+| pageMargin         | 页面间距 (仅 Android)               | number                                | -           |
+| scrollEnabled      | 是否可滚动                          | boolean                               | true        |
+| overdrag           | 允许过度拖拽效果                    | boolean                               | -           |
+| offscreenPageLimit | 离屏保留页面数 (仅 Android)         | number                                | -           |
+| renderPlaceholder  | 未加载页面的占位符组件              | (index: number) => ReactNode          | -           |
+
+### Events
+
+| 事件                     | 描述                             | 类型                                                        |
+| ------------------------ | -------------------------------- | ----------------------------------------------------------- |
+| onPageChange             | 页面切换时触发                   | (index: number) => void                                     |
+| onNext                   | 滑动到下一页时触发               | (index: number) => void                                     |
+| onPrev                   | 滑动到上一页时触发               | (index: number) => void                                     |
+| onPageScrollStateChanged | 滚动状态变化时触发               | (state: 'idle' | 'dragging' | 'settling') => void |
+| onScrollEndDrag          | 用户释放拖拽时触发 (仅 FlatList) | (index: number) => void                                     |
+
+### Ref Methods
+
+| 方法           | 描述             | 类型                                        |
+| -------------- | ---------------- | ------------------------------------------- |
+| goToPage       | 跳转到指定页面   | (index: number, animated?: boolean) => void |
+| next           | 跳转到下一页     | (animated?: boolean) => void                |
+| prev           | 跳转到上一页     | (animated?: boolean) => void                |
+| getCurrentPage | 获取当前页面索引 | () => number                                |

package/src/components/Swiper/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Swiper - A performant, data-driven carousel component
+ *
+ * @example
+ * ```tsx
+ * import { Swiper, SwiperRef } from '@/components/Swiper'
+ *
+ * const swiperRef = useRef<SwiperRef>(null)
+ *
+ * <Swiper
+ *   ref={swiperRef}
+ *   data={items}
+ *   renderItem={(item, index) => <ItemCard item={item} />}
+ *   infinite
+ *   onPageChange={(index) => console.log('Page:', index)}
+ * />
+ *
+ * // Programmatic control
+ * swiperRef.current?.next()
+ * swiperRef.current?.goToPage(5)
+ * ```
+ */
+
+export { Swiper } from "./Swiper";
+export type { SwiperProps, SwiperRef } from "./types";