UI组件前端移动开发【免费下载链接】ant-design-mobileEssential UI blocks for building mobile web apps.项目地址https://gitcode.com/gh_mirrors/an/ant-design-mobile点击查看免费下载下拉刷新是移动端列表页最常用的交互之一用户通过手指在页面顶部向下拖动触发数据更新。ant-design-mobileantd-mobile提供的PullToRefresh组件以状态机驱动 手势监听的方式封装了这一能力。本文以 pull-to-refresh/index.zh.md 为骨架结合 pull-to-refresh.tsx 的源码实现与 pull-to-refresh.test.tsx 的测试用例完整讲解该组件的使用方式、全部属性配置、四态状态机流转逻辑以及它在滚动容器检测、橡皮筋阻尼、浏览器默认行为规避等底层细节上的设计取舍。读完本文你将能够独立完成下拉刷新的接入、文案定制、失败处理与多层嵌套布局适配。何时使用 PullToRefresh按官方文档的定义PullToRefresh 适用于对当前页面进行内容更新的场景。它是一个容器型组件将列表等内容包在内部用户在内容区顶部下拉即可触发刷新回调。与之互补的是上拉加载更多antd-mobile 将其单独实现为 InfiniteScroll 组件——当页面滚动到底部、距底部threshold默认 250px时自动调用loadMore。两者的职责划分非常清晰需要下拉刷新页面数据 → 使用PullToRefresh需要上拉加载更多数据 → 使用InfiniteScroll两者可以组合使用外层包PullToRefresh实现下拉刷新列表内部或滚动容器底部挂载InfiniteScroll实现滚动加载。快速上手基础用法官方第一个示例demos/demo1.tsx展示了最基础的接入方式import React, { useState } from react import { PullToRefresh, List } from antd-mobile import { sleep } from antd-mobile/es/utils/sleep import { lorem } from demos function getNextData() { const ret: string[] [] for (let i 0; i 18; i) { ret.unshift(lorem.generateWords(1)) } return ret } export default () { const [data, setData] useState(() getNextData()) return ( PullToRefresh onRefresh{async () { await sleep(1000) setData([...getNextData(), ...data]) }} List style{{ minHeight: 100vh }} {data.map((item, index) ( List.Item key{index}{item}/List.Item ))} /List /PullToRefresh ) }要点PullToRefresh包裹实际内容这里是List作为唯一子节点onRefresh必须返回一个 Promise——组件会await它只有 Promise resolve 之后才会进入完成状态并收起头部示例中通过sleep(1000)模拟 1 秒网络请求随后把新数据拼接到已有数据之前为了让列表内容足够长、可被拖动示例给List设置了minHeight: 100vh。从源码看PullToRefresh的默认 props 定义在 pull-to-refresh.tsxexport const defaultProps { pullingText: 下拉刷新, canReleaseText: 释放立即刷新, refreshingText: 加载中..., completeText: 刷新成功, completeDelay: 500, disabled: false, onRefresh: () {}, }注意onRefresh的默认值是一个空函数因此即使漏传该属性组件也不会崩溃只是刷新时不执行任何逻辑。属性配置全解官方文档给出了PullStatus类型定义与完整的属性表type PullStatus pulling | canRelease | refreshing | complete属性说明类型默认值canReleaseText释放的提示文案ReactNode释放立即刷新completeDelay完成后延迟消失的时间单位为 msnumber500completeText完成时的提示文案ReactNode刷新成功disabled是否禁用下拉刷新booleanfalseheadHeight头部提示内容区的高度单位为 pxnumber40onRefresh触发刷新时的处理函数() Promiseany-pullingText下拉的提示文案ReactNode下拉刷新refreshingText刷新时的提示文案ReactNode加载中……renderText根据下拉状态自定义下拉提示文案(status: PullStatus) ReactNode-threshold触发刷新需要下拉多少距离单位为 pxnumber60下面逐项说明关键参数的作用与实现层面的影响headHeight 与 threshold控制下拉的物理行程headHeight默认 40是头部提示内容区的高度。源码中头部内容通过style{{ height: headHeight }}渲染pull-to-refresh.tsx它决定了刷新时、完成时头部占据的视觉空间threshold默认 60是触发刷新的下拉距离阈值。手势过程中当实际下拉高度height threshold时状态切换为canRelease此时松手才会真正执行刷新pull-to-refresh.tsx。注意单位换算源码里这两个值不是直接使用而是经过convertPx处理const headHeight props.headHeight ?? convertPx(40) const threshold props.threshold ?? convertPx(60)convert-px.ts 会根据页面上的adm-px-tester元素实测 1px 的真实渲染高度自动适配postcss-px-to-viewport之类把 px 换算成 rem/vw 的移动端适配方案。也就是说在做了移动端 rem 适配的项目里传入 40/60 仍能获得与设计稿一致的物理距离无需手工换算。onRefresh必须返回 Promise 的刷新回调onRefresh: () Promiseany是触发刷新时执行的函数。查看 doRefresh 的实现可以看到完整流程async function doRefresh() { api.start({ height: headHeight }) setStatus(refreshing) try { await props.onRefresh() setStatus(complete) } catch (e) { reset() throw e } if (props.completeDelay 0) { await sleep(props.completeDelay) } reset() }即下拉松开 → 头部展开到headHeight并进入refreshing状态 →await onRefresh()→ 进入complete状态 → 等待completeDelay默认 500ms后收起头部并复位为pulling。如果onRefresh抛出异常比如网络请求失败组件会立即收起头部并复位同时把异常继续向上抛出。这意味着你必须让onRefresh返回一个真正await了异步操作的 Promise才能保证 loading 文案持续到请求真正结束刷新失败时组件本身不吞掉错误你可以用try/catch或.catch()自行处理详见下文处理刷新失败。completeDelay完成态的展示时长completeDelay默认 500ms控制刷新成功文案的停留时间。源码中通过sleep(props.completeDelay)实现测试用例pull-to-refresh.test.tsx使用假定时器推进 1000ms请求 500mscompleteDelay后验证文案依次从加载中...变为刷新成功再复位为下拉刷新。若设为0则刷新完成后立即收起几乎看不到刷新成功的反馈——一般不建议除非你通过renderText做了其他形式的完成反馈。disabled整体禁用下拉手势disabled默认false为true时组件完全不响应下拉手势。实现上它被直接传给useDrag的enabled选项pull-to-refresh.tsx从手势库层面彻底关闭拖动能力。renderText按状态定制文案的终极方案renderText: (status: PullStatus) ReactNode的优先级最高。从 renderStatusText 的实现可见const renderStatusText () { if (props.renderText) { return props.renderText?.(status) } if (status pulling) return props.pullingText if (status canRelease) return props.canReleaseText if (status refreshing) return props.refreshingText if (status complete) return props.completeText }一旦传入renderText四个独立文案属性pullingText/canReleaseText/refreshingText/completeText都会被忽略。它可以返回任意ReactNode比如图标 文字的复合内容。自定义提示文案通过 renderText 定制四态文案官方第二个示例demos/demo2.tsx用一个statusRecord映射四个状态的自定义文案import { PullStatus } from antd-mobile/es/components/pull-to-refresh const statusRecord: RecordPullStatus, string { pulling: 用力拉, canRelease: 松开吧, refreshing: 玩命加载中..., complete: 好啦, } PullToRefresh onRefresh{async () { await sleep(1000) setData([...getNextData(), ...data]) }} renderText{status { return div{statusRecord[status]}/div }} {/* 内容 */} /PullToRefreshPullStatus类型可以直接从antd-mobile/es/components/pull-to-refresh导入该类型在 index.ts 中被重新导出。测试用例 pull-to-refresh.test.tsx 完整覆盖了这种用法验证拖动 100px 时显示用力拉、拖到 200px 显示松开吧、松手后显示玩命加载中...、请求完成后显示好啦。多语言文案的默认来源细心的读者会发现源码中的文案默认值并非直接来自defaultProps而是通过mergeProps与 ConfigProvider 的 locale 合并pull-to-refresh.tsxconst props mergeProps( defaultProps, { refreshingText: ${locale.common.loading}..., pullingText: locale.PullToRefresh.pulling, canReleaseText: locale.PullToRefresh.canRelease, completeText: locale.PullToRefresh.complete, }, p )以 src/locales/base.ts 的英文语言包为例PullToRefresh: { pulling: Scroll down to refresh, canRelease: Release to refresh immediately, complete: Refresh successful, },这意味着在 antd-mobile 的 ConfigProvider 中切换 locale 后PullToRefresh 的提示文案会自动切换为对应语言而显式传入的 props 优先级最高会覆盖 locale 与 defaultProps。refreshingText默认值则是通用 loading 文案加省略号与 locale 的common.loading联动。处理刷新失败的情况官方第三个示例demos/demo3.tsx演示了失败场景的标准处理姿势——让onRefresh抛出异常组件收起头部业务侧自行提示import React from react import { PullToRefresh, Toast } from antd-mobile import { DemoDescription } from demos import { sleep } from antd-mobile/es/utils/sleep async function doRefresh() { await sleep(1000) Toast.show({ icon: fail, content: 刷新失败, }) throw new Error(刷新失败) } export default () { return ( PullToRefresh onRefresh{doRefresh} div className{styles.content} DemoDescription下拉刷新一下试试/DemoDescription /div /PullToRefresh ) }这与 doRefresh 的实现严格对应onRefresh抛错后catch分支调用reset()让头部直接收起不显示刷新成功并throw e把错误继续向上传播。示例中在抛错前先用Toast.show弹出失败提示这是一种组件收起 业务提示的组合方案。由此也可以总结出最佳实践不要在onRefresh内部吞掉错误——让异常自然抛出PullToRefresh 会自动复位状态提示文案Toast/Message由业务代码负责。内容区域存在多层嵌套时的处理官方第四个示例demos/demo-nested.tsx展示了头部列表、Tabs 面板、可滚动列表多层嵌套的复杂布局PullToRefresh onRefresh{async () { await sleep(1000) setData(getNextData()) }} div className{styles.container} List header头部的一些内容 modecard {data.headerItems.map((item, index) ( List.Item key{index}{item}/List.Item ))} /List div className{styles.tabsPart} Tabs Tabs.Tab key1 title{面板 A} / Tabs.Tab key2 title{面板 B} / /Tabs /div div className{styles.scrollPart} List style{{ minHeight: 100vh }} {data.bodyItems.map((item, index) ( List.Item key{index}{item}/List.Item ))} /List /div /div /PullToRefreshPullToRefresh 之所以能处理这种嵌套场景关键在于源码中的滚动位置预检逻辑pull-to-refresh.tsxif (state.first parsedY 0) { const target state.event.target if (!target || !(target instanceof Element)) return let scrollParent getScrollParent(target) while (true) { if (!scrollParent) return const scrollTop getScrollTop(scrollParent) if (scrollTop 0) { return } if (scrollParent instanceof Window) { break } scrollParent getScrollParent(scrollParent.parentNode as Element) } pullingRef.current true ... }它的语义是手指第一次向下移动时先找到手势起点元素的所有可滚动祖先滚动容器只要其中任何一个尚未滚动到顶部scrollTop 0就放弃本次下拉——因为此时用户的本意大概率是向上滚动列表内容而不是触发刷新。只有当所有滚动容器都已处于顶部时才真正进入下拉模式。这正是多层嵌套下避免滚动页面与下拉刷新打架的关键。配套的滚动容器探测工具是 get-scroll-parent.ts它沿 DOM 向上遍历通过overflowY的scroll/auto/overlay样式值与scrollHeight clientHeight判断元素是否可滚动遇到body则直接返回 window。测试用例 pull-to-refresh.test.tsx 也验证了这一点当window.scrollY 10页面未在顶部时即使下拉 200pxonRefresh也不会被调用。源码级原理状态机与手势实现四态状态机组件内部用一个useStatePullStatus维护状态pull-to-refresh.tsx四态流转如下pulling ──(下拉距离 threshold)── canRelease canRelease ──(松手)── refreshing ──(onRefresh resolve)── complete complete ──(等待 completeDelay)── pulling canRelease ──(下拉距离回落)── pulling每次状态切换都对应一套文案pullingText/canReleaseText/refreshingText/completeText或renderText的返回值用户在下拉过程中能直观感知当前所处的阶段。手势监听useGesture react-spring组件使用use-gesture/react的useDrag监听纵向拖动使用react-spring/web的useSpring驱动头部高度动画pull-to-refresh.tsx动画配置为tension: 300, friction: 30, round: true, clamp: true兼顾了跟手性与回弹手感。拖动过程中的距离计算pull-to-refresh.tsxconst height Math.max( rubberbandIfOutOfBounds(parsedY, 0, 0, headHeight * 5, 0.5), 0 ) api.start({ height }) setStatus(height threshold ? canRelease : pulling)这里的rubberbandIfOutOfBounds来自 rubberband.ts实现 iOS 风格的回弹阻尼下拉距离越大实际展开高度的增量越小形成越拉越费力的物理手感。其核心公式为(distance * dimension * constant) / (dimension constant * distance)dimension取headHeight * 5200px、constant取 0.5。防抖动的空 touchmove 监听源码中有一段看似无用的代码pull-to-refresh.tsxuseEffect(() { elementRef.current?.addEventListener(touchmove, () {}) }, [])这其实是一个经典的移动端兼容技巧注册一个空的非 passive 的touchmove监听用来解锁后续调用event.preventDefault()的能力部分浏览器在未注册 touchmove 监听时preventDefault 会被忽略从而避免下拉时页面抖动/滚动穿透。同时手势监听通过eventOptions: supportsPassive ? { passive: false } : undefined保证能成功拦截默认行为pull-to-refresh.tsxsupportsPassive工具来自 supports-passive.ts。常见问题是否支持上拉加载更多不支持。上拉加载更多是另一个独立组件InfiniteScroll。PullToRefresh 只负责下拉刷新两者的滚动方向与触发时机完全不同可以组合使用。关于浏览器的默认下拉行为官方文档明确指出一些浏览器或 webview 容器本身自带弹性效果或下拉刷新逻辑antd-mobile 不建议在这种环境中使用 PullToRefresh。如果一定要用需要先禁用外层浏览器的默认下拉与弹性效果否则会出现 PullToRefresh 与浏览器默认行为同时触发的情况造成糟糕的用户体验。从源码角度可以进一步理解这个警告useDrag在拖动时会调用event.preventDefault()阻止页面原生滚动pull-to-refresh.tsx但这一拦截只作用于组件内部的容器而浏览器/webview 层的原生下拉刷新发生在应用之外组件无法控制。常见的处理方式包括在 iOS Safari/部分 WebView 中设置overscroll-behavior-y: none或相关 meta 标签禁用原生回弹在 App 的 WebView 配置中关闭原生下拉刷新能力评估是否改用原生容器的下拉能力而非在 Web 层实现。组件结构与样式要点从 pull-to-refresh.tsx 可以看到组件的 DOM 结构div classadm-pull-to-refresh div classadm-pull-to-refresh-head !-- 头部动画容器高度由 useSpring 驱动 -- div classadm-pull-to-refresh-head-content !-- 定高 headHeight文案居中 -- {renderStatusText()} /div /div div classadm-pull-to-refresh-content !-- 业务内容 -- {props.children} /div /div样式定义在 pull-to-refresh.less-head设置overflow: hidden; position: relative-head-content绝对定位在底部并水平垂直居中文字颜色使用 CSS 变量--adm-color-weak因此跟随主题色自动适配。入口文件 index.ts 同时导出了组件、PullToRefreshProps与PullStatus类型。结语PullToRefresh 是 antd-mobile 中交互复杂度较高的组件之一它用四态状态机把下拉手势抽象成清晰的流程用getScrollParent解决嵌套滚动冲突用rubberbandIfOutOfBounds还原原生阻尼手感再用convertPx适配移动端 rem 布局。理解这些源码细节不仅能帮你正确配置 headHeight、threshold、completeDelay 等属性也能让你在遇到嵌套滚动、浏览器原生下拉冲突等问题时快速定位原因。需要进一步验证行为时可参考 pull-to-refresh.test.tsx 中覆盖的 pulling/canRelease/refreshing/complete 全链路用例。赞分享UI组件前端移动开发【免费下载链接】ant-design-mobileEssential UI blocks for building mobile web apps.项目地址https://gitcode.com/gh_mirrors/an/ant-design-mobile点击查看免费下载相关推荐ant-design-mobile PullToRefresh 下拉刷新组件完全指南状态机、手势原理与实战配置ant design mobile PullToRefresh 下拉刷新组件完全指南状态机、手势原理与实战配置 本文围绕 ant design mobileUI组件前端移动开发BetterScroll pulldown 插件完全指南下拉刷新的状态机、配置与源码剖析BetterScroll pulldown 插件完全指南下拉刷新的状态机、配置与源码剖析 pulldown 插件为 BetterScroll 注入「下拉刷新」前端UI组件BetterScroll pulldown 下拉刷新插件完全指南配置、状态机与实战BetterScroll pulldown 下拉刷新插件完全指南配置、状态机与实战 pulldown 是 BetterScroll 官方插件体系中为列表注入前端UI组件上一篇揭秘LTX-2.3-3DREAL-LoRA3D转写实技术如何颠覆影视动画制作流程下一篇systemd-docker 高级功能详解环境变量传递、日志管理与系统通知集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考