# Technical Documentation: ant-design/ant-design-mobile

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/ant-design/ant-design-mobile)

### Overview (`README.md`)

<div align="center">

  <img src="https://gw.alipayobjects.com/zos/bmw-prod/b2c7ff8b-eba0-4af9-9dd5-0b5b17f42c57.svg" alt="logo" width="200" height="auto" />
  <h1>Ant Design Mobile</h1>

  <p>
    Essential UI blocks for building mobile web apps. 
  </p>

[](https://www.npmjs.com/package/antd-mobile) [](https://github.com/ant-design/ant-design-mobile/releases) [](https://www.npmjs.com/package/antd-mobile) [](https://www.npmjs.com/package/antd-mobile) [](https://www.jsdelivr.com/package/npm/antd-mobile) [](https://unpkg.com/browse/antd-mobile@5/umd/antd-mobile.js) [](https://github.com/ant-design/ant-design-mobile/graphs/contributors) [](https://github.com/ant-design/ant-design-mobile/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)  [](https://codecov.io/gh/ant-design/ant-design-mobile) [](https://github.com/ant-design/ant-design-mobile)

  <h4>
    <a href="https://mobile.ant.design">English Doc</a>
  <span> · </span>
    <a href="https://mobile.ant.design/zh">中文文档</a>
  <span> · </span>
    <a href="https://discord.gg/jmNvw4WFYn">Discord</a>
  <span> · </span>
    <a href="https://mdn.alipayobjects.com/huamei_pdkywj/afts/img/A*nC08QYnlP68AAAAAAAAAAAAAesHxAQ/original">钉钉</a>
  </h4>
</div>

```bash
$ npm install antd-mobile
# or
$ yarn add antd-mobile
# or
$ pnpm add antd-mobile
# or
$ bun add antd-mobile
```

- **Fast**: It is carefully optimized for harsh scenes, without configuration, you can have the best package size and ultimate performance.
- **Customizable**: Based on CSS variables, you can reliably and efficiently adjust the appearance of components or create your own themes.
- **Atomic**: The function of each component, neither more nor less, is exactly what you need.
- **Fluent**: With smooth gestures and delicate animation, it helps the product create the ultimate experience.

You can also play with antd-mobile just in browser with [Codesandbox](https://codesandbox.io/s/antd-mobile-snrxr?file=/package.json). No need to prepare development environment.

If you found bugs or would like to request some new features, please consider opening an [issue](https://github.com/ant-design/ant-design-mobile/issues/new).

If you have some questions about how to use ant-mobile, you can start a [discussion thread](https://github.com/ant-design/ant-design-mobile/discussions).

---


## 🤝 Contributing 

Thanks to all the contributors of antd-mobile:

<a href="https://openomy.app/github/ant-design/ant-design-mobile" target="_blank" style="display: block; width: 100%;" align="center">
  <img src="https://www.openomy.app/svg?repo=ant-design/ant-design-mobile&chart=bubble&latestMonth=3" target="_blank" alt="Contribution Leaderboard" style="display: block; width: 100%;" />
</a>

<a href="https://github.com/ant-design/ant-design-mobile/graphs/contributors">
  <img src="https://opencollective.com/ant-design-mobile/contributors.svg?width=960&button=false" alt="contributors" />
</a>

---

### 404.En (`docs/404.en.md`)

Oops, seems this page does not exist.

[Back to Home](/)

---

### Index.En (`docs/index.en.md`)

---
title: Ant Design Mobile
full: true
gapless: true
---

<code src="./components/home-page.tsx" inline="true"></code>

---

### Index.Zh (`docs/index.zh.md`)

---
title: Ant Design Mobile
full: true
gapless: true
---

<code src="./components/home-page.tsx" inline="true"></code>

---

### Resources.En (`docs/resources.en.md`)

---
sidemenu: false
---

# Resources

Here is a summary of resources related to Ant Design Mobile.

## Design Resources

Here are the downloads of Ant Design Mobile related design resources and design tools, and more design resources are being sorted out and improved.

<ResourceCard title="Sketch Components" description="The Sketch component templates" link="https://gw.alipayobjects.com/os/bmw-prod/c68904d2-7c9e-43db-a219-4a093f0d452d.sketch" image="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*r5GrQLIP0OsAAAAAAAAAAAAAARQnAQ"></ResourceCard>

<ResourceCard title="Figma Components" description="The Figma component templates" link="https://gw.alipayobjects.com/os/bmw-prod/8a148021-e590-419a-b092-ba9879a89e40.zip" image="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*b2CjQ6X7vNkAAAAAAAAAAAAAARQnAQ"></ResourceCard>

<ResourceCard title="Press Kit" description="The logos and banners of antd-mobile" link="https://gw.alipayobjects.com/os/bmw-prod/ef00ee0b-7fda-4698-8ebf-b6367b582395.zip" image="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*_rmUTKBYs4MAAAAAAAAAAAAAARQnAQ"></ResourceCard>

## Tech Resources

<ResourceCard title="Blog" description="Some technical sharing" link="https://www.yuque.com/awmleer/rocket" image="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*PXoRS74Wr8sAAAAAAAAAAAAAARQnAQ"></ResourceCard>

<ResourceCard title="Codesandbox" description="Write demos online" link="https://codesandbox.io/s/antd-mobile-snrxr?file=/package.json" image="https://gw.alipayobjects.com/zos/bmw-prod/6fb7e052-b388-4aa1-904b-a595332914b9.svg"></ResourceCard>

<ResourceCard title="Stackblitz" description="Write demos online" link="https://stackblitz.com/edit/antd-mobile?file=index.tsx" image="https://gw.alipayobjects.com/zos/bmw-prod/612011bc-6bca-417f-9760-6f4048649815.svg"></ResourceCard>

## Other Links

[2.x doc site](https://antd-mobile-v2.surge.sh)

[3.x doc site (alpha)](https://antd-mobile-v3.surge.sh)

---

### Resources.Zh (`docs/resources.zh.md`)

---
sidemenu: false
---

# 资源

这里汇总了与 Ant Design Mobile 相关资源

## 设计资源

这里提供 Ant Design Mobile 相关设计资源和设计工具的下载，更多设计资源正在整理和完善中。

<ResourceCard title="Sketch 组件包" description="移动组件 Sketch 模板包" link="https://gw.alipayobjects.com/os/bmw-prod/c68904d2-7c9e-43db-a219-4a093f0d452d.sketch" image="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*r5GrQLIP0OsAAAAAAAAAAAAAARQnAQ"></ResourceCard>

<ResourceCard title="Figma 组件包" description="移动组件 Figma 模板包" link="https://gw.alipayobjects.com/os/bmw-prod/8a148021-e590-419a-b092-ba9879a89e40.zip" image="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*b2CjQ6X7vNkAAAAAAAAAAAAAARQnAQ"></ResourceCard>

<ResourceCard title="媒体素材" description="antd-mobile 的 logo 和 banner" link="https://gw.alipayobjects.com/os/bmw-prod/ef00ee0b-7fda-4698-8ebf-b6367b582395.zip" image="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*_rmUTKBYs4MAAAAAAAAAAAAAARQnAQ"></ResourceCard>

## 技术资源

<ResourceCard title="博客" description="一些技术分享" link="https://www.yuque.com/awmleer/rocket" image="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*PXoRS74Wr8sAAAAAAAAAAAAAARQnAQ"></ResourceCard>

<ResourceCard title="Codesandbox" description="在线写 demo" link="https://codesandbox.io/s/antd-mobile-snrxr?file=/package.json" image="https://gw.alipayobjects.com/zos/bmw-prod/6fb7e052-b388-4aa1-904b-a595332914b9.svg"></ResourceCard>

<ResourceCard title="Stackblitz" description="在线写 demo" link="https://stackblitz.com/edit/antd-mobile?file=index.tsx" image="https://gw.alipayobjects.com/zos/bmw-prod/612011bc-6bca-417f-9760-6f4048649815.svg"></ResourceCard>

## 其他相关链接

[2.x 文档站点](https://antd-mobile-v2.surge.sh)

[3.x 文档站点（alpha）](https://antd-mobile-v3.surge.sh)

---

### Guide Css Variables.En (`docs/guide/css-variables.en.md`)

# CSS Variables

Compared to the crude CSS style override (also known as the magic style), CSS Variables allow us to customize the style of the component more elegantly.

Let's take a look at how we should use the CSS variables exposed by the component.

> The premise of this article is that you have some basic understanding of [CSS variables](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties)

In the "CSS Variables" table of the component document, you can check which CSS variables are exposed by each component. Of course, you can also find it directly in the ts definition of the component.

Taking the Input component as an example, we can find a table similar to the following on its documentation:

| Name | Description | Default | Global |
| --- | --- | --- | --- |
| --border-radius | Border radius of the button. | `4px` | `--adm-button-border-radius` |
| --border-width | Border width of the button. | `1px` | `--adm-button-border-width` |

This means that it supports the `--border-radius` and `--border-width` variables.

Next, we need to set the value of the CSS variable. There are two ways:

### Method 1: Set in the CSS file

Add a custom `className` to the Button component:

```jsx
<Button className='my-button'/>
```

Then set CSS Variables in the CSS file

```css
.my-button {
  --border-radius: 2px;
}
```

### Method 2: Set directly through the style attribute

Directly through the `style` property of the component, it is simple and rude, suitable for small-scale adjustments:

```jsx
<Button style={{
  '--border-radius': '2px'
}}/>
```

### Method 3: Use the global variables

Let's assume you need to adjust the style of all the Buttons in your project. In this case, setting CSS variables for every Button is unrealistic. But you can use the "global" CSS variables (listed as the last column in the table above).

```css
:root:root {
  --adm-button-border-radius: 2px;
}
```

In this way, all the Buttons in page will be affected.

Of course, you can also adjust style for only part of the page. All you need to do is bind the global CSS variables to the root dom element of that area.

## CSS Variables Auto Fallback

CSS variables are natively supported in iOS Safari `>= 10` and Chrome `>= 49`, which should be sufficient for your project in most cases. But if your project needs to be compatible with iOS 9, you need to use a special way to achieve compatibility.

CSS variables are highly dynamic, and there is no reliable polyfill solution in the industry, so antd-mobile has officially provided a patch CSS since version `5.14.0`:

```js
import 'antd-mobile/bundle/css-vars-patch.css'
```

You can include it in your project to ensure that component styles don't get messed up in iOS 9.

> For `2x` projects, please import the corresponding `antd-mobile/2x/bundle/css-vars-patch.css`

This patch CSS will automatically determine the current browser environment and will only take effect if the browser does not support CSS variables. So in most cases, it won't take effect, and it won't have a direct impact on your project. But when it takes effect, all features that depend on CSS variables will no longer take effect, such as: theme settings, component styling based on CSS variables, dark mode.

Currently, only the following components support CSS variable degradation. We are still improving the CSS variable degradation capabilities of other components. Please pay attention to the subsequent releases:

- Button
- Cascader
- CenterPopup
- ErrorBlock
- Image
- Mask
- Modal
- PageIndicator
- Popover
- PopoverMenu
- ScrollMask
- Space
- SpinLoading
- Swiper
- Tabs
- Toast

---

### Guide Css Variables.Zh (`docs/guide/css-variables.zh.md`)

# CSS 变量

相比于粗暴的 CSS 样式覆盖（也被叫做魔改样式），CSS 变量让我们可以更加优雅地自定义组件的样式。

一起来看看我们该怎么使用组件暴露出来的 CSS 变量吧。

> 本文的前提是你已经对 [CSS 变量](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties)有一些基础的了解

在组件文档的 "CSS 变量" 表格中，你可以查阅到每个组件暴露了都哪些 CSS 变量，当然你也可以直接在组件的 ts 定义中找到。

以 Input 组件为例，我们可以在它的文档上找到类似于下面这样的表格：

| 属性            | 说明     | 默认值 | 全局变量                     |
| --------------- | -------- | ------ | ---------------------------- |
| --border-radius | 圆角大小 | `4px`  | `--adm-button-border-radius` |
| --border-width  | 边框宽度 | `1px`  | `--adm-button-border-width`  |

这表示了它支持了 `--border-radius` 和 `--border-width` 变量。

接下来，我们需要设置 CSS 变量的值，有两种方法：

### 方法一：在 CSS 文件中设置

给 Button 组件加一个自定义的 `className`：

```jsx
<Button className='my-button'/>
```

然后在 CSS 文件中设置 CSS 变量

```css
.my-button {
  --border-radius: 2px;
}
```

### 方法二：直接通过 style 属性设置

直接通过组件的 `style` 属性，简单粗暴，适合小范围的调整：

```jsx
<Button style={{
  '--border-radius': '2px'
}}/>
```

### 方法三：通过全局变量进行设置

假如你需要对整个项目中所有的 Button 都进行样式的调整，那么对每一个按钮进行 CSS 变量的设置显然是不现实的。在这种情况下，你可以通过"全局 CSS 变量"（也就是上面表格中的最后一列）进行统一的设置：

```css
:root:root {
  --adm-button-border-radius: 2px;
}
```

这样页面上全部的 Button 都会受到调整。

当然，你也可以"局部性"地进行调整，只需要把对应的 CSS 变量添加到对应的父级节点上。

## CSS 变量自动降级 <Experimental></Experimental>

CSS 变量在 iOS Safari `>= 10` 和 Chrome `>= 49` 版本下是有原生支持的，这在大多数情况下都足够满足你的项目需要了。但是如果你的项目需要兼容 iOS 9，那就需要用特殊的方式来实现兼容了。

CSS 变量具有很高的动态性，业界并没有很可靠的 polyfill 方案，因此 antd-mobile 从 `5.14.0` 版本开始，官方提供了一份补丁 CSS：

```js
import 'antd-mobile/bundle/css-vars-patch.css'
```

你可以在项目中引入它，来确保在 iOS 9 下组件样式也不会乱掉。

> 对于 `2x` 项目，请引入对应的 `antd-mobile/2x/bundle/css-vars-patch.css`

这份 patch CSS 会自动判断当前的浏览器环境，并且只在浏览器不支持 CSS 变量时才会生效。所以在大部分情况下，它都不会生效，对于你的项目也不会有直接的影响。但是当它生效时，所有依赖 CSS 变量的特性都不会再生效，例如：主题设置、基于 CSS 变量的组件样式调整、深色模式。

目前，只有以下组件支持了 CSS 变量降级，其他组件的 CSS 变量降级能力我们还在持续完善中，请关注后续的发布：

- Button
- Cascader
- CenterPopup
- ErrorBlock
- Image
- Mask
- Modal
- PageIndicator
- Popover
- PopoverMenu
- ScrollMask
- Space
- SpinLoading
- Swiper
- Tabs
- Toast

---

### Guide Dark Mode.En (`docs/guide/dark-mode.en.md`)

# Dark Mode <Experimental></Experimental>

antd-mobile has a built-in dark mode theme, you only need to set the attribute `data-prefers-color-scheme="dark"` on the `html` tag of the page to enable it.

If you need to dynamically control the switching of dark mode, or you can't directly control the `html` tag, you can use js to set the attribute:

```js
document.documentElement.setAttribute(
   'data-prefers-color-scheme',
   'dark'
)
```

At present, the dark mode is still in the experimental stage, and the access method may be adjusted in the future. In addition, if you find that some components are not fully adapted to dark mode during use, please submit an [issue](https://github.com/ant-design/ant-design-mobile/issues/new/choose).

<code src="../../src/global/demos/dark-mode/demo1.tsx"></code>

---

### Guide Dark Mode.Zh (`docs/guide/dark-mode.zh.md`)

# 深色模式 <Experimental></Experimental>

antd-mobile 内置了一套深色模式的主题，你只需要在页面的 `html` 标签上设置属性 `data-prefers-color-scheme="dark"` 即可启用。

如果你需要动态控制深色模式的切换，或者是不能直接控制 `html` 标签，那么可以使用 js 来设置属性：

```js
document.documentElement.setAttribute(
  'data-prefers-color-scheme',
  'dark'
)
```

目前深色模式还在试验性阶段，未来可能会调整接入方式。另外，如果你在使用过程中，发现了某些组件对深色模式的适配不够完善，欢迎来提交 [issue](https://github.com/ant-design/ant-design-mobile/issues/new/choose)。

<code src="../../src/global/demos/dark-mode/demo1.tsx"></code>

---

### Guide Faq.En (`docs/guide/faq.en.md`)

# FAQ

### Does it support mini program?

antd-mobile itself only supports React stack.

For Alipay mini programs, you can use [antd-mini](https://mini.ant.design/).

There is no corresponding twin component library for mini programs on WeChat and other platforms, and community members are welcome to develop them.

### Does it support React Native?

No. Consider using [antd-mobile-rn](https://github.com/ant-design/ant-design-mobile-rn).

### Why did you jump from v2 to v5? Where did v3 and v4 go?

V2 has been released a long time ago. In the last two years, we have developed two versions of v3 and v4 within the company, but they have not been released to the community in the end.

### Should I start using the v5 version now?

For new projects, we recommend using the v5 version directly.

For old projects, we recommend a gradual [migration plan](/guide/migration).

### How to check the exact version of antd-mobile installed in the project?

Open `node_modules/antd-mobile/package.json`, the value of the `version` field is the exact version of antd-mobile installed in the current project.

### How to solve the error after installing antd-mobile v5 in the umi project?

Due to the conflict between the old version of the umi plugin and antd-mobile v5, you may encounter errors similar to the following:

```
These dependencies were not found:

* antd-mobile/es/button in ./src/pages/home-my/index.tsx
* antd-mobile/es/button/style in ./src/pages/home-my/index.tsx
...
```

The solution is to upgrade the plug-in:

1. If your project relies on `@umijs/preset-react` (you can see it in the `package.json` file), please upgrade it to the latest version
2. If your project relies on `@umijs/plugin-antd` (you can see it in the `package.json` file), please upgrade it to the latest version
3. If your project has no dependencies on the above two npm packages, you can install the latest version of the `@umijs/plugin-antd-mobile` plugin

### How do I migrate from v2 to v5?

Please refer to the [migration guide](/guide/migration).

### How to avoid the 300ms delay of click?

Add this into `head` element：

```html
<meta name="viewport" content="width=device-width">
```

Or add some global style:

```css
html {
  touch-action: manipulation;
}
```

For the detailed explanation, please refer to:

- [300ms tap delay, gone away](https://developers.google.com/web/updates/2013/12/300ms-tap-delay-gone-away)
- [More Responsive Tapping on iOS](https://webkit.org/blog/5610/more-responsive-tapping-on-ios/)

### In my project, the component gesture operation of antd-mobile cannot take effect, how to solve it?

Please check if fastclick is introduced in the project, if so, try to remove it and try again.

### About React Hot Loader

React Hot Loader is relatively intrusive to the project, and many components in antd-mobile (such as Swiper Tabs Form TabBar SideBar Dropdown Space Steps) are not compatible with it, and React Hot Loader itself is also recommended in the README. Don't use it anymore, so please consider removing React Hot Loader or replacing it with [React Fast Refresh](https://github.com/facebook/react/issues/16604).

### How to write a duplicate demo on CodesandBox

Codesandbox is a browser-side sandbox runtime environment that supports a variety of popular build templates and can be used for rapid prototyping, DEMO presentations, Bug recovery, and more.

1. create a CodesandBox

   visit https://codesandbox.io/s/antd-mobile-snrxr to create a codesandbox online example

2. To ensure accurate reproduction, make sure that the version of your bug is the same as the antd-mobile version in the CodesandBox dependency.

3. When you're done reliving the code, don't forget to `save` to create a new instance, and then click the Share button appearing in the upper right corner to copy the URL to Issues.

### What is the `import xxx from 'demos'` that appears in the documentation demo?

`demos` is not an npm package, but an alias created in the antd-mobile project. Its implementation is [here](https://github.com/ant-design/ant-design-mobile/blob/master/src/demos/index.ts).

Please don't try `npm install demos`. You can just ignore them.

### Does antd-mobile have umd package on CDN?

Yes, please refer to [this document](/guide/pre-built-bundles) for specific usage.

---

### Guide Faq.Zh (`docs/guide/faq.zh.md`)

# FAQ

### 支持小程序吗？

antd-mobile 本身只支持 React 技术栈。

对于支付宝小程序，可以使用 [antd-mini](https://mini.ant.design/)。

微信和其他平台的小程序暂时还没有对应的孪生组件库，欢迎社区同学开发。

### 支持 React Native 吗？

不支持。可以考虑使用 [antd-mobile-rn](https://github.com/ant-design/ant-design-mobile-rn)。

### 为什么从 v2 直接跳跃到了 v5？v3 和 v4 跑到哪里去了？

v2 已经是很久之前发布的版本了，最近两年在公司内部，我们开发了 v3 v4 两个版本，但最终并未发布到社区上。

### 我应该现在开始使用 v5 版本吗？

对于新项目，我们推荐直接使用 v5 版本。

对于旧项目，我们建议采用渐进式的[迁移方案](/zh/guide/migration)。

### 如何查看项目中安装的 antd-mobile 的准确版本？

打开 `node_modules/antd-mobile/package.json`，里面 `version` 字段的值就是当前项目中安装的 antd-mobile 的准确版本。

### umi 项目安装 antd-mobile v5 后报错如何解决？

由于旧版本的 umi 插件和 antd-mobile v5 有一定的冲突，所以你可能会遇到类似下面这样的报错：

```
These dependencies were not found:

* antd-mobile/es/button in ./src/pages/home-my/index.tsx
* antd-mobile/es/button/style in ./src/pages/home-my/index.tsx
...
```

解决方法就是对插件进行一下升级：

1. 如果你的项目中依赖了 `@umijs/preset-react` （可以在 `package.json` 文件中看到），那么请把它升级到最新版
2. 如果你的项目中依赖了 `@umijs/plugin-antd` （可以在 `package.json` 文件中看到），那么请把它升级到最新版
3. 如果你的项目中上述两个 npm 包都没有依赖，那么可以安装最新版的 `@umijs/plugin-antd-mobile` 插件

### 从 v2 如何迁移到 v5？

请参考[迁移指南](/zh/guide/migration)。

### 如何避免 300ms 的点击延迟？

在 `head` 中增加以下内容：

```html
<meta name="viewport" content="width=device-width">
```

或者增加以下全局样式：

```css
html {
  touch-action: manipulation;
}
```

具体请参考这两篇文章：

- [300ms tap delay, gone away](https://developers.google.com/web/updates/2013/12/300ms-tap-delay-gone-away)
- [More Responsive Tapping on iOS](https://webkit.org/blog/5610/more-responsive-tapping-on-ios/)

### 在我的项目中，antd-mobile 的组件手势操作无法生效，该怎么解决？

请检查项目中是不是引入了 fastclick，如果有的话，尝试移除掉再试一下。

### 关于 React Hot Loader

React Hot Loader 对项目有比较大的侵入性， 而 antd-mobile 中的很多组件（例如 Swiper Tabs Form TabBar SideBar Dropdown Space Steps）并不能和它兼容，而且 React Hot Loader 本身也在 README 中写了推荐大家不要再使用，所以请考虑移除 React Hot Loader 或将其替换为 [React Fast Refresh](https://github.com/facebook/react/issues/16604)。

### 如何在 codesandbox 上写一个复现 demo

codesandbox 是一个浏览器端的沙盒运行环境，支持多种流行的构建模板，可以用于快速原型开发、DEMO 展示、Bug 还原等等。

1. 创建一个 codesandbox

   访问 https://codesandbox.io/s/antd-mobile-snrxr 创建一个 codesandbox 的在线示例

2. 为了保证准确复现，请保证你出现 bug 的版本与 codesandbox 依赖中的 antd-mobile 版本一致。

3. 完成代码复现后，别忘了`保存`以创建一个新的实例，然后点击右上角出现的 share 按钮，复制 url。

### 文档 demo 中出现的 `import xxx from 'demos'` 是什么？

`demos` 并不是一个 npm 包，而是 antd-mobile 项目中创建的一个别名。它的实现在[这里](https://github.com/ant-design/ant-design-mobile/blob/master/src/demos/index.ts)。

请不要尝试 `npm install demos`。你可以直接忽略它们。

### antd-mobile 有 CDN 上的 umd 包吗？

有的，具体用法请参考[这篇文档](/zh/guide/pre-built-bundles)。

---

### Guide Hd.En (`docs/guide/hd.en.md`)

# HD Adaptation

In some projects, you may want to use 2 times the size of the style file. In order to reduce your access cost, antd-mobile has built-in a set of preprocessed 2 times the size of the code, placed in the `2x` subdirectory.

You can replace the import of `antd-mobile` in the project with `antd-mobile/2x`, so that a 2x version of the component is loaded, for example:

```js
import { Button } from 'antd-mobile'
// ⬇️
import { Button } from 'antd-mobile/2x'

import 'antd-mobile/es/global'
// ⬇️
import 'antd-mobile/2x/es/global'
```

If you think it is too troublesome to add an extra `2x` every time you import it, you can consider configuring an alias from `antd-mobile` to `antd-mobile/2x` in webpack. For specific configuration methods, please refer to [webpack documentation ](https://webpack.js.org/configuration/resolve/#resolvealias).

If you are using the umi framework, you can directly install the latest version of `@umijs/preset-react` or `@umijs/plugin-antd-mobile`, and then configure in `config.js`:

```js
{
  antdMobile: {
    hd: true
  }
}
```

It is worth mentioning that you need to take care of your imports. Please don't write both `import xxx from 'antd-mobile'` and `import xxx from 'antd-mobile/2x'` in one same project.

---

### Guide Hd.Zh (`docs/guide/hd.zh.md`)

# 高清适配

在部分项目中，你可能希望使用 2 倍大小的样式文件，antd-mobile 为了降低你的接入成本，内置了一套经过预处理的 2 倍大小的代码，放置在 `2x` 子目录下。

你可以把项目中对 `antd-mobile` 的 import 替换为 `antd-mobile/2x`，这样加载的就是 2 倍大小版本的组件了，例如：

```js
import { Button } from 'antd-mobile'
// ⬇️
import { Button } from 'antd-mobile/2x'

import 'antd-mobile/es/global'
// ⬇️
import 'antd-mobile/2x/es/global'
```

如果你觉得每次引入都要额外加个 `2x` 太麻烦，可以考虑在 webpack 中配置一个从 `antd-mobile` 到 `antd-mobile/2x` 的别名，具体的配置方法请参考 [webpack 文档](https://webpack.js.org/configuration/resolve/#resolvealias)。

如果你使用的是 umi 框架，那么可以直接安装最新版的 `@umijs/preset-react` 或 `@umijs/plugin-antd-mobile`，然后在 `config.js` 中配置：

```js
{
  antdMobile: {
    hd: true
  }
}
```

需要特别注意的是，在同一个项目中，请不要混用 `import xxx from 'antd-mobile'` 和 `import xxx from 'antd-mobile/2x'`，这很有可能会导致严重的样式问题。因此，我们更推荐你使用上文提到的别名的方案进行配置。

---

### Guide I18n.En (`docs/guide/i18n.en.md`)

# Internationalization

### ConfigProvider

antd-mobile provides a Component [ConfigProvider](../components/config-provider) for configuring antd locale text globally.

```jsx
import { ConfigProvider } from "antd-mobile";
import enUS from 'antd-mobile/es/locales/en-US'

return (
  <ConfigProvider locale={enUS}>
    <App />
  </ConfigProvider>
)
```

The following languages are currently supported:

| Language              | Filename |
| --------------------- | -------- |
| Chinese (Simplified)  | zh-CN    |
| Chinese (Traditional) | zh-HK    |
| Chinese (Traditional) | zh-TW    |
| English               | en-US    |
| Persian               | fa-IR    |
| Spanish               | es-ES    |
| Hungarian             | hu-HU    |
| Korean                | ko-KR    |
| Japanese              | ja-JP    |
| Kazakh                | kk-KZ    |
| Indonesian            | id-ID    |
| Indonesian(old form)  | in-ID    |
| Italian               | it-IT    |
| Danish                | da-DK    |
| Norwegian (Bokmål)    | nb-NO    |
| Dutch (Netherlands)   | nl-NL    |
| Russian (Russia)      | ru-RU    |
| Turkish (Türkçe)      | tr-TR    |
| Thai                  | th-TH    |
| French                | fr-FR    |
| German                | de-DE    |
| Malay                 | ms-MY    |
| Arabic                | ar-SA    |
| Portuguese            | pt-BR    |
| Vietnamese            | vi-VN    |
| Serbian               | hr-HR    |
| Croatian              | sr-RS    |
| Montenegrin           | cnr-ME   |

See more usage at [ConfigProvider](../components/config-provider).

### Add new language

If your language is not above list, welcome to create a locale package based on the [en-US](https://github.com/ant-design/ant-design-mobile/blob/master/src/locales/en-US.ts) lanugage pack and send us a Pull Request. [language code table](http://www.lingoes.net/en/translator/langcode.htm)

Do it step by step:

1. Add a locale file in `src/locales`.
2. Add a test case for the language in [config-provider.test.tsx](https://github.com/ant-design/ant-design-mobile/blob/master/src/components/config-provider/tests/config-provider.test.tsx).
3. Run `pnpm test -u` command to update the snapshots.
4. (Optional) Add the language to i18n list [i18n.zh.md](https://github.com/ant-design/ant-design-mobile/blob/master/docs/guide/i18n.zh.md) 和 [i18n.en.md](https://github.com/ant-design/ant-design-mobile/blob/master/docs/guide/i18n.en.md).

## FAQ

### Why the ConfigProvider not work when component used in an imperative way?

Taking the Modal component as an example, antd-mobile will dynamic create React instance by `ReactDOM.render` when you call `Modal.show`. Whose context is different with origin code located context.

You can set the default language through `setDefaultConfig`

```jsx
import { setDefaultConfig } from 'antd-mobile'

setDefaultConfig({
  locale: enUS,
})
```

---

### Guide I18n.Zh (`docs/guide/i18n.zh.md`)

# 国际化

### ConfigProvider

antd-mobile 提供了 [ConfigProvider](../components/config-provider) 组件用于全局配置国际化文案。

```jsx
import { ConfigProvider } from "antd-mobile";
import enUS from 'antd-mobile/es/locales/en-US'

return (
  <ConfigProvider locale={enUS}>
    <App />
  </ConfigProvider>
)
```

目前支持以下语言：

| 语言                 | 文件名 |
| -------------------- | ------ |
| 简体中文             | zh-CN  |
| 繁体中文（中国香港） | zh-HK  |
| 繁体中文（中国台湾） | zh-TW  |
| 英语（美式）         | en-US  |
| 波斯语               | fa-IR  |
| 西班牙语             | es-ES  |
| 韩语                 | ko-KR  |
| 日语                 | ja-JP  |
| 哈萨克语             | kk-KZ  |
| 印度尼西亚语         | id-ID  |
| 印度尼西亚语（旧版） | in-ID  |
| 意大利语             | it-IT  |
| 丹麦语               | da-DK  |
| 挪威                 | nb-NO  |
| 荷兰语               | nl-NL  |
| 俄罗斯语             | ru-RU  |
| 土耳其语             | tr-TR  |
| 泰语                 | th-TH  |
| 法语                 | fr-FR  |
| 德语                 | de-DE  |
| 马来语               | ms-MY  |
| 阿拉伯语             | ar-SA  |
| 葡萄牙语             | pt-BR  |
| 越南语               | vi-VN  |
| 克罗地亚语           | hr-HR  |
| 塞尔维亚语           | sr-RS  |
| 黑山语               | cnr-ME |

具体的使用方法请参考 [ConfigProvider](../components/config-provider) 文档。

### 增加语言包

如果你找不到你需要的语言包，欢迎你在 [英文语言包](https://github.com/ant-design/ant-design-mobile/blob/master/src/locales/en-US.ts) 的基础上创建一个新的语言包，并给我们发一个 Pull Request。 [语言对照表](http://www.lingoes.net/en/translator/langcode.htm)

基本步骤如下：

1. 在 `src/locales` 中增加语言包。
2. 在 [config-provider.test.tsx](https://github.com/ant-design/ant-design-mobile/blob/master/src/components/config-provider/tests/config-provider.test.tsx) 添加改语言的测试用例。
3. 运行 `pnpm test -u` 命令，更新 snapshots。
4. （可选）更新文档 [i18n.zh.md](https://github.com/ant-design/ant-design-mobile/blob/master/docs/guide/i18n.zh.md) 和 [i18n.en.md](https://github.com/ant-design/ant-design-mobile/blob/master/docs/guide/i18n.en.md)，增加语言列表。

## FAQ

### 为什么组件指令式的调用不支持 ConfigProvider？

以 Modal 为例，直接调用 `Modal.show` 方法，antd-mobile 会通过 ReactDOM.render 动态创建新的 React 实体。其 context 与当前代码所在 context 并不相同，因而无法获取 context 信息。

可以通过 `setDefaultConfig` 设置默认语言

```jsx
import { setDefaultConfig } from 'antd-mobile'

setDefaultConfig({
  locale: enUS,
})
```

---

### Guide Import On Demand.En (`docs/guide/import-on-demand.en.md`)

# Import On Demand

antd-mobile supports on-demand loading based on Tree Shaking, most of the build tools (such as webpack 4+ and rollup) support Tree Shaking, so **in most cases, you don't need to do additional configuration** to have better Small package size.

## Import On Demand Manually

If your environment does not support Tree Shaking, then you can manually introduce some components:

```js
import Button from 'antd-mobile/es/components/button'
```

It should be noted that **when manually loading on demand, you also need to import the `global` file in the entry file to load some antd-mobile global logic and styles**:

```js
import 'antd-mobile/es/global'
```

Of course, if you think the above writing method is too cumbersome, you can also use [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) for automatic syntax conversion. It can be configured like this in `.babelrc`:

```js
module.exports = {
  "plugins": [
    ["import", { "libraryName": "antd-mobile", "libraryDirectory": "es/components", "style": false}]
  ]
}
```

<Alert type="error">
  Even if you use `babel-plugin-import`, you still need to manually import the `global` file in the entry file.
</Alert>

It is not difficult to find that manual on-demand loading is very difficult to maintain, especially when there are multiple entry files in your project. So unless you have a sufficient understanding of the packaging and construction process and antd-mobile itself, we do not recommend this manual processing.

---

### Guide Import On Demand.Zh (`docs/guide/import-on-demand.zh.md`)

# 按需加载

antd-mobile 支持基于 Tree Shaking 的按需加载，大部分的构建工具（例如 webpack 4+ 和 rollup）都支持 Tree Shaking，所以**绝大多数情况下你无需做额外的配置**即可拥有较小的包体积。

## 手动的按需加载

如果你的环境不支持 Tree Shaking，那么你可以手动引入部分组件：

```js
import Button from 'antd-mobile/es/components/button'
```

需要注意的是，**在手动按需加载时，你还需要在入口文件中引入 `global` 文件来加载一些 antd-mobile 的全局性逻辑和样式**：

```js
import 'antd-mobile/es/global'
```

当然，如果你觉得上面的写法过于繁琐，你也可以使用 [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 来进行自动语法转换。可以在 `.babelrc` 中这样配置：

```js
module.exports = {
  "plugins": [
    ["import", { "libraryName": "antd-mobile", "libraryDirectory": "es/components", "style": false}]
  ]
}
```

<Alert type="warning">
  即便你使用了 `babel-plugin-import`，你依然需要在入口文件中手动引入 `global` 文件。
</Alert>

不难发现，手动按需加载是非常难以维护的，特别是在你的项目中存在多个入口文件时。所以除非你对打包构建的过程和 antd-mobile 本身都有足够的了解，否则我们非常不推荐这样手动处理。

---

### Guide Migration.En (`docs/guide/migration.en.md`)

# Migrating from v2

v5 is a completely rewritten version, so there are lots of differences between v2 and v5. Actually, this shouldn't be called as "migration". It's about replacing one component library with another one.

In order to reduce the cost of migration, you can try to use some methods mentioned below to make v2 and v5 live alongside in your project at the same time.

## Method 1: Use antd-mobile-v2 (Recommended)

We have published a shadow npm package for v2 which is name as `antd-mobile-v2`. You can replace the v2 antd-mobile package in your project with this one.

First, install `antd-mobile-v2`:

```bash
$ npm install --save antd-mobile-v2
# or
$ yarn add antd-mobile-v2
# or
$ pnpm add antd-mobile-v2
```

And then, replace everything that uses `antd-mobile` with `antd-mobile-v2`. For example:

```jsx
import {Button} from 'antd-mobile'
// ⬇️
import {Button} from 'antd-mobile-v2'
```

Next, remove the old `antd-mobile` dependency. And try to run/test/build your project. Check if everything is working fine.

If you find that the component styles of v2 are lost at this time, you can manually import the style file in the entry file:

```js
import 'antd-mobile-v2/dist/antd-mobile.less';  // or 'antd-mobile-v2/dist/antd-mobile.css'
```

Finally, reinstall the `antd-mobile` package as v5:

```bash
$ npm install --save antd-mobile
# or
$ yarn add antd-mobile
# or
$ pnpm add antd-mobile
```

Now, the `antd-mobile` in project is v5, and `antd-mobile-v2` is v2.

> Although the above approach is simple to operate, it may lead to the full import of v2 components, which will bring a certain amount of package size overhead. If you have such strict requirements on package volume, you can configure antd-mobile-v2 Let's take a look at babel-plugin-import. The specific configuration method will not be introduced here, and it needs to be analyzed in detail.
>
> However, please note that v5 components do not need to configure babel-plugin-import. When configuring, please be careful not to write the libraryName wrong.

## Method 2: Install v5 via alias

We recommend you to use the method 1. Although it requires a little bit migration work, it can make the whole migration process less costly and more steady.

Of course, in case your project doesn't seem to be suitable to use method 1, we provided a backup plan for you.

You can use npm alias to install v5:

```bash
$ npm install --save antd-mobile-v5@npm:antd-mobile@5
# or
$ yarn add antd-mobile-v5@npm:antd-mobile@5
# or
$ pnpm add antd-mobile-v5@npm:antd-mobile@5
```

And after that, the corresponding `package.json` is:

```json
{
  "antd-mobile": "^2.3.2",
  "antd-mobile-v5": "npm:antd-mobile@5"
}
```

Now, `antd-mobile` is v2 and `antd-mobile-v5` is v5.

```js
import { Button } from 'antd-mobile' // v2
import { Button } from 'antd-mobile-v5' // v5
```

Please note that npm aliases are not well supported by all package managers

---

### Guide Migration.Zh (`docs/guide/migration.zh.md`)

# 从 v2 迁移

v5 是完全重写的一个版本，所以 v2 和 v5 的差异非常之大，其实不存在所谓的"迁移"，基本是替换为一套全新的组件。

为了降低迁移成本和难度，你可以通过下面提到的一些方法来实现 v2 和 v5 两个版本的共存：

## 方法一：使用 antd-mobile-v2（推荐）

我们为 v2 发布了一个单独的影子 npm 包：`antd-mobile-v2`，你可以先将原来项目中 v2 版本的 antd-mobile 替换为这个包。

先安装 `antd-mobile-v2`：

```bash
$ npm install --save antd-mobile-v2
# or
$ yarn add antd-mobile-v2
# or
$ pnpm add antd-mobile-v2
```

然后把项目中所有对 `antd-mobile` 的引入都替换为 `antd-mobile-v2`，例如：

```jsx
import {Button} from 'antd-mobile'
// ⬇️
import {Button} from 'antd-mobile-v2'
```

接下来，移除原有的 `antd-mobile` 依赖，运行（测试、构建）你的项目，确认一下是否一切是正常的。

如果此时你发现 v2 的组件样式丢失了，那么可以在入口文件中手动引入一下样式文件：

```js
import 'antd-mobile-v2/dist/antd-mobile.less';  // or 'antd-mobile-v2/dist/antd-mobile.css'
```

最后，重新安装 `antd-mobile` 为 v5 版本：

```bash
$ npm install --save antd-mobile
# or
$ yarn add antd-mobile
# or
$ pnpm add antd-mobile
```

现在，你项目中的 `antd-mobile` 是 v5 版本，`antd-mobile-v2` 是 v2 版本。

> 上面的这种思路虽然操作简单，但是可能会导致 v2 组件被全量引入，从而带来一定的打包体积开销，如果你对包体积有这比较严苛的要求，可以对 antd-mobile-v2 配置一下 babel-plugin-import，具体的配置方式这里就不再展开介绍了，需要具体情况具体分析。
>
> 不过请注意，v5 组件并不需要配置 babel-plugin-import，在配置时，请留意不要把 libraryName 写错。

## 方法二：通过别名安装 v5

我们更推荐你使用方法一进行迁移，它虽然需要一点点前期一次性的改造，但是却可以让整体的迁移成本更低，同时让后续的迁移更加平滑简单。

当然，如果你的项目环境无法使用这种迁移方式，我们也为你提供了备选方案。

你可以通过别名的方式来安装 antd-mobile v5，同时保留 v2 版本：

```bash
$ npm install --save antd-mobile-v5@npm:antd-mobile@5
# or
$ yarn add antd-mobile-v5@npm:antd-mobile@5
# or
$ pnpm add antd-mobile-v5@npm:antd-mobile@5
```

对应的 package.json 为：

```json
{
  "antd-mobile": "^2.3.2",
  "antd-mobile-v5": "npm:antd-mobile@5"
}
```

现在，你项目中的 `antd-mobile` 还是 v2 版本，`antd-mobile-v5` 是 v5 版本。

```js
import { Button } from 'antd-mobile' // v2
import { Button } from 'antd-mobile-v5' // v5
```

需要注意的是，npm 别名并不是所有的包管理器都有很好的支持。

---

### Guide Pre Built Bundles.En (`docs/guide/pre-built-bundles.en.md`)

# Pre-Built Bundles

antd-mobile provides a set of pre-built bundles, consisting of two parts:

js resource:

```text
/bundle/antd-mobile.cjs.development.js
/bundle/antd-mobile.es.development.js
/bundle/antd-mobile.umd.development.js
```

The above bundles with `.development` are only meant for development, and are not suitable for production. Minified and optimized production bundles are available at:

```text
/bundle/antd-mobile.cjs.js
/bundle/antd-mobile.es.js
/bundle/antd-mobile.umd.js
/bundle/antd-mobile.compatible.umd.js
```

Among them, we provide two versions of umd files, one is `antd-mobile.umd.js` not processed by babel, the compatibility is `Chrome >= 61` `iOS >= 11`, the other is processed by babel `antd-mobile.compatible.umd.js`, compatibility is `Chrome >= 49` `iOS >= 9`.

css resource:

```text
/bundle/css-vars-patch.css
/bundle/style.css
```

These pre-built js files do not contain css content, so usually, you need to selectively import a certain version of js resources (such as `/bundle/antd-mobile.umd.js`), and then add additional Import `/bundle/style.css`.

You can find it at [unpkg](https://unpkg.com/browse/antd-mobile@5/bundle/) or [jsdelivr](https://www.jsdelivr.com/package/npm/antd-mobile?path =bundle).

---

### Guide Pre Built Bundles.Zh (`docs/guide/pre-built-bundles.zh.md`)

# 预构建产物

antd-mobile 提供了一套预构建的产物，包括两部分：

js 资源：

```text
/bundle/antd-mobile.cjs.development.js
/bundle/antd-mobile.es.development.js
/bundle/antd-mobile.umd.development.js
```

上述带有 `.development` 的产物仅适用于开发环境，不适合用于生产环境。压缩优化后可用于生产环境的产物如下：

```text
/bundle/antd-mobile.cjs.js
/bundle/antd-mobile.es.js
/bundle/antd-mobile.umd.js
/bundle/antd-mobile.compatible.umd.js
```

其中我们提供了两个版本的 umd 文件，一个是未被 babel 处理的 `antd-mobile.umd.js`，兼容性为 `Chrome >= 61` `iOS >= 11`，另一个是经过 babel 处理的 `antd-mobile.compatible.umd.js`，兼容性为 `Chrome >= 49` `iOS >= 9`。

css 资源：

```text
/bundle/css-vars-patch.css
/bundle/style.css
```

这些预构建的 js 文件中是不包含 css 内容的，因此通常情况下，你需要选择性地引入某一个版本的 js 资源（例如 `/bundle/antd-mobile.umd.js`），然后再额外引入 `/bundle/style.css`。

你可以在 [unpkg](https://unpkg.com/browse/antd-mobile@5/bundle/) 或 [jsdelivr](https://www.jsdelivr.com/package/npm/antd-mobile?path=bundle) 上找到这些文件。

---

### Guide Quick Start.En (`docs/guide/quick-start.en.md`)

# Quick Start

## Installation

```bash
$ npm install --save antd-mobile
# or
$ yarn add antd-mobile
# or
$ pnpm add antd-mobile
# or
$ bun add antd-mobile
```

## Import

Just import the component directly and antd-mobile will automatically load css style files:

```js
import { Button } from 'antd-mobile'
```

If you are developing an internal project in alibaba group or ant group, please read [this additional guide](https://yuque.antfin.com/antd-mobile/kfcgs3/md4or5).

If you are using the umi framework, it is recommended to read "[How to solve the error after installing antd-mobile v5 in the umi project?](/guide/faq#how-to-solve-the-error-after-installing-antd-mobile-v5-in-the-umi-project)" in the FAQ.

## Compatibility

We recommend adding the following babel configuration, so that maximum compatibility can be achieved (iOS Safari `>= 10` and Chrome `>= 49`):

```json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "chrome": "49",
          "ios": "10"
        }
      }
    ]
  ]
}
```

<Alert type="warning">
  Do not exclude node_modules from babel compilation, otherwise the above configuration will not work
</Alert>

For TypeScript, antd-mobile is compatible with versions `>= 3.8`.

For React, antd-mobile is compatible with versions `^16.8.0` and `^17.0.0`.

Since iOS 9 does not support CSS variables, if you need to support iOS 9, please refer to [this document](/guide/css-variables#css-variables-auto-fallback) to enable automatic CSS variable degradation, and set target ios in babel configuration to `9`.

## Playground

If you don't want to configure your environment locally, you can also try it directly on [codesandbox](https://codesandbox.io/s/antd-mobile-snrxr?file=/package.json) or [stackblitz](https://stackblitz.com/edit/antd-mobile?file=index.tsx).

## Discussion Groups

- [DingDing](https://mdn.alipayobjects.com/huamei_pdkywj/afts/img/A*nC08QYnlP68AAAAAAAAAAAAAesHxAQ/original)
- [Discord](https://discord.gg/jmNvw4WFYn)

## Contributing

Everyone are welcomed to join the community of antd-mobile. If you want to contribute, please refer to [this guide](https://github.com/ant-design/ant-design-mobile/blob/master/.github/CONTRIBUTING.md).

---

### Guide Quick Start.Zh (`docs/guide/quick-start.zh.md`)

# 快速上手

## 安装

```bash
$ npm install --save antd-mobile
# or
$ yarn add antd-mobile
# or
$ pnpm add antd-mobile
# or
$ bun add antd-mobile
```

## 引入

直接引入组件即可，antd-mobile 会自动为你加载 css 样式文件：

```js
import { Button } from 'antd-mobile'
```

如果你开发的是阿里/蚂蚁内部项目，那么请额外阅读一下[这篇指引](https://yuque.antfin.com/antd-mobile/kfcgs3/md4or5)。

如果你使用的是 umi 框架，那么推荐阅读一下常见问题中的 "[umi 项目安装 antd-mobile v5 后报错如何解决？](/zh/guide/faq#umi-%E9%A1%B9%E7%9B%AE%E5%AE%89%E8%A3%85-antd-mobile-v5-%E5%90%8E%E6%8A%A5%E9%94%99%E5%A6%82%E4%BD%95%E8%A7%A3%E5%86%B3%EF%BC%9F)"。

## 兼容性

我们建议在项目中增加下面的 babel 配置，这样可以达到最大兼容性，为 iOS Safari `>= 10` 和 Chrome `>= 49`：

```json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "chrome": "49",
          "ios": "10"
        }
      }
    ]
  ]
}
```

<Alert type="warning">
  不要把 node_modules 排除在 babel 编译之外，不然上面的配置不会有效果
</Alert>

对于 TypeScript，我们兼容的版本是 `>= 3.8`。

对于 React，我们兼容的版本是 `^16.8.0` `^17.0.0` `^18.0.0`。

由于 iOS 9 并不支持 CSS 变量，因此如果你需要支持 iOS 9，请参考 [这篇文档](/zh/guide/css-variables#css-变量自动降级) 启用 CSS 变量自动降级，并且将 babel 配置中的 target ios 设置为 `9`。

## 在线体验

如果你不想在本地配置环境，也可以直接在 [codesandbox](https://codesandbox.io/s/antd-mobile-snrxr?file=/package.json) 或 [stackblitz](https://stackblitz.com/edit/antd-mobile?file=index.tsx) 上进行体验。

## 讨论组

欢迎加入我们的钉钉交流群：

<img src="https://mdn.alipayobjects.com/huamei_pdkywj/afts/img/A*nC08QYnlP68AAAAAAAAAAAAAesHxAQ/original" alt="ding-group" width="300" />

或者也可以加入我们的 Discord 讨论组：

https://discord.gg/jmNvw4WFYn

## 参与贡献

antd-mobile 社区欢迎每一位社区朋友，如果你想参与建设，可以阅读[这篇指南](https://github.com/ant-design/ant-design-mobile/blob/master/.github/CONTRIBUTING.md)。

---

### Guide Reduce Motion.En (`docs/guide/reduce-motion.en.md`)

# Reduce Motion <Experimental></Experimental>

In some scenarios, you may not want various complex animation effects on the interface, so you can control the animation effects of components through the `reduceMotion` and `restoreMotion` functions provided by antd-mobile.

When you call `reduceMotion()`, the antd-mobile component will skip the animation as much as possible.

```jsx
import { reduceMotion } from 'antd-mobile'

reduceMotion()
```

It should be noted that `reduceMotion()` will only control the components provided by antd-mobile, and will not affect your own components in your business project.

When you want to restore the animation effect, you can call `restoreMotion()`.

## Demos

<code src="../../src/utils/demos/reduce-motion/demo1.tsx"></code>

<code src="../../src/utils/demos/reduce-motion/demo2.tsx"></code>

## Follow System Settings

In some cases, you may want the animation compatibility to follow the system settings directly, such as the "Accessibility - Compatible Motion Effects" setting under iOS:

<img alt="reduce-motion-en" src="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*MiDURJ7_vAwAAAAAAAAAAAAAARQnAQ" width="500px" />

Then you can use it with [react-reduce-motion](https://github.com/infiniteluuke/react-reduce-motion):

```jsx
import { useReducedMotion } from 'react-reduce-motion'
import { reduceMotion, restoreMotion } from 'antd-mobile'

const MyApp = () => {
  const prefersReducedMotion = useReducedMotion()
  React.useEffect(() => {
    if (prefersReducedMotion) {
      reduceMotion()
    } else {
      restoreMotion()
    }
  }, [prefersReducedMotion])
  // ...
}
```

---

### Guide Reduce Motion.Zh (`docs/guide/reduce-motion.zh.md`)

# 减弱动效 <Experimental></Experimental>

在一些场景下，你可能并不希望界面上存在各种复杂的动画效果，那么可以通过 antd-mobile 提供的 `reduceMotion` 和 `restoreMotion` 函数，来控制组件的动画效果。

当你调用 `reduceMotion()` 之后，antd-mobile 的组件会尽可能的跳过动画效果。

```jsx
import { reduceMotion } from 'antd-mobile'

reduceMotion()
```

需要注意的是，`reduceMotion()` 只会控制 antd-mobile 提供的组件，不会影响你业务项目中自己的组件。

当你希望恢复动画效果时，可以调用 `restoreMotion()`。

## 示例

<code src="../../src/utils/demos/reduce-motion/demo1.tsx"></code>

<code src="../../src/utils/demos/reduce-motion/demo2.tsx"></code>

## 跟随系统设置

一些情况下，你可能会希望动画是否减弱直接跟随系统设置，例如 iOS 下的 "辅助功能 - 减弱动态效果" 设置：

<img alt="reduce-motion-zh" src="https://gw.alipayobjects.com/mdn/rms_25513e/afts/img/A*LVkBSrQkji4AAAAAAAAAAAAAARQnAQ" width="500px" />

那么可以配合 [react-reduce-motion](https://github.com/infiniteluke/react-reduce-motion) 使用：

```jsx
import { useReducedMotion } from 'react-reduce-motion'
import { reduceMotion, restoreMotion } from 'antd-mobile'

const MyApp = () => {
  const prefersReducedMotion = useReducedMotion()
  React.useEffect(() => {
    if (prefersReducedMotion) {
      reduceMotion()
    } else {
      restoreMotion()
    }
  }, [prefersReducedMotion])
  // ...
}
```

---

### Guide Ssr.En (`docs/guide/ssr.en.md`)

# Server-side Rendering / SSR <Experimental></Experimental>

The support for SSR (server-side rendering) is still in the initial stage. If you find bugs during use, please submit an issue to us.

## Next.js

Using antd-mobile in Next.js requires some additional configuration.

### Next.js 12

First, you need to install `next-transpile-modules`:

```bash
$ npm install --save-dev next-transpile-modules
# or
$ yarn add -D next-transpile-modules
# or
$ pnpm add -D next-transpile-modules
# or
$ bun add -D next-transpile-modules
```

Then configure it in `next.config.js`:

```js
const withTM = require('next-transpile-modules')([
  'antd-mobile',
]);

module.exports = withTM({
  // other Next.js configuration in your project
});
```

### Next.js 13

Next.js 13 can automatically transpile and bundle dependencies from external dependencies (`node_modules`). This replaces the `next-transpile-modules` package.

```js
// next.config.js
const nextConfig = {
  transpilePackages: ['antd-mobile'],
};

module.exports = nextConfig;
```

To use antd-mobile in `app` directory, add the `'use client'` directive at the top of the file.

```jsx
// app/page.jsx
'use client'

import { Button } from 'antd-mobile'
```

- [transpilepackages](https://beta.nextjs.org/docs/api-reference/next.config.js#transpilepackages)
- [server-and-client-components](https://beta.nextjs.org/docs/rendering/server-and-client-components)

## Remix

Using antd-mobile in Remix requires some additional configuration.

Add antd-mobile config in `tsconfig.json` `compilerOptions.paths` field, Add `global.d.ts` in `include` field:

```json
{
  "include": ["remix.env.d.ts", "global.d.ts", "**/*.ts", "**/*.tsx"],
  "compilerOptions": {
    ...
    "paths": {
      "antd-mobile": ["node_modules/antd-mobile/bundle/antd-mobile.es.js"]
    }
  }
}
```

Add `global.d.ts` file in project root dir.

```ts
declare module 'antd-mobile' {
  export * from 'antd-mobile/es';
}
```

Import style file in `app/root.tsx`:

```ts
import styles from "antd-mobile/bundle/style.css";

export function links() {
  return [{ rel: "stylesheet", href: styles }];
}
```

- [remix template](https://github.com/3lang3/antd-mobile-template/tree/main/remix)

---

### Guide Ssr.Zh (`docs/guide/ssr.zh.md`)

# 服务端渲染 / SSR <Experimental></Experimental>

对 SSR（服务端渲染）的支持目前还处在比较初始的阶段，如果你在使用过程中发现了 bug，欢迎向我们提交 issue。

## Next.js

在 Next.js 中使用 antd-mobile 需要做一些额外的配置。

### Next.js 12

首先，需要安装 `next-transpile-modules` 依赖：

```bash
$ npm install --save-dev next-transpile-modules
# or
$ yarn add -D next-transpile-modules
# or
$ pnpm add -D next-transpile-modules
# or
$ bun add -D next-transpile-modules
```

然后在 `next.config.js` 中进行配置：

```js
const withTM = require('next-transpile-modules')([
  'antd-mobile',
]);

module.exports = withTM({
  // 你项目中其他的 Next.js 配置
});
```

### Next.js 13

Next.js 13 可以通过配置自动处理 `node_modules` 中的依赖，不再需要 `next-transpile-modules`。

```js
// next.config.js
const nextConfig = {
  transpilePackages: ['antd-mobile'],
};

module.exports = nextConfig;
```

如果在 `app` 目录下使用 antd-mobile，需要在文件顶部添加 `'use client'` 指令。

```jsx
// app/page.jsx
'use client'

import { Button } from 'antd-mobile'
```

- [transpilepackages](https://beta.nextjs.org/docs/api-reference/next-config#transpilepackages)
- [server-and-client-components](https://beta.nextjs.org/docs/rendering/server-and-client-components)

## Remix

在 Remix 中使用 antd-mobile 需要做一些额外的配置。

在 `tsconfig.json` 的 `compilerOptions.paths` 中新增 antd-mobile 配置，`include` 中添加 `global.d.ts`:

```json
{
  "include": ["remix.env.d.ts", "global.d.ts", "**/*.ts", "**/*.tsx"],
  "compilerOptions": {
    ...
    "paths": {
      "antd-mobile": ["node_modules/antd-mobile/bundle/antd-mobile.es.js"]
    }
  }
}
```

在根目录新增 `global.d.ts` 文件:

```ts
declare module 'antd-mobile' {
  export * from 'antd-mobile/es';
}
```

最后在 `app/root.tsx` 中引入样式文件:

```ts
import styles from "antd-mobile/bundle/style.css";

export function links() {
  return [{ rel: "stylesheet", href: styles }];
}
```

- [remix template](https://github.com/3lang3/antd-mobile-template/tree/main/remix)

---

### Guide Theming.En (`docs/guide/theming.en.md`)

# Theming

Thanks to the powerful and flexible capabilities of CSS variables, it is very simple to customize a set of antd-mobile themes. You don’t need to configure any compilation tools or install additional plug-ins. You can fix it directly in `:root` to overwrite CSS Variables are fine:

```css
:root:root {
  --adm-color-primary: #a062d4;
}
```

> Note: Why write two duplicate `:root`?
>
> Since the theme variables in antd-mobile are also declared under `:root`, in some cases they cannot be successfully overwritten due to priority issues. Through `:root:root` you can explicitly make the content you write a higher priority to ensure the successful coverage of the theme variables.

Of course, if you just want to adjust the partial theme, you can also add the above CSS variable override logic to any node you want to adjust, for example:

```css
.purple-theme {
  --adm-color-primary: #a062d4;
}
```

```jsx
<div className='purple-theme'>
  <Button color='primary'>Purple</Button>
</div>
```

You can get a button like this:

```jsx | preview
/**
 * inline: true
 */

import React from 'react'
import { Button } from 'antd-mobile'

export default () => {
  return (
    <div style={{
      ['--adm-color-primary']: '#a062d4',
    }}>
      <Button color='primary'>Purple</Button>
    </div>
  )
}
```

The following are the global CSS variables currently provided by antd-mobile:

```css
:root {
  --adm-color-primary: #1677ff;
  --adm-color-success: #00b578;
  --adm-color-warning: #ff8f1f;
  --adm-color-danger: #ff3141;

  --adm-color-white: #ffffff;
  --adm-color-text: #333333;
  --adm-color-text-secondary: #666666;
  --adm-color-weak: #999999;
  --adm-color-light: #cccccc;
  --adm-color-border: #eeeeee;
  --adm-color-box: #f5f5f5;
  --adm-color-background: #ffffff;

  --adm-font-size-main: var(--adm-font-size-5);

  --adm-font-family: -apple-system, blinkmacsystemfont, 'Helvetica Neue',
  helvetica, segoe ui, arial, roboto, 'PingFang SC', 'miui',
  'Hiragino Sans GB', 'Microsoft Yahei', sans-serif;
}
```

<Alert type="warning">
  The --adm-border-color variable has been deprecated since version 5.14.0, if you use it in your project, please replace it with --adm-color-border. We will remove --adm-border-color in the next major release.
</Alert>

Besides, every component has its own global CSS variables. You can find more information in their document page. For detailed explanation, please refer the [CSS Variables](/guide/css-variables) chapter.

---

### Guide Theming.Zh (`docs/guide/theming.zh.md`)

# 主题

得益于 CSS 变量强大而灵活的能力，自定义一套 antd-mobile 的主题是非常简单的，你不需要配置任何编译工具，也不需要安装额外的插件，直接修在 `:root` 覆盖 CSS 变量就可以了：

```css
:root:root {
  --adm-color-primary: #a062d4;
}
```

> 注：为什么要写两个重复的 `:root`？
>
> 由于 antd-mobile 中的主题变量也是在 `:root` 下声明的，所以在有些情况下会由于优先级的问题无法成功覆盖。通过 `:root:root` 可以显式地让你所写内容的优先级更高一些，从而确保主题变量的成功覆盖。

当然如果你只是希望对局部的主题进行调整，也可以把上面的 CSS 变量覆盖逻辑加在任何一个你想调整的节点上，例如：

```css
.purple-theme {
  --adm-color-primary: #a062d4;
}
```

```jsx
<div className='purple-theme'>
  <Button color='primary'>Purple</Button>
</div>
```

可以得到这样的一个按钮：

```jsx | preview
/**
 * inline: true
 */

import React from 'react'
import { Button } from 'antd-mobile'

export default () => {
  return (
    <div style={{
      ['--adm-color-primary']: '#a062d4',
    }}>
      <Button color='primary'>Purple</Button>
    </div>
  )
}
```

以下是 antd-mobile 目前提供的全局性 CSS 变量：

```css
:root {
  --adm-color-primary: #1677ff;
  --adm-color-success: #00b578;
  --adm-color-warning: #ff8f1f;
  --adm-color-danger: #ff3141;

  --adm-color-white: #ffffff;
  --adm-color-text: #333333;
  --adm-color-text-secondary: #666666;
  --adm-color-weak: #999999;
  --adm-color-light: #cccccc;
  --adm-color-border: #eeeeee;
  --adm-color-box: #f5f5f5;
  --adm-color-background: #ffffff;

  --adm-font-size-main: var(--adm-font-size-5);

  --adm-font-family: -apple-system, blinkmacsystemfont, 'Helvetica Neue',
  helvetica, segoe ui, arial, roboto, 'PingFang SC', 'miui',
  'Hiragino Sans GB', 'Microsoft Yahei', sans-serif;
}
```

<Alert type="warning">
  从 5.14.0 版本起，--adm-border-color 变量已经被弃用了，如果你在项目中用到了它，请替换为 --adm-color-border。我们将在下个大版本中移除 --adm-border-color。
</Alert>

此外，每个组件也有自己对应的 CSS 全局变量，你可以在它们的文档页面中找到，具体请参阅 [CSS 变量](/zh/guide/css-variables) 章节。

---

### Guide V5 For 19.En (`docs/guide/v5-for-19.en.md`)

# React 19 Compatibility

<Alert type="info">
  antd-mobile v5 compatibility with React 16 ~ 18 by default. For React 19, you can use the following compatibility methods to adapt. This compatibility method and interface will be removed in the next major version.
</Alert>

### React 19 Compatibility Issues

Since React 19 adjusted the export method of `react-dom`, antd-mobile cannot directly use the `ReactDOM.render` method. Therefore, using antd-mobile will encounter the following problems:

- React 19 RC react-dom no longer exports createRoot [#6635](https://github.com/ant-design/ant-design-mobile/issues/6635)
- Toast not supported in the latest React version [#6842](https://github.com/ant-design/ant-design-mobile/issues/6842)
- Uncaught (in promise) TypeError: reactRender is not a function [#6814](https://github.com/ant-design/ant-design-mobile/issues/6814)

Therefore, you need to use a compatibility configuration to make antd-mobile work properly in React 19.

### Compatibility Methods

#### unstableSetRender

`unstableSetRender` is a low-level registration method that allows developers to modify the rendering method of ReactDOM. Write the following code at the entry of your application:

```js
import { unstableSetRender } from 'antd-mobile'; // Support since version ^5.40.0
import { createRoot } from 'react-dom/client';

unstableSetRender((node, container) => {
  container._reactRoot ||= createRoot(container);
  const root = container._reactRoot;
  root.render(node);
  return async () => {
    await new Promise((resolve) => setTimeout(resolve, 0));
    root.unmount();
  };
});
```

---

### Guide V5 For 19.Zh (`docs/guide/v5-for-19.zh.md`)

# React 19 兼容

<Alert type="info">
  antd-mobile v5 默认兼容 React 16 ~ 18 版本，对于 React 19 版本，可以使用以下兼容方法进行适配。该兼容方式以及接口将在下一个 major 版本被移除。
</Alert>

### React 19 兼容问题

由于 React 19 调整了 `react-dom` 的导出方式，导致 antd-mobile 无法直接使用 `ReactDOM.render` 方法。因而使用 antd-mobile 会遇到以下问题：

- React 19 RC react-dom 不再导出 createRoot [#6635](https://github.com/ant-design/ant-design-mobile/issues/6635)
- Toast 在最新的 react 版本上不支持 [#6842](https://github.com/ant-design/ant-design-mobile/issues/6842)
- Uncaught (in promise) TypeError: reactRender is not a function [#6814](https://github.com/ant-design/ant-design-mobile/issues/6814)

因而需要通过兼容配置，使 antd-mobile 在 React 19 中正常工作。

### 兼容方式

#### unstableSetRender

`unstableSetRender` 为底层注册方法，允许开发者修改 ReactDOM 的渲染方法。在你的应用入口处写入：

```js
import { unstableSetRender } from 'antd-mobile'; // Support since version ^5.40.0
import { createRoot } from 'react-dom/client';

unstableSetRender((node, container) => {
  container._reactRoot ||= createRoot(container);
  const root = container._reactRoot;
  root.render(node);
  return async () => {
    await new Promise((resolve) => setTimeout(resolve, 0));
    root.unmount();
  };
});
```

---

### Guide What Is Experimental.En (`docs/guide/what-is-experimental.en.md`)

# What are 'Experimental Features'?

Experimental features are some features that we are still in the exploratory stage, such as some components whose API and interaction are not yet certain, some technical solutions that may be adjusted in the future, and some component properties whose names or meanings may change in the future. We will release it publicly ahead of time, and **it will be identified by a reagent bottle <Experimental></Experimental> icon** on the document. Developers can try it out, feedback and suggestions are welcome.

**In future minor and major releases, these experimental features may have functional changes, API break changes, or even be completely removed**. But don't worry, we will **explicitly warn you in the release log** when:

- an experimental feature breaks change
- an experimental feature has reached the maturity standard and is changed from an experimental feature to a regular feature

**So if you use these experimental features, we recommend:**

- Subscribe and follow our [release log](https://github.com/ant-design/ant-design-mobile/releases) (highly recommended)
- Use lockfile to lock the version (recommended)
- Manually set the version range of antd-mobile dependencies to `~` (recommended)

Of course, we maintain consistently strict quality standards for both experimental and regular features.

---

### Guide What Is Experimental.Zh (`docs/guide/what-is-experimental.zh.md`)

# 什么是试验性

试验性特性是一些我们还处于探索阶段的特性，例如一些 API 和交互还不太确定的组件，一些可能在未来有所调整的技术方案，一些命名或者含义可能会在未来发生变动的组件属性。 我们会提前将其公开发布出来，并且会在文档上有一个**试剂瓶 <Experimental></Experimental> 的图标进行标识**。各位开发者可以尝试使用，也欢迎反馈意见和建议～

**在未来的 minor 和 major 版本中，这些试验性的特性可能会功能发生变化，API 出现 break change，甚至会被完全移除掉**。但是不要担心，我们会在以下情况发生时，**明确地在发布日志中进行提示**：

- 当一个试验性特性出现 break change 时
- 当一个试验性特性已经达到成熟标准，从试验性特性变为常规特性时

**所以如果你使用了这些试验性特性，我们推荐：**

- 订阅和关注我们的[发布日志](https://github.com/ant-design/ant-design-mobile/releases)（强烈推荐）
- 使用 lockfile 锁定版本（推荐）
- 手动设置 antd-mobile 依赖的版本范围为 `~` （推荐）

当然，不管是试验性特性还是常规特性，我们都会对它们保持一贯严格的质量标准。

---

### Components Icon Index.En (`docs/components/icon/index.en.md`)

# Icon

The icons are in a separate npm package. If you want to use the icons, you need to install it first:

```bash
npm install --save antd-mobile-icons
# or
yarn add antd-mobile-icons
# or
pnpm add antd-mobile-icons
# or
bun add antd-mobile-icons
```

Then just import the icons you need from this package:

```js
import { AntOutline } from 'antd-mobile-icons'
```

Since the mainstream build tools automatically do Tree-Shaking, only the icons you use will be packaged in, so you don't have to worry about package size.

## Icon List

<code src="./demo-all.tsx" inline="true"></code>

## Example

<code src="./demo-single.tsx"></code>

---

### Components Icon Index.Zh (`docs/components/icon/index.zh.md`)

# Icon 图标

图标是在一个单独的 npm 包中，如果你想使用图标，需要先安装它：

```bash
npm install --save antd-mobile-icons
# or
yarn add antd-mobile-icons
# or
pnpm add antd-mobile-icons
# or
bun add antd-mobile-icons
```

然后从这个包中引入你所需要的图标即可：

```js
import { AntOutline } from 'antd-mobile-icons'
```

由于主流的构建工具会自动做 Tree-Shaking，所以最终被打包进来的只有你用到的那些图标，不必担心包体积问题。

## 图标列表

<code src="./demo-all.tsx" inline="true"></code>

## 使用示例

<code src="./demo-single.tsx"></code>

---

--- METRICS ---
- Files Extracted: 36
- Estimated Token Budget: ~14915 tokens
- Canonical Reference: https://codewiki.google/github.com/ant-design/ant-design-mobile