可滚动视图#

ScrollView 组件用于在可滚动区域中显示其内容。当用户执行滚动手势时，可视区域会随之更新。你可以通过 axes 属性控制滚动方向，支持垂直、水平或双向滚动。

类型定义#

1type ScrollViewProps = {
2  axes?: AxisSet
3  children?: VirtualNode | VirtualNode[] | (VirtualNode | undefined | null)[]
4}

基本说明#

• 滚动方向由 axes 属性控制。
• 内容通过 children 指定，通常使用如 <VStack>、<HStack> 等布局容器。
• 不支持缩放操作。

默认行为#

• 默认滚动方向为 垂直。
• 滚动指示器根据平台默认行为自动显示，除非通过 modifier 显式设置。

示例#

1<ScrollView>
2  <VStack>
3    {new Array(100).fill('').map((_, index) => (
4      <Text>Row {index}</Text>
5    ))}
6  </VStack>
7</ScrollView>

ScrollView 修饰符说明#

你可以使用以下视图修饰符配置滚动行为：

scrollIndicator#

控制滚动指示器的显示方式。

类型定义#

1scrollIndicator?: ScrollScrollIndicatorVisibility | {
2  visibility: ScrollScrollIndicatorVisibility
3  axes: AxisSet
4}

ScrollScrollIndicatorVisibility 可选值：#

• "automatic"：遵循系统默认行为。
• "visible"：显示指示器，可能会自动隐藏。
• "hidden"：隐藏指示器，除非被系统强制显示。
• "never"：从不显示指示器。

示例#

1<ScrollView scrollIndicator="never">
2  <VStack>{/* 内容 */}</VStack>
3</ScrollView>

设置特定方向的指示器：

1<ScrollView
2  scrollIndicator={{
3    visibility: "hidden",
4    axes: "vertical"
5  }}
6>
7  <VStack>{/* 内容 */}</VStack>
8</ScrollView>

scrollDisabled#

完全禁用滚动行为。

类型定义#

1scrollDisabled?: boolean

示例#

1<ScrollView scrollDisabled>
2  <Text>该滚动视图已被锁定。</Text>
3</ScrollView>

scrollClipDisabled#

控制是否允许内容超出滚动视图边界显示。

类型定义#

1scrollClipDisabled?: boolean

示例#

1<ScrollView scrollClipDisabled>
2  {/* 内容可能会超出滚动区域边界 */}
3</ScrollView>

scrollDismissesKeyboard#

指定滚动行为对软件键盘的影响。

类型定义#

1scrollDismissesKeyboard?: ScrollDismissesKeyboardMode

可选值#

• "automatic"：根据上下文决定默认行为。
• "immediately"：滚动开始时立即关闭键盘。
• "interactively"：允许用户拖动关闭键盘。
• "never"：滚动不会影响键盘。

示例#

1<ScrollView scrollDismissesKeyboard="interactively">
2  {/* 含有输入框的内容 */}
3</ScrollView>

defaultScrollAnchor#

设置初始显示的内容锚点，或内容变化时保持该锚点对齐。

类型定义#

1defaultScrollAnchor?: KeywordPoint | Point

KeywordPoint 关键词#

如 "top"、"bottom"、"leading"、"trailing"、"center"、"topLeading"、"bottomTrailing" 等。

示例#

1<ScrollView defaultScrollAnchor="bottom">
2  <VStack>
3    {/* 新增内容会保持底部对齐 */}
4  </VStack>
5</ScrollView>

AxisSet#

定义滚动方向。

类型定义#

1type AxisSet = 'vertical' | 'horizontal' | 'all'

示例#

1<ScrollView axes="horizontal">
2  <HStack>{/* 横向滚动内容 */}</HStack>
3</ScrollView>

scrollTargetLayout#

用于标记滚动区域中的主要布局容器，便于对齐与滚动控制。

类型定义#

1scrollTargetLayout?: boolean

示例#

1<ScrollView axes="horizontal">
2  <LazyHStack scrollTargetLayout>
3    {items.map(item => <Text>{item.title}</Text>)}
4  </LazyHStack>
5</ScrollView>

scrollTargetBehavior#

定义滚动时如何对齐内容。

类型定义#

1scrollTargetBehavior?: ScrollTargetBehavior

1type ScrollTargetBehavior =
2  | "paging"
3  | "viewAligned"
4  | "viewAlignedLimitAutomatic"
5  | "viewAlignedLimitAlways"
6  | "viewAlignedLimitNever"
7  | "viewAlignedLimitAlwaysByFew"
8  | "viewAlignedLimitAlwaysByOne"

模式说明#

• "paging"：分页滚动，以容器尺寸为单位。
• "viewAligned"：滚动时按视图边界对齐。
• "viewAlignedLimitAutomatic"：在紧凑横向环境下限制滚动数量，其他情况放开。
• "viewAlignedLimitAlways"：始终限制每次滚动的项目数量。
• "viewAlignedLimitNever"：不限制滚动范围。
• "viewAlignedLimitAlwaysByFew" (仅 iOS 18.0+)：每次滚动少量视图。
• "viewAlignedLimitAlwaysByOne" (仅 iOS 18.0+)：每次滚动一个视图。

描述#

用于配置内容滚动对齐策略，适用于横向滚动的列表、分页等场景。

scrollContentBackground#

指定滚动区域的默认背景是否显示。

类型定义#

1scrollContentBackground?: Visibility

可选值#

• "automatic"：根据上下文自动决定是否显示背景。
• "hidden"：隐藏默认背景，可实现透明或自定义背景。
• "visible"：强制显示默认背景，即使已有自定义背景。

示例#

1<List scrollContentBackground="hidden">
2  <Text>这里没有默认背景</Text>
3</List>

总结#