antd-mobile 从 0 到 1：5 分钟跑通，4 个页面场景搭出你的第一个 H5

antd-mobile 从 0 到 15 分钟跑通4 个页面场景搭出你的第一个 H5【免费下载链接】ant-design-mobileEssential UI blocks for building mobile web apps.项目地址: https://gitcode.com/gh_mirrors/an/ant-design-mobile做移动端 H5总被弹窗层级、刘海屏留白、点击延迟这几个问题卡住antd-mobile 是蚂蚁团队出品的 React 移动端 UI 组件库把导航栏、列表、表单、弹窗、Toast 这些移动开发的高频积木做成了开箱即用的组件支持 React 16.8 到 19。这篇文章只讲一件事让你先跑起来再按真实页面把组件用顺最后知道往哪深挖。5 分钟装好 antd-mobile 并跑通第一个页面这一节解决「怎么装、怎么引、第一屏长什么样」。组件样式会随 import 自动加载所以入口里不用再单独引样式文件这也是 v5 相对旧版最大的省心点。先装包antd-mobile-icons是官方图标包后面底部导航会用到npm install antd-mobile antd-mobile-icons # yarn add antd-mobile antd-mobile-icons 也可以下面是整个项目最小的可运行入口渲染一个主按钮点击弹一个 Toastimport { Button, Toast } from antd-mobile export default () ( Button colorprimary onClick{() Toast.show(跑通了)} 点我试试 /Button )从包根路径import { Button } from antd-mobile时全局样式会一并加载。只有当你的构建工具不支持 Tree Shaking、需要手动按需引入如antd-mobile/es/components/button时才必须在入口补一句import antd-mobile/es/global细节见 docs/guide/import-on-demand.zh.md。按页面任务过一遍 4 个核心场景组件清单背不完但页面就那么几类。下面 4 个场景覆盖了「一个 H5 页面的骨架」导航、搜索列表、表单、操作反馈。搭出顶部导航栏和底部 TabBar一个典型的 App 式页面 顶部 NavBar 中间内容 底部 TabBar。back传null可以隐藏返回箭头比如首页onBack自己决定回退逻辑。import { NavBar, TabBar } from antd-mobile import { AppOutline, UserOutline } from antd-mobile-icons const [key, setKey] useState(home) NavBar back返回 onBack{() history.back()} 首页 /NavBar TabBar activeKey{key} onChange{setKey} TabBar.Item keyhome title首页 icon{AppOutline /} / TabBar.Item keymy title我的 icon{UserOutline /} / /TabBarTabBar 的icon支持传一个函数(active) ...选中态可以换实心图标官方 demosrc/components/tab-bar/demos/里就是这么写的。用 SearchBar 加 List 做一个可筛选列表这一节解决「搜索框 列表」这个最高频的组合。onSearch在回车或点取消旁的确认时触发List.Item只要传了onClick就会自动显示为可点击态。SearchBar placeholder搜索商品 showCancelButton onSearch{setKeyword} / List {filterBy(keyword).map(item ( List.Item key{item.id} title{item.title} description{item.desc} onClick{() goDetail(item.id)} / ))} /List列表项的title、description、extra、prefix是四个固定插槽把商品名放title、价格放extra、头像放prefix排版就不用自己写 flex 了。用 Form 做一个带校验的资料表单表单场景的核心是「声明字段 → 声明校验 → 提交时拿值」。antd-mobile 的 Form 基于 rc-field-form 封装所以Form.useForm、rules、validateFields这些用法和你熟悉的其他 Form 一脉相承。Form layouthorizontal onFinish{async values { await saveProfile(values) Toast.show({ icon: success, content: 已保存 }) }} footer{ Button block typesubmit colorprimary sizelarge 提交 /Button } Form.Item namenickname label昵称 rules{[{ required: true, message: 昵称不能为空 }]} Input placeholder请输入昵称 / /Form.Item /Form这里有两个「为什么这么写」footer是 Form 的专属插槽放提交按钮时按钮的typesubmit会触发整表校验校验通过才进onFinishlayouthorizontal让 label 在左、输入框在右这是移动端表单最省地的布局。用 Toast 和 Dialog 处理操作反馈轻反馈用Toast.show重决策用Dialog.confirm。Dialog 的静态方法返回 Promise确认 resolvetrue取消或点遮罩 resolvefalse可以直接await写串行逻辑。const ok await Dialog.confirm({ content: 删除后无法恢复确定吗, onConfirm: async () { await deleteItem() Toast.show(删除成功) }, }) if (!ok) console.log(用户取消了)Toast.show传字符串是纯文字想带图标就传对象Toast.show({ icon: success, content: 已保存 })。icon还支持loading和fail长任务里先 show 一个 loading Toast、结束时Toast.clear()替换成结果就是最常见的 loading 反馈套路。改 CSS 变量换主题再封装一层业务组件这一节解决「怎么把组件库调成自己产品的样子」。antd-mobile 的主题体系完全建立在 CSS 变量上不改源码、不配置编译工具直接覆盖变量即可。改全局主题时注意官方推荐写:root:root而不是:root——因为库自己的主题变量也声明在:root下单写一个:root可能因优先级输了:root:root { --adm-color-primary: #a062d4; /* 主色Button/TabBar 高亮等 */ --adm-color-text: #333; /* 正文文字色 */ --adm-color-border: #eee; /* 边框色旧名 --adm-border-color 已弃用 */ }局部换肤同理把变量挂到任意容器节点上.purple-theme { --adm-color-primary: #a062d4; }div classNamepurple-theme Button colorprimary只有这块变紫/Button /div组件内也可以直接用style传变量如style{{ [--adm-color-primary]: #a062d4 }}。完整的变量清单颜色、字号、组件级变量在 docs/guide/theming.zh.md 和 docs/guide/css-variables.zh.md。二次封装的思路是「固定业务默认值放开口子给覆盖」import { Button } from antd-mobile import type { ButtonProps } from antd-mobile export const BrandButton (props: ButtonProps) ( Button shaperounded colorprimary {...props} / ){...props}放最后调用方随时能覆盖。团队里统一用BrandButton以后改品牌样式只动这一个文件。另外组件文案确认/取消/校验提示可以通过ConfigProvider的locale换成其他语言内置了 src/locales/ 下 30 多个语言包。真机适配与性能一份勾选清单这一节解决「模拟器上没问题、真机上翻车」的几件小事每条都是一句话能说完的配置刘海屏留白在内容区首尾各放一个SafeArea positiontop /和SafeArea positionbottom /普通屏幕上高度为 0全面屏上自动撑出留白。消灭 300ms 点击延迟head里加meta nameviewport contentwidthdevice-width或全局html { touch-action: manipulation; }。触摸热区可点元素保持至少 44px × 44px列表项、TabBar 项默认尺寸已满足自定义组件时别压得太小。高清屏适配全项目把 import 换成antd-mobile/2xumi 项目配antdMobile: { hd: true }即可1x 和 2x 千万别混用详见 docs/guide/hd.zh.md。弹窗锁滚动Popup、Mask 这类浮层会自动锁定 body 滚动不用自己写overflow: hidden补丁。老浏览器兼容babel 的targets设到chrome: 49, ios: 10且不要把node_modules排除在 babel 编译之外。深色模式也值得一试给html加data-prefers-color-schemedark即启用试验性阶段见 docs/guide/dark-mode.zh.md。踩坑与 FAQ五个最高频的问题 每条按「现象 → 原因 → 解法」给结论都来自官方 FAQ。1. umi 项目构建时报antd-mobile/es/button/style not found现象依赖找不到、构建直接失败。 原因旧版 umi 插件会按 v2 的目录结构做自动样式拆分和 v5 的目录对不上。 解法把umijs/preset-react、umijs/plugin-antd升到最新版或改装最新的umijs/plugin-antd-mobile。2. 手势类组件Swiper、Slider、Tabs 拖拽点不动或延迟现象滑不动、点击慢半拍。 原因项目里引了 fastclick或者 viewport 没配。 解法移除 fastclick并按上一条加 viewport metaHot Loader 也会干扰手势建议换 React Fast Refresh。3. 改了主题色不生效现象--adm-color-primary改了按钮还是默认蓝。 原因你的:root声明和库自带的:root声明优先级打平后加载的赢。 解法选择器写成:root:root提高优先级。4. 样式错乱、组件像「没加载样式」现象布局散架、弹窗没有蒙层样式。 原因手动按需引入时忘了引 global或者 1x / 2x 版本混用。 解法入口补import antd-mobile/es/global2x 走别名统一切换禁止两种 import 并存。5. iOS 9 上整站样式丢失现象只在很老的 iOS Safari 上白屏或裸奔。 解法iOS 9 不支持 CSS 变量按 CSS 变量降级 的说明开启自动降级并把 babel targets 的 ios 设为 9。速查表常见任务与对应入口常见任务对应能力关键 API / 入口全局轻反馈ToastToast.show/Toast.config/Toast.clear二次确认 / 提示DialogDialog.confirm/Dialog.alert顶部导航NavBarback/onBack/right底部导航TabBaractiveKey/onChangeicon支持函数搜索 列表SearchBar ListonSearch/List.Item的title、extra、prefix表单与校验FormForm.useForm/Form.Item的rules/footer刘海屏留白SafeAreapositiontop \| bottom主题定制CSS 变量:root:root覆盖--adm-color-primary等深色模式实验特性html上data-prefers-color-schemedark国际化ConfigProviderlocale内置 30 语言包高清适配2x 版本import from antd-mobile/2x组件 API 细节各组件文档各组件目录下的index.zh.md如 src/components/form/跑通第一个页面只是开始下一步建议按速查表把列表、表单、反馈三条线在你的业务里各走一遍再回头读 docs/guide/quick-start.zh.md 补齐 babel 配置与兼容性细节基本就是一个能上线的 H5 骨架了。【免费下载链接】ant-design-mobileEssential UI blocks for building mobile web apps.项目地址: https://gitcode.com/gh_mirrors/an/ant-design-mobile创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考