This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

ScrollView

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

iOS

tvOS

Included in Expo Go

GitHub

npm

更新日志

有关跨平台使用，请参阅通用的 ScrollView — 它会针对每个平台渲染相应的原生组件。

Expo UI ScrollView 与官方 SwiftUI ScrollView API 保持一致，并为其子元素提供一个可滚动容器。

安装

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.

用法

基本垂直滚动视图

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

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 })]}>
              {`项目 ${i + 1}`}
            </Text>
          ))}
        </VStack>
      </ScrollView>
    </Host>
  );
}

水平滚动视图

使用 axes 属性进行水平滚动。

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>
  );
}

隐藏滚动指示器

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

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}>{`项目 ${i + 1}`}</Text>
          ))}
        </VStack>
      </ScrollView>
    </Host>
  );
}

共享滚动位置

需要 iOS 17 或更高版本。在较旧的版本上，该修饰符不会产生任何作用。

从 JavaScript 跟踪领先的滚动目标 id，并通过写入状态来滚动到某个目标。为每个滚动目标添加 id 修饰符，将内容容器包裹在 scrollTargetLayout 中，并将 scrollPosition 修饰符应用到 ScrollView。可选的 onChange 回调会在领先目标发生变化时在 JS 线程上触发。

scrollPosition 修饰符也适用于其他可滚动容器，例如 LazyVStack 和 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="从 worklet 滚动到 item 10"
          onPress={() => {
            scheduleOnUI(() => {
              'worklet';
              activeID.value = 'item-10';
            });
          }}
        />
      </VStack>
    </Host>
  );
}

未裁剪的滚动内容

需要 iOS 17 或更高版本。在较旧的版本上，该修饰符不会产生任何作用。

滚动视图会将其内容裁剪到自身边界，超出边界绘制的内容（例如阴影或超出边缘放大的卡片）会被截断。应用 scrollClipDisabled 修饰符以保持这些内容可见。

ScrollViewUnclippedExample.tsx

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

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

API

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

Component

`ScrollView`

iOS

tvOS

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`

iOS

tvOS

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

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

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

`children`

iOS

tvOS

Type: ReactNode

`showsIndicators`

iOS

tvOS

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`

iOS

tvOS

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`

iOS

tvOS

Literal type: string

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

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