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。每个子项都会变成独立的页面，并拉伸以填充分页器。

🌐 A PagerView component with an API compatible with react-native-pager-view. It wraps the platform-specific @expo/ui primitives: Jetpack Compose HorizontalPager on Android and a paged SwiftUI ScrollView on iOS. Each child becomes a separate page and stretches to fill the pager.

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

🌐 If you need lower-level control over platform-specific paging behavior or modifiers, use the native primitives directly. On iOS, TabView with the page style also renders a horizontal pager and may fit better when you want SwiftUI's built-in page indicators.

安装

🌐 Installation

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

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

🌐 Optionally, install react-native-worklets if you need either of the following:

• iOS 上的动画 setPage。 如果没有 worklets，iOS 的 setPage 会退回到非动画跳转。无论如何，Android 都会进行动画。
• 每帧 onPageScroll 回调保持在 UI 线程上。 当你的 onPageScroll 处理程序本身是一个 worklet 时，它会在每一帧上同步运行在 UI 线程上，而不是切换到 JS。没有 worklets 的情况下，回调仍然会触发——只是它在 JS 线程上运行。

从 react-native-pager-view 迁移

🌐 Migrating from react-native-pager-view

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

🌐 Update the import statement by importing PagerView from @expo/ui/community/pager-view:

import PagerView from 'react-native-pager-view';
// becomes:
import PagerView from '@expo/ui/community/pager-view';

在你交换之前，你应该了解会发生哪些变化：

🌐 Before you swap, you should know what changes:

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

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

🌐 See Platform behavior for the full list.

基本用法

🌐 Basic usage

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>Page one</Text>
        </View>
        <View key="two" style={[styles.page, { backgroundColor: '#bfdbfe' }]}>
          <Text>Page two</Text>
        </View>
        <View key="three" style={[styles.page, { backgroundColor: '#bbf7d0' }]}>
          <Text>Page three</Text>
        </View>
      </PagerView>

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

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

平台行为

🌐 Platform behavior

Web 不被支持，在 web 上渲染 PagerView 会在运行时抛出异常。

🌐 Web is not supported and rendering PagerView on web throws at runtime.

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

🌐 Additional differences from upstream react-native-pager-view:

• orientation="vertical"、keyboardDismissMode、overdrag 和 overScrollMode 不受支持。仅支持水平分页，其他将回退到平台分页器的默认设置。
• usePagerView 钩子未提供。请使用 ref 到 PagerView 来访问 setPage、setPageWithoutAnimation 和 setScrollEnabled。
• setScrollEnabled 会触发重新渲染，因此新值会作为属性传递到原生视图。对于从非 React 上下文（例如基于 ref 的手势处理器）进行切换仍然很有用。
• borderRadius 样式在两个平台上都适用。在 Android 上，只有数值会裁剪分页器。底层的 Compose 主机会静默丢弃诸如 '50%' 这样的字符串值。

应用接口

🌐 API

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

Component

Types