expo-smartrefreshlayout

简体中文

English

简体中文

English

外观

API 参考 ​

SmartRefreshLayout ​

tsx
import { SmartRefreshLayout } from 'expo-smartrefreshlayout';

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

Props ​

属性类型默认值说明
childrenReactElement必填唯一的滚动子组件
refreshHeaderReactElement-挂载到 Android/iOS 原生刷新 Header 槽位的 React 内容；提供后替代 headerStyle 选中的 Classic/Material Header
refreshHeaderHeightnumber80自定义 Header 的逻辑高度（Android dp / iOS pt）；有限正数上限为 10000，会取整；非法或取整后非正的值回退 80
refreshHeaderSpinnerStyle'scale' | 'translate' | 'fixed-behind''translate'仅用于 refreshHeader；两端都映射到等价的原生布局模式
refreshHeaderTriggerRatenumber1自定义 Header 的刷新触发高度倍率；有效范围 (0, 1]，无效值回退 1
refreshHeaderMaxDragRatenumber2自定义 Header 的最大下拉高度倍率；有效范围 [1, 9]，无效值回退 2
refreshHeaderFinishDurationnumber0自定义 Header 成功/失败完成态的原生停留/完成动画时长（毫秒），归一化为 0..60000
refreshEnabledboolean是否提供 onRefresh是否允许下拉刷新
loadMoreEnabledboolean是否提供 onLoadMore是否允许上拉加载
loadMoreMode`'pull''auto'`'pull'
autoLoadMoreEnabledbooleanfalse兼容别名，等同于 loadMoreMode="auto"；新代码请使用 loadMoreMode
refreshingboolean非受控受控刷新状态
loadingMoreboolean非受控受控加载状态
hasMorebooleantruefalse 时显示没有更多数据并禁止继续加载
hapticsEnabledbooleantrue到达释放阈值时启用触觉反馈
headerStyle'classic' | 'material''classic'刷新头样式
primaryColorColorValue平台默认Classic Header/Footer 主背景色；Android Material Header 也使用该值作为主色
indicatorColorColorValue平台默认指示器颜色
titleColorColorValue平台默认状态文字颜色
classicSpinnerStyle'scale' | 'translate' | 'fixed-behind''translate'Classic Header 动画模式，Android 与 iOS 都支持
classicEnableLastTimebooleantrueAndroid 与 iOS Classic Header 是否显示最后更新时间
materialShowBezierWavebooleanfalseAndroid 专属；对应 MaterialHeader.setShowBezierWave
materialEnableHeaderTranslationContentbooleanfalseAndroid 专属；Material Header 下拉时内容是否同步偏移
materialProgressBackgroundColorColorValueMaterial 默认Android 与 iOS Material 进度圆背景色
messagesPartial<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 的下拉距离变化，包含松手后的回弹过程
onHeaderInitialized(event: HeaderLifecycleEvent) => void-仅自定义 Header：原生尺寸初始化完成
onHeaderReleased(event: HeaderLifecycleEvent) => void-仅自定义 Header：用户释放且原生开始释放/回弹动画
onHeaderStart(event: HeaderLifecycleEvent) => void-仅自定义 Header：原生真正开始刷新动画
onHeaderFinish(event: HeaderFinishEvent) => void-仅自定义 Header：原生进入成功或失败完成态

其余 ViewProps 会传给原生容器。

自定义原生 Header ​

refreshHeader 的内容会真实挂载到 Android 和 iOS 的原生刷新 Header 槽位，而不是作为列表中的普通 React 子节点。提供它后，会覆盖 headerStyle 选中的 Classic 或 Material Header。默认逻辑高度为 80， 可用 refreshHeaderHeight 调整；内容布局应与该高度一致。纯展示内容建议设置 pointerEvents="none"， 避免截获列表的下拉手势。

refreshHeaderSpinnerStyle 支持 scale、translate 和 fixed-behind。refreshHeaderTriggerRate 控制相对于 Header 高度的触发阈值，refreshHeaderMaxDragRate 控制真实最大下拉高度。最大倍率上限为 9， 以避开 Android 内核将 >= 10 解释为物理像素高度的特殊语义；onHeaderMoving.maxDragHeight 会反映 最终约束。refreshHeaderFinishDuration 是原生 Header 进入成功/失败完成态后的停留/完成动画时长，和 finishRefresh({ delay }) 延迟发起完成命令的含义不同。

onHeaderMoving 在拖拽和松手回弹时都会发出事件。offset、height、maxDragHeight 均为跨平台一致的 逻辑像素（Android dp / iOS pt）；percent >= 1 表示已达到刷新触发阈值。自定义 Header 的 onHeaderInitialized、onHeaderReleased 和 onHeaderStart 都接收 { height, maxDragHeight }； onHeaderFinish 接收原生完成回调给出的 { success }，不是根据 JS Promise 推断出的结果。

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 ​

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

请求参数和结果类型：

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

interface HeaderLifecycleEvent {
  /** 原生 Header 高度，单位为逻辑像素（dp/pt）。 */
  height: number;
  /** 最大可下拉距离，单位为逻辑像素（dp/pt）。 */
  maxDragHeight: number;
}

interface HeaderFinishEvent {
  /** 原生 Header 完成态报告的结果。 */
  success: boolean;
}

RefreshState ​

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

SmartRefreshLayoutRef ​

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

beginRefresh ​

ts
beginRefresh(delay?: number): boolean;

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

finishRefresh ​

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

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

beginLoadMore ​

ts
beginLoadMore(delay?: number): boolean;

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

finishLoadMore ​

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

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

resetNoMoreData ​

ts
resetNoMoreData(): void;

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

兼容导出 ​

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

ts
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 ​

属性类型默认值说明
childrenReactElement必填普通页面的唯一滚动子组件
secondFloorReactElement必填二楼的全屏内容；可放 ScrollView/FlatList
secondFloorBackgroundReactElement-secondFloor 后方的揭露背景；提供后正式内容会在打开时淡入
refreshEnabledboolean是否提供 onRefresh是否允许普通下拉刷新
refreshingboolean非受控受控普通刷新状态
hapticsEnabledbooleantrue到达刷新或二楼释放阈值时触觉反馈
secondFloorEnabledbooleantrue是否允许进入二楼
headerInsetnumber0Classic Header 顶部预留的逻辑高度。页面顶部有覆盖式 Toolbar 时传入其高度，使 Header 的可见位置与二楼阈值一起计算
maxRatenumber2.5最大拖拽倍率，归一化到 1.2..5
floorRatenumber1.9二楼释放倍率，至少 1.1，且低于 maxRate
refreshRatenumber1普通刷新倍率，至少 0.25，且低于 floorRate
floorDurationnumber1000进入/停留二楼的动画时长（毫秒），归一化到 0..10000
pullToCloseEnabledbooleantrue是否允许在二楼向下拉关闭
bottomPullUpToCloseRatenumber1/6二楼底部关闭拖拽倍率，归一化到 0.01..0.5
primaryColorColorValue平台默认Classic Header 背景色
indicatorColorColorValue平台默认Classic 指示器颜色
titleColorColorValue平台默认Classic 文案颜色
classicEnableLastTimebooleantrue是否显示 Classic 最后更新时间
messagesPartial<SecondFloorMessages>英文默认文案覆盖普通刷新文案
onRefresh(request) => void | Promise<void>-普通下拉刷新回调
onRefreshError(error: unknown) => void-刷新失败通知
onStateChange(state: SecondFloorState) => void-普通刷新和二楼生命周期状态
onSecondFloorOpen() => void-二楼展开动画完成
onSecondFloorClose() => void-二楼关闭动画完成

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

SecondFloorMessages ​

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

SecondFloorState ​

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

SmartSecondFloorLayoutRef ​

ts
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 的状态缺失。

Released under the MIT License.

Copyright © TomWq