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

HorizontalPager

用于可滑动页面的 Jetpack Compose HorizontalPager 组件。

Android
Included in Expo Go
Recommended version:
~58.0.15

Expo UI HorizontalPager 与 Jetpack Compose 的 HorizontalPager 相匹配——一个水平滚动的分页器,可固定到单个页面。

HorizontalPager 不会自动设置高度——可以用 height 修饰符给它一个高度,或者把它放在有固定高度的父容器里。

HorizontalPager showing the second of three pages with a page indicator belowHorizontalPager showing the second of three pages with a page indicator below

安装

🌐 Installation

Terminal
- npx expo install @expo/ui
- yarn expo install @expo/ui
- pnpm expo install @expo/ui
- bun expo install @expo/ui

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

用法

🌐 Usage

失控的

🌐 Uncontrolled

分页器本地拥有其滚动位置。使用 initialPage 选择起始页,并使用 onCurrentPageChange(在刷卡过程中目标页翻转时触发)或 onSettledPageChange(仅在刷卡结束后触发)监听变化。

🌐 The pager owns its scroll position natively. Use initialPage to pick the starting page, and listen for changes with onCurrentPageChange (fires mid-swipe as the snap target flips) or onSettledPageChange (fires only after the swipe settles).

UncontrolledPagerExample.tsx
import { Box, Column, Host, HorizontalPager, Text, useMaterialColors, } from '@expo/ui/jetpack-compose'; import { background, fillMaxSize, fillMaxWidth, height, } from '@expo/ui/jetpack-compose/modifiers'; import { useState } from 'react'; export default function UncontrolledPagerExample() { const colors = useMaterialColors(); const [currentPage, setCurrentPage] = useState(1); const [settledPage, setSettledPage] = useState(1); return ( <Host matchContents={{ vertical: true }} style={{ width: '100%' }}> <Column verticalArrangement={{ spacedBy: 12 }} modifiers={[fillMaxWidth()]}> <Text style={{ typography: 'titleLarge' }} color={colors.onBackground}> currentPage: {currentPage} · settledPage: {settledPage} </Text> <HorizontalPager initialPage={1} onCurrentPageChange={setCurrentPage} onSettledPageChange={setSettledPage} modifiers={[fillMaxWidth(), height(240)]}> <Page label="Page 1" color="#6200EE" /> <Page label="Page 2" color="#03DAC5" /> <Page label="Page 3" color="#FF5722" /> </HorizontalPager> </Column> </Host> ); } function Page({ label, color }: { label: string; color: string }) { return ( <Box modifiers={[fillMaxSize(), background(color)]} contentAlignment="center"> <Text color="#FFFFFF" style={{ typography: 'headlineLarge' }}> {label} </Text> </Box> ); }

编程导航

🌐 Programmatic navigation

附加一个 ref 并在其上调用 animateScrollToPage 或 scrollToPage。这些对应 Compose 的 PagerState.animateScrollToPage 和 PagerState.scrollToPage。

🌐 Attach a ref and call animateScrollToPage or scrollToPage on it. These mirror Compose's PagerState.animateScrollToPage and PagerState.scrollToPage.

ProgrammaticPagerExample.tsx
import { Box, Button, Column, Host, HorizontalPager, type HorizontalPagerHandle, Row, Text, useMaterialColors, } from '@expo/ui/jetpack-compose'; import { background, fillMaxSize, fillMaxWidth, height, } from '@expo/ui/jetpack-compose/modifiers'; import { useRef, useState } from 'react'; const PAGE_COUNT = 5; export default function ProgrammaticPagerExample() { const colors = useMaterialColors(); const pagerRef = useRef<HorizontalPagerHandle>(null); const [page, setPage] = useState(0); return ( <Host matchContents={{ vertical: true }} style={{ width: '100%' }}> <Column verticalArrangement={{ spacedBy: 12 }} modifiers={[fillMaxWidth()]}> <Text style={{ typography: 'titleLarge' }} color={colors.onBackground}> Page {page + 1} / {PAGE_COUNT} </Text> <HorizontalPager ref={pagerRef} onSettledPageChange={setPage} modifiers={[fillMaxWidth(), height(200)]}> {Array.from({ length: PAGE_COUNT }).map((_, i) => ( <Page key={i} label={`Page ${i + 1}`} color={COLORS[i]} /> ))} </HorizontalPager> <Row horizontalArrangement={{ spacedBy: 8 }}> <Button onClick={() => pagerRef.current?.animateScrollToPage( Math.max(0, page - 1) ) }> <Text>Prev</Text> </Button> <Button onClick={() => pagerRef.current?.animateScrollToPage( Math.min(PAGE_COUNT - 1, page + 1) ) }> <Text>Next</Text> </Button> <Button onClick={() => pagerRef.current?.scrollToPage(0)}> <Text>Jump to first</Text> </Button> </Row> </Column> </Host> ); } const COLORS = [ '#6200EE', '#03DAC5', '#FF5722', '#4CAF50', '#2196F3', ]; function Page({ label, color }: { label: string; color: string }) { return ( <Box modifiers={[fillMaxSize(), background(color)]} contentAlignment="center"> <Text color="#FFFFFF" style={{ typography: 'headlineLarge' }}> {label} </Text> </Box> ); }

页面间距和内容填充

🌐 Page spacing and content padding

使用 pageSpacing 在页面之间添加间隙(在滑动时可见),使用 contentPadding 插入分页器,以便在静止时邻近的页面可见。

🌐 Use pageSpacing to add a gap between pages (visible during swipe) and contentPadding to inset the pager so neighboring pages peek at rest.

PagerLayoutExample.tsx
import { Box, Host, HorizontalPager, Text, } from '@expo/ui/jetpack-compose'; import { background, fillMaxSize, fillMaxWidth, height, } from '@expo/ui/jetpack-compose/modifiers'; export default function PagerLayoutExample() { return ( <Host matchContents={{ vertical: true }} style={{ width: '100%' }}> <HorizontalPager pageSpacing={12} contentPadding={{ start: 32, end: 32 }} modifiers={[fillMaxWidth(), height(180)]}> <Page label="Page 1" color="#6200EE" /> <Page label="Page 2" color="#03DAC5" /> <Page label="Page 3" color="#FF5722" /> </HorizontalPager> </Host> ); } function Page({ label, color }: { label: string; color: string }) { return ( <Box modifiers={[fillMaxSize(), background(color)]} contentAlignment="center"> <Text color="#FFFFFF" style={{ typography: 'headlineLarge' }}> {label} </Text> </Box> ); }

应用接口

🌐 API

import { HorizontalPager } from '@expo/ui/jetpack-compose';

No API data file found, sorry!