API 参考

SmartRefreshLayout

tsx

import { SmartRefreshLayout } from 'expo-smartrefreshlayout';

组件必须包含且只包含一个 React Native 滚动组件，例如 FlatList、SectionList 或 ScrollView。

Props

属性	类型	默认值	说明
`children`	`ReactElement`	必填	唯一的滚动子组件
`refreshHeader`	`ReactElement`	-	挂载到 Android/iOS 原生刷新 Header 槽位的 React 内容；提供后替代 `headerStyle` 选中的 Classic/Material Header
`refreshEnabled`	`boolean`	是否提供 `onRefresh`	是否允许下拉刷新
`loadMoreEnabled`	`boolean`	是否提供 `onLoadMore`	是否允许上拉加载
`loadMoreMode`	`'pull'	'auto'`	`'pull'`
`autoLoadMoreEnabled`	`boolean`	`false`	兼容别名，等同于 `loadMoreMode="auto"`；新代码请使用 `loadMoreMode`
`refreshing`	`boolean`	非受控	受控刷新状态
`loadingMore`	`boolean`	非受控	受控加载状态
`hasMore`	`boolean`	`true`	`false` 时显示没有更多数据并禁止继续加载
`hapticsEnabled`	`boolean`	`true`	到达释放阈值时启用触觉反馈
`headerStyle`	`'classic' \| 'material'`	`'classic'`	刷新头样式
`primaryColor`	`ColorValue`	平台默认	Classic Header/Footer 主背景色；Android Material Header 也使用该值作为主色
`indicatorColor`	`ColorValue`	平台默认	指示器颜色
`titleColor`	`ColorValue`	平台默认	状态文字颜色
`classicSpinnerStyle`	`'scale' \| 'translate' \| 'fixed-behind'`	`'translate'`	Classic Header 动画模式，Android 与 iOS 都支持
`classicEnableLastTime`	`boolean`	`true`	Android 与 iOS Classic Header 是否显示最后更新时间
`materialShowBezierWave`	`boolean`	`false`	Android 专属；对应 `MaterialHeader.setShowBezierWave`
`materialEnableHeaderTranslationContent`	`boolean`	`false`	Android 专属；Material Header 下拉时内容是否同步偏移
`materialProgressBackgroundColor`	`ColorValue`	Material 默认	Android 与 iOS Material 进度圆背景色
`messages`	`Partial<RefreshMessages>`	英文默认文案	覆盖状态文案
`onRefresh`	`(request) => void \| Promise<void>`	-	下拉刷新回调，参数含 `requestId` 和 `source`
`onLoadMore`	`(request) => void \| { hasMore } \| Promise<...>`	-	加载更多回调，可直接返回下一页是否还有数据
`onRefreshError`	`(error: unknown) => void`	-	`onRefresh` 抛错后的通知
`onLoadMoreError`	`(error: unknown) => void`	-	`onLoadMore` 抛错后的通知
`onStateChange`	`(state: RefreshState) => void`	-	原生刷新状态变化
`onHeaderMoving`	`(event: HeaderMovingEvent) => void`	-	自定义 Header 的下拉距离变化，包含松手后的回弹过程

其余 ViewProps 会传给原生容器。

refreshHeader 的内容会真实挂载到 Android 和 iOS 的原生刷新 Header 槽位，而不是作为列表中的普通 React 子节点。提供它后，会覆盖 headerStyle 选中的 Classic 或 Material Header。当前自定义 Header 的固定逻辑高度为 80；应让内容在这个区域内完成布局。纯展示内容建议设置 pointerEvents="none"，避免截获列表的下拉手势。

onHeaderMoving 在拖拽和松手回弹时都会发出事件。offset、height、maxDragHeight 均为跨平台一致的逻辑像素（Android dp / iOS pt）；percent >= 1 表示已达到刷新触发阈值。

Classic 与 Material 配置

Classic Header/Footer 的颜色在 Android 与 iOS 上都生效；Classic Header 的 Spinner 样式和最后更新时间也在两端生效。Material 的 indicatorColor 与 materialProgressBackgroundColor 也在两端生效；materialShowBezierWave 和 materialEnableHeaderTranslationContent 是 Android 官方 Header 的布局开关，iOS 会安全忽略。

tsx

<SmartRefreshLayout
  headerStyle="classic"
  primaryColor="#1677ff"
  indicatorColor="#ffffff"
  titleColor="#ffffff"
  classicSpinnerStyle="fixed-behind"
  classicEnableLastTime
  onRefresh={reload}
>
  <FlatList {...listProps} />
</SmartRefreshLayout>

tsx

<SmartRefreshLayout
  headerStyle="material"
  primaryColor="#52c41a"
  indicatorColor="#ffffff"
  materialShowBezierWave
  materialEnableHeaderTranslationContent={false}
  materialProgressBackgroundColor="#52c41a"
  onRefresh={reload}
>
  <FlatList {...listProps} />
</SmartRefreshLayout>

indicatorColor 在 Android Material 模式中映射到官方 setColorSchemeColors；在 Classic 模式中用于箭头与加载指示器。titleColor 只影响 Classic Header/Footer 文案。iOS Material Header 使用 indicatorColor 和 materialProgressBackgroundColor；其 primaryColor 仍保留给 Classic Header/Footer。

这些配置可以在组件运行期间动态更新。Android Classic Spinner 样式会重建 Header 以确保 scale、translate 和 fixed-behind 真正切换；如果当前正在刷新或分页，变更会等到布局回到空闲状态后应用。

Promise 行为

未传 refreshing 时，onRefresh 返回的 Promise settle 后会自动调用原生 finishRefresh。未传 loadingMore 时，onLoadMore 采用同样规则。

如果回调抛错，组件会以失败状态结束动画，并调用对应的 error handler。组件不会在没有 error handler 时制造未处理的 Promise rejection。

传入 refreshing 或 loadingMore 后即进入受控模式，调用方必须把对应值恢复为 false 才会结束动画。

一次刷新或分页请求从原生手势或实例命令开始，并带有只属于该视图实例的 requestId。同一时间只允许一个请求；重复手势、刷新与分页交叉触发，以及过期的延迟结束命令都会被忽略。

onLoadMore 可以返回 { hasMore: false }，组件会在同一轮请求完成时锁定 footer，不必等待下一次 React 渲染。未返回该对象时，组件使用 hasMore Prop 的最新值。

自动模式不会在首次挂载、短列表或仅仅因为 footer 出现时触发。Android 和 iOS 都要求内容超过一屏，并先检测到用户向上滚动；请求完成后需要下一次向上滚动才会再次解锁自动加载。

RefreshMessages

interface RefreshMessages {
  pullDown: string;
  releaseToRefresh: string;
  refreshing: string;
  refreshComplete: string;
  pullUp: string;
  releaseToLoadMore: string;
  loadingMore: string;
  noMoreData: string;
}

请求参数和结果类型：

interface RefreshRequest {
  requestId: number;
  source: 'gesture' | 'programmatic';
}

interface LoadMoreResult {
  hasMore: boolean;
}

interface HeaderMovingEvent {
  /** 相对于刷新触发阈值的下拉进度。 */
  percent: number;
  /** 当前 Header 下拉距离，单位为逻辑像素（dp/pt）。 */
  offset: number;
  /** 原生 Header 高度，单位为逻辑像素（dp/pt）。 */
  height: number;
  /** 最大可下拉距离，单位为逻辑像素（dp/pt）。 */
  maxDragHeight: number;
  /** 用户当前是否正在拖拽滚动视图。 */
  isDragging: boolean;
}

RefreshState

type RefreshState =
  | 'idle'
  | 'pulling'
  | 'ready'
  | 'refreshing'
  | 'loading'
  | 'no-more-data';

SmartRefreshLayoutRef

tsx

import type { SmartRefreshLayoutRef } from 'expo-smartrefreshlayout';

beginRefresh

beginRefresh(delay?: number): boolean;

主动开始刷新。返回 true 表示当前实例接受了请求，false 表示已有刷新或分页请求。delay 为非负毫秒数，非法值会归一化为 0。

finishRefresh

finishRefresh(options?: {
  success?: boolean;
  delay?: number;
}): void;

结束当前刷新。默认 success: true、delay: 0。

beginLoadMore

beginLoadMore(delay?: number): boolean;

主动开始加载更多。返回值与 beginRefresh 相同；hasMore=false 时返回 false。

finishLoadMore

finishLoadMore(options?: {
  success?: boolean;
  hasMore?: boolean;
  delay?: number;
}): void;

结束当前加载。hasMore: false 会让原生 footer 进入没有更多数据状态。

resetNoMoreData

resetNoMoreData(): void;

重置原生 footer 状态。若组件的 hasMore 仍为 false，下一次渲染会再次应用没有更多数据状态，因此受控场景应同时更新 hasMore。

兼容导出

v2 暂时保留旧组件名作为别名：

import { ExpoSmartrefreshlayoutView } from 'expo-smartrefreshlayout';

别名使用的仍是 v2 Props。旧的 ExpoSmartrefreshlayoutModule 和旧 Props 不再存在。

SmartSecondFloorLayout（仅 Android）

tsx

import { SmartSecondFloorLayout } from 'expo-smartrefreshlayout';

这是 Android-only 组件，底层使用 SmartRefreshLayout 的 TwoLevelHeader。children 必须是普通页面的唯一滚动子组件，secondFloor 是覆盖式二楼内容。可选的 secondFloorBackground 用于在其后放置揭露式背景，并让正式二楼内容在进入后原生淡入。二楼组件不包含 footer，也不支持 onLoadMore 或自动加载更多。iOS 没有等价原生能力，渲染该组件会抛出明确错误：请在平台分支中不要挂载它，或继续使用跨平台的 SmartRefreshLayout。

Props

属性	类型	默认值	说明
`children`	`ReactElement`	必填	普通页面的唯一滚动子组件
`secondFloor`	`ReactElement`	必填	二楼的全屏内容；可放 `ScrollView`/`FlatList`
`secondFloorBackground`	`ReactElement`	-	`secondFloor` 后方的揭露背景；提供后正式内容会在打开时淡入
`refreshEnabled`	`boolean`	是否提供 `onRefresh`	是否允许普通下拉刷新
`refreshing`	`boolean`	非受控	受控普通刷新状态
`hapticsEnabled`	`boolean`	`true`	到达刷新或二楼释放阈值时触觉反馈
`secondFloorEnabled`	`boolean`	`true`	是否允许进入二楼
`headerInset`	`number`	`0`	Classic Header 顶部预留的逻辑高度。页面顶部有覆盖式 Toolbar 时传入其高度，使 Header 的可见位置与二楼阈值一起计算
`maxRate`	`number`	`2.5`	最大拖拽倍率，归一化到 `1.2..5`
`floorRate`	`number`	`1.9`	二楼释放倍率，至少 `1.1`，且低于 `maxRate`
`refreshRate`	`number`	`1`	普通刷新倍率，至少 `0.25`，且低于 `floorRate`
`floorDuration`	`number`	`1000`	进入/停留二楼的动画时长（毫秒），归一化到 `0..10000`
`pullToCloseEnabled`	`boolean`	`true`	是否允许在二楼向下拉关闭
`bottomPullUpToCloseRate`	`number`	`1/6`	二楼底部关闭拖拽倍率，归一化到 `0.01..0.5`
`primaryColor`	`ColorValue`	平台默认	Classic Header 背景色
`indicatorColor`	`ColorValue`	平台默认	Classic 指示器颜色
`titleColor`	`ColorValue`	平台默认	Classic 文案颜色
`classicEnableLastTime`	`boolean`	`true`	是否显示 Classic 最后更新时间
`messages`	`Partial<SecondFloorMessages>`	英文默认文案	覆盖普通刷新文案
`onRefresh`	`(request) => void \| Promise<void>`	-	普通下拉刷新回调
`onRefreshError`	`(error: unknown) => void`	-	刷新失败通知
`onStateChange`	`(state: SecondFloorState) => void`	-	普通刷新和二楼生命周期状态
`onSecondFloorOpen`	`() => void`	-	二楼展开动画完成
`onSecondFloorClose`	`() => void`	-	二楼关闭动画完成

floorRate、maxRate 和 refreshRate 会在 JS 与 Android 两端同时归一化。为了保持阈值顺序，传入互相矛盾的值时，组件会把较低层级压到上限，而不是抛异常。

SecondFloorMessages

interface SecondFloorMessages {
  pullDown: string;
  releaseToRefresh: string;
  refreshing: string;
  refreshComplete: string;
}

SecondFloorState

type SecondFloorState =
  | 'idle'
  | 'pulling'
  | 'ready'
  | 'refreshing'
  | 'release-to-second-floor'
  | 'second-floor-opening'
  | 'second-floor'
  | 'second-floor-closing';

SmartSecondFloorLayoutRef

interface SmartSecondFloorLayoutRef {
  beginRefresh(delay?: number): boolean;
  finishRefresh(options?: { success?: boolean; delay?: number }): void;
  openSecondFloor(): boolean;
  closeSecondFloor(): boolean;
}

beginRefresh 返回 false 表示已有刷新或二楼处于打开/动画状态；openSecondFloor 返回 true 表示命令已派发给空闲的已挂载实例，closeSecondFloor 返回 true 表示当前处于可关闭的打开/展开状态。所有布尔返回值描述的是命令接受情况，不是动画完成情况。

二楼内容可以是嵌套 ScrollView 或 FlatList，但外层 TwoLevelHeader 会在边界拖拽时接管触摸；务必给内部滚动组件配置 nestedScrollEnabled，并避免把横向分页手势放在同一个边界区域。这个限制是原生手势竞争，不是 onStateChange 的状态缺失。

API 参考 ​

SmartRefreshLayout ​

Props ​

自定义原生 Header ​

Classic 与 Material 配置 ​

Promise 行为 ​

RefreshMessages ​

RefreshState ​

SmartRefreshLayoutRef ​

beginRefresh ​

finishRefresh ​

beginLoadMore ​

finishLoadMore ​

resetNoMoreData ​

兼容导出 ​

SmartSecondFloorLayout（仅 Android） ​

Props ​

SecondFloorMessages ​

SecondFloorState ​

SmartSecondFloorLayoutRef ​

API 参考

SmartRefreshLayout

Props

自定义原生 Header

Classic 与 Material 配置

Promise 行为

RefreshMessages

RefreshState

SmartRefreshLayoutRef

beginRefresh

finishRefresh

beginLoadMore

finishLoadMore

resetNoMoreData

兼容导出

SmartSecondFloorLayout（仅 Android）

Props

SecondFloorMessages

SecondFloorState

SmartSecondFloorLayoutRef