This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

一个与 react-native-pager-view API 兼容的 PagerView 组件。它封装了平台特定的 @expo/ui 原语：在 Android 上使用 Jetpack Compose 的 HorizontalPager，在 iOS 上使用分页式 SwiftUI ScrollView。每个子元素都会成为一个单独的页面，并拉伸以填满分页器。

如果你需要对平台特定的分页行为或修饰器进行更底层的控制，请直接使用原生原语。在 iOS 上，使用 page 样式的 TabView 也会渲染一个水平分页器，并且在你想使用 SwiftUI 内置页面指示器时可能更合适。

Android

iOS

安装

If you are installing this in an existing React Native app, make sure to install expo in your project.

如果你需要以下任一功能，可以选择安装 react-native-worklets：

• iOS 上带动画的 setPage。 没有 worklets 时，iOS 的 setPage 会退回为无动画跳转。Android 无论如何都会有动画。
• 每帧、保持在 UI 线程上的 onPageScroll 回调。 当你的 onPageScroll 处理函数本身就是一个 worklet 时，它会在 UI 线程上每一帧同步运行，而不是切回 JS。没有 worklets 时，回调仍然会触发——只是会在 JS 线程上运行。

从 react-native-pager-view 迁移

通过从 @expo/ui/community/pager-view 导入 PagerView 来更新导入语句：

import PagerView from 'react-native-pager-view';
// 变为：
import PagerView from '@expo/ui/community/pager-view';

在切换之前，你应该了解以下变化：

• 不支持 orientation="vertical"、keyboardDismissMode、overdrag 和 overScrollMode。
• 不提供 usePagerView 钩子——请改用 ref。
• 在 iOS 上，onPageScroll 和 onPageScrollStateChanged 仅会在 iOS 18 及以上版本触发。

完整列表请参见平台行为。

基本用法

PagerViewExample.tsx

Copy

import { useRef } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import PagerView, { type PagerViewRef } from '@expo/ui/community/pager-view';

export default function PagerViewExample() {
  const pagerRef = useRef<PagerViewRef>(null);

  return (
    <View style={{ flex: 1 }}>
      <PagerView
        ref={pagerRef}
        style={{ flex: 1 }}
        initialPage={0}
        onPageSelected={event => {
          console.log('selected page', event.nativeEvent.position);
        }}>
        <View key="one" style={[styles.page, { backgroundColor: '#fde68a' }]}>
          <Text>第 1 页</Text>
        </View>
        <View key="two" style={[styles.page, { backgroundColor: '#bfdbfe' }]}>
          <Text>第 2 页</Text>
        </View>
        <View key="three" style={[styles.page, { backgroundColor: '#bbf7d0' }]}>
          <Text>第 3 页</Text>
        </View>
      </PagerView>

      <Button title="前往第 2 页" onPress={() => pagerRef.current?.setPage(1)} />
    </View>
  );
}

const styles = StyleSheet.create({
  page: { flex: 1, alignItems: 'center', justifyContent: 'center' },
});

Android

iOS

平台行为

Web 不受支持，在 web 上渲染 PagerView 会在运行时抛出错误。

与上游 react-native-pager-view 的其他差异：

• 不支持 orientation="vertical"、keyboardDismissMode、overdrag 和 overScrollMode。仅支持水平分页，其余选项会回退到平台分页器的默认值。
• 不提供 usePagerView 钩子。请使用 PagerView 的 ref 来访问 setPage、setPageWithoutAnimation 和 setScrollEnabled。
• setScrollEnabled 会触发重新渲染，使新值作为 prop 传递到原生视图。它仍然适用于从非 React 上下文中切换，例如基于 ref 的手势处理器。
• borderRadius 样式在两个平台上都生效。在 Android 上，只有数值才会裁剪分页器。底层的 Compose 宿主会静默忽略字符串值，例如 '50%'。

API

import PagerView from '@expo/ui/community/pager-view';

Component

Types