ScrollView

用于可滚动内容的 SwiftUI ScrollView 组件。

iOS

tvOS

Included in Expo Go

Recommended version:

~57.0.3

信息有关跨平台使用，请参阅通用 ScrollView —— 它会根据平台呈现相应的原生组件。

Expo UI ScrollView 与官方 SwiftUI ScrollView API 相匹配，并为其子元素提供可滚动的容器。

🌐 Expo UI ScrollView matches the official SwiftUI ScrollView API and provides a scrollable container for its children.

安装

🌐 Installation

Terminal

- npx expo install @expo/ui

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

用法

🌐 Usage

基本垂直滚动视图

🌐 Basic vertical scroll view

一个简单的垂直可滚动文本项列表。

🌐 A simple vertically scrollable list of text items.

ScrollViewVerticalExample.tsx

import { Host, ScrollView, VStack, Text } from '@expo/ui/swift-ui';
import { padding } from '@expo/ui/swift-ui/modifiers';

export default function ScrollViewVerticalExample() {
  return (
    <Host style={{ flex: 1 }}>
      <ScrollView>
        <VStack spacing={8}>
          {Array.from({ length: 30 }, (_, i) => (
            <Text key={i} modifiers={[padding({ horizontal: 16 })]}>
              {`Item ${i + 1}`}
            </Text>
          ))}
        </VStack>
      </ScrollView>
    </Host>
  );
}

水平滚动视图

🌐 Horizontal scroll view

使用 axes 属性来水平滚动。

🌐 Use the axes prop to scroll horizontally.

ScrollViewHorizontalExample.tsx

import { Host, ScrollView, HStack, RoundedRectangle } from '@expo/ui/swift-ui';
import { frame, foregroundStyle } from '@expo/ui/swift-ui/modifiers';

export default function ScrollViewHorizontalExample() {
  return (
    <Host style={{ flex: 1 }}>
      <ScrollView axes="horizontal">
        <HStack spacing={8}>
          {Array.from({ length: 20 }, (_, i) => (
            <RoundedRectangle
              key={i}
              cornerRadius={12}
              modifiers={[
                frame({ width: 100, height: 100 }),
                foregroundStyle(`hsl(${i * 18}, 70%, 50%)`),
              ]}
            />
          ))}
        </HStack>
      </ScrollView>
    </Host>
  );
}

隐藏的滚动指示器

🌐 Hidden scroll indicators

将 showsIndicators 设置为 false 以隐藏滚动条。

🌐 Set showsIndicators to false to hide the scroll bars.

ScrollViewHiddenIndicatorsExample.tsx

import { Host, ScrollView, VStack, Text } from '@expo/ui/swift-ui';

export default function ScrollViewHiddenIndicatorsExample() {
  return (
    <Host style={{ flex: 1 }}>
      <ScrollView showsIndicators={false}>
        <VStack spacing={8}>
          {Array.from({ length: 30 }, (_, i) => (
            <Text key={i}>{`Item ${i + 1}`}</Text>
          ))}
        </VStack>
      </ScrollView>
    </Host>
  );
}

共享滚动位置

🌐 Shared scroll position

信息需要 iOS 17 或更高版本。在旧版本上，该修饰符无效。

从 JavaScript 跟踪主要滚动目标 id，并通过写入状态滚动到目标。用 id 修饰符标记每个滚动目标，将内容容器封装在 scrollTargetLayout 中，并将 scrollPosition 修饰符应用到 ScrollView 上。当主要目标变化时，可选的 onChange 回调会在 JS 线程上触发。

🌐 Track the leading scroll target id from JavaScript and scroll to a target by writing to the state. Mark each scroll target with the id modifier, wrap the content container in scrollTargetLayout, and apply the scrollPosition modifier to the ScrollView. The optional onChange callback fires on the JS thread when the leading target changes.

scrollPosition 修饰符也适用于其他可滚动的容器，如 LazyVStack 和 LazyHStack。

🌐 The scrollPosition modifier also works on other scrollable containers like LazyVStack and LazyHStack.

警告对 state.value 的写入必须在 UI 运行时执行。将写入操作封装在来自 react-native-worklets 的 scheduleOnUI 中，或者在 'worklet' 函数内部调用它们。从 JS 运行时进行的写入会触发 Main Thread Checker，这是 Xcode 的运行时工具，用于标记从后台线程发出的 UIKit 调用。

ScrollViewSharedPositionExample.tsx

import { Button, Host, ScrollView, Text, VStack, useNativeState } from '@expo/ui/swift-ui';
import { id, padding, scrollPosition, scrollTargetLayout } from '@expo/ui/swift-ui/modifiers';
import { scheduleOnUI } from 'react-native-worklets';

export default function ScrollViewSharedPositionExample() {
  const activeID = useNativeState<string | null>(null);

  return (
    <Host style={{ flex: 1 }}>
      <VStack spacing={12}>
        <ScrollView
          modifiers={[
            scrollPosition(activeID, {
              onChange: newID => {
                console.log('[JS thread] leading target:', newID);
              },
            }),
          ]}>
          <VStack modifiers={[scrollTargetLayout()]}>
            {Array.from({ length: 30 }, (_, i) => (
              <Text
                key={`item-${i}`}
                modifiers={[id(`item-${i}`), padding({ horizontal: 16, vertical: 12 })]}>
                {`Item ${i}`}
              </Text>
            ))}
          </VStack>
        </ScrollView>
        <Button
          label="Scroll to item 10 from worklet"
          onPress={() => {
            scheduleOnUI(() => {
              'worklet';
              activeID.value = 'item-10';
            });
          }}
        />
      </VStack>
    </Host>
  );
}

应用接口

🌐 API

import { ScrollView } from '@expo/ui/swift-ui';

Component

`ScrollView`

Type: React.Element<ScrollViewProps>

SwiftUI ScrollView wrapper. To control scroll position, pair this with the scrollPosition(state, { onChange }) modifier and a useNativeState-backed id. Write state.value = targetId for an instant scroll, or wrap the write in withAnimation(...) from @expo/ui/swift-ui for an animated one.

ScrollViewProps

`axes`

Optional • Literal type: string • Default: 'vertical'

The scrollable axes. Pass 'both' to enable 2D (horizontal + vertical) scrolling.

Acceptable values are: 'vertical' | 'horizontal' | 'both'

`children`

Type: ReactNode

`showsIndicators`

Optional • Type: boolean • Default: true

Whether to show scroll indicators. For richer visibility control (e.g. 'never') or per-axis control, use the scrollIndicators(...) modifier instead.

Inherited Props

CommonViewModifierProps

Types

`ScrollGeometry`

Snapshot of a ScrollView's scroll geometry, emitted by the useScrollGeometryChange(...) and onScrollPhaseChange(...) modifiers (iOS 18+).

Property	Type	Description
containerHeight	`number`	Height of the visible scroll container, in points.
containerWidth	`number`	Width of the visible scroll container, in points.
contentHeight	`number`	Total height of the scrollable content, in points.
contentOffsetX	`number`	Horizontal content offset, in points.
contentOffsetY	`number`	Vertical content offset, in points.
contentWidth	`number`	Total width of the scrollable content, in points.

`ScrollPhase`

Literal Type: string

Scroll phase emitted by the onScrollPhaseChange(...) modifier. Mirrors SwiftUI's ScrollPhase (iOS 18+).

Acceptable values are: 'idle' | 'tracking' | 'interacting' | 'animating' | 'decelerating'