antd-mobile 从 0 到 1：5 分钟跑通，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 也可以

下面是整个项目最小的可运行入口，渲染一个主按钮，点击弹一个 Toast：

import { Button, Toast } from 'antd-mobile' export default () => ( <Button color='primary' 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 key='home' title='首页' icon={<AppOutline />} /> <TabBar.Item key='my' title='我的' icon={<UserOutline />} /> </TabBar>

TabBar 的icon支持传一个函数(active) => ...，选中态可以换实心图标，官方 demo（src/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 layout='horizontal' onFinish={async values => { await saveProfile(values) Toast.show({ icon: 'success', content: '已保存' }) }} footer={ <Button block type='submit' color='primary' size='large'> 提交 </Button> } > <Form.Item name='nickname' label='昵称' rules={[{ required: true, message: '昵称不能为空' }]}> <Input placeholder='请输入昵称' /> </Form.Item> </Form>

这里有两个「为什么这么写」：footer是 Form 的专属插槽，放提交按钮时按钮的type='submit'会触发整表校验，校验通过才进onFinish；layout='horizontal'让 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 className='purple-theme'> <Button color='primary'>只有这块变紫</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 shape='rounded' color='primary' {...props} /> )

{...props}放最后，调用方随时能覆盖。团队里统一用BrandButton，以后改品牌样式只动这一个文件。另外，组件文案（确认/取消/校验提示）可以通过ConfigProvider的locale换成其他语言，内置了 src/locales/ 下 30 多个语言包。

真机适配与性能：一份勾选清单

这一节解决「模拟器上没问题、真机上翻车」的几件小事，每条都是一句话能说完的配置：

• 刘海屏留白：在内容区首尾各放一个<SafeArea position='top' />和<SafeArea position='bottom' />，普通屏幕上高度为 0，全面屏上自动撑出留白。
• 消灭 300ms 点击延迟：head里加<meta name="viewport" content="width=device-width">，或全局html { touch-action: manipulation; }。
• 触摸热区：可点元素保持至少 44px × 44px，列表项、TabBar 项默认尺寸已满足，自定义组件时别压得太小。
• 高清屏适配：全项目把 import 换成antd-mobile/2x（umi 项目配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-scheme="dark"即启用（试验性阶段），见 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 meta；Hot Loader 也会干扰手势，建议换 React Fast Refresh。

3. 改了主题色不生效现象：--adm-color-primary改了，按钮还是默认蓝。 原因：你的:root声明和库自带的:root声明优先级打平，后加载的赢。 解法：选择器写成:root:root提高优先级。

4. 样式错乱、组件像「没加载样式」现象：布局散架、弹窗没有蒙层样式。 原因：手动按需引入时忘了引 global，或者 1x / 2x 版本混用。 解法：入口补import 'antd-mobile/es/global'；2x 走别名统一切换，禁止两种 import 并存。

5. iOS 9 上整站样式丢失现象：只在很老的 iOS Safari 上白屏或裸奔。 解法：iOS 9 不支持 CSS 变量，按 CSS 变量降级 的说明开启自动降级，并把 babel targets 的 ios 设为 9。

速查表：常见任务与对应入口

跑通第一个页面只是开始：下一步建议按速查表把列表、表单、反馈三条线在你的业务里各走一遍，再回头读 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