## File: README.md

<h3 align="center">轻量、可靠的小程序 UI 组件库</h3>





---

### 介绍

Vant 是一个**轻量、可靠的移动端组件库**，于 2017 年开源。

目前 Vant 官方提供了 [Vue 2 版本](https://vant-ui.github.io/vant/v2/)、[Vue 3 版本](https://vant-ui.github.io/vant/)和[微信小程序版本](http://vant-ui.github.io/vant-weapp/)，并由社区团队维护 [React 版本](https://github.com/3lang3/react-vant)和[支付宝小程序版本](https://github.com/ant-move/Vant-Aliapp)。

## 预览

扫描下方小程序二维码，体验组件库示例。注意：因微信审核机制限制，目前示例小程序不是最新版本，可以 clone 代码到本地开发工具预览



## 使用之前

使用 Vant Weapp 前，请确保你已经学习过微信官方的 [小程序简易教程](https://developers.weixin.qq.com/miniprogram/dev/framework/) 和 [自定义组件介绍](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/)。

## 安装

### 方式一. 通过 npm 安装 (推荐)

小程序已经支持使用 npm 安装第三方包，详见 [npm 支持](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html?search-key=npm)

```bash
# 通过 npm 安装
npm i @vant/weapp -S --production

# 通过 yarn 安装
yarn add @vant/weapp --production

# 安装 0.x 版本
npm i vant-weapp -S --production
```

### 方式二. 下载代码

直接通过 git 下载 Vant Weapp 源代码，并将 `dist` 目录拷贝到自己的项目中。

```bash
git clone https://github.com/youzan/vant-weapp.git
```

## 使用组件

以按钮组件为例，只需要在 json 文件中引入按钮对应的自定义组件即可

```json
{
  "usingComponents": {
    "van-button": "/path/to/vant-weapp/dist/button/index"
  }
}
```

接着就可以在 wxml 中直接使用组件

```html
<van-button type="primary">按钮</van-button>
```

## 在开发者工具中预览

```bash
# 安装项目依赖
npm install

# 执行组件编译
npm run dev
```

打开[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)，把`vant-weapp/example`目录添加进去就可以预览示例了。

PS：关于 `van-area` Area 省市区选择组件，地区数据初始化可以直接在云开发环境中导入`vant-weapp/example/database_area.JSON` 文件使用。

## 基础库版本

Vant Weapp 最低支持到小程序基础库 2.6.5 版本。

## 链接

- [文档网站（GitHub）](https://vant-ui.github.io/vant-weapp/)
- [文档网站（国内）](https://vant.pro/vant-weapp/)
- [意见反馈](https://github.com/youzan/vant-weapp/issues)
- [设计资源](https://vant-ui.github.io/vant/#/zh-CN/design)
- [更新日志](https://vant-ui.github.io/vant-weapp/#/changelog)
- [官方示例](https://github.com/vant-ui/vant-demo)

## 核心团队

以下是 Vant 和 Vant Weapp 的核心贡献者们：

| [](https://github.com/chenjiahan/) | [](https://github.com/cookfront/) | [](https://github.com/w91/) | [](https://github.com/pangxie1991/) | [](https://github.com/rex-zsd/) | [](https://github.com/nemo-shen/) |
| :-: | :-: | :-: | :-: | :-: | :-: |
| [chenjiahan](https://github.com/chenjiahan/) | [cookfront](https://github.com/cookfront/) | [wangnaiyi](https://github.com/w91/) | [pangxie](https://github.com/pangxie1991/) | [rex-zsd](https://github.com/rex-zsd/) | [nemo-shen](https://github.com/nemo-shen/) |

| [](https://github.com/Lindysen/) | [](https://github.com/JakeLaoyu/) | [](https://github.com/landluck/) | [](https://github.com/wjw-gavin/) | [](https://github.com/inottn/) | [](https://github.com/zhousg/) |
| :-: | :-: | :-: | :-: | :-: | :-: |
| [Lindysen](https://github.com/Lindysen/) | [JakeLaoyu](https://github.com/JakeLaoyu/) | [landluck](https://github.com/landluck/) | [wjw-gavin](https://github.com/wjw-gavin/) | [inottn](https://github.com/inottn/) | [zhousg](https://github.com/zhousg/) |

## 贡献者们

感谢以下小伙伴们为 Vant Weapp 发展做出的贡献：

<a href="https://github.com/youzan/vant-weapp/graphs/contributors">
  
</a>

## 开源协议

本项目基于 [MIT](https://zh.wikipedia.org/wiki/MIT%E8%A8%B1%E5%8F%AF%E8%AD%89)协议，请自由地享受和参与开源。

---

## File: docs/markdown/custom-style.md

# 样式覆盖

### 介绍

Vant Weapp 基于微信小程序的机制，为开发者提供了以下 3 种修改组件样式的方法

### 解除样式隔离

样式隔离的相关背景知识请查阅[微信小程序文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)



Vant Weapp 的所有组件都开启了`addGlobalClass: true`以接受外部样式的影响，可以使用如下 2 种方式覆盖组件样式

> 在页面中使用 Vant Weapp 组件时，可直接在页面的样式文件中覆盖样式

```html
<van-button type="primary">主要按钮</van-button>
```

```css
/* page.wxss */
.van-button--primary {
  font-size: 20px;
  background-color: pink;
}
```

> 在自定义组件中使用 Vant Weapp 组件时，需开启`styleIsolation: 'shared'`选项

```html
<van-button type="primary">主要按钮</van-button>
```

```js
Component({
  options: {
    styleIsolation: 'shared',
  },
});
```

```css
.van-button--primary {
  font-size: 20px;
  background-color: pink;
}
```

### 使用外部样式类

外部样式类的相关知识背景请查阅[微信小程序文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E5%A4%96%E9%83%A8%E6%A0%B7%E5%BC%8F%E7%B1%BB)



Vant Weapp 开放了大量的外部样式类供开发者使用，具体的样式类名称可查阅对应组件的“外部样式类”部分。

需要注意的是普通样式类和外部样式类的优先级是未定义的，因此使用时请添加`!important`以保证外部样式类的优先级。

```html
<van-cell
  title="单元格"
  value="内容"
  title-class="cell-title"
  value-class="cell-value"
/>
```

```css
.cell-title {
  color: pink !important;
  font-size: 20px !important;
}

.cell-value {
  color: green !important;
  font-size: 12px !important;
}
```

### 使用 CSS 变量

Vant Weapp 为部分 CSS 属性开放了基于 CSS 属性的定制方案。

相较于 解除样式隔离 和 使用外部样式类，这种方案支持在页面或应用级别对多个组件的样式做批量修改以进行主题样式的定制。

当然，用它来修改单个组件的部分样式也是绰绰有余的。具体的使用方法请查阅[定制主题](#/theme)

---

## File: docs/markdown/home.md

<h2 style="margin: 0; font-size: 32px; line-height: 60px;">Vant Weapp</h2>
    轻量、可靠的小程序 UI 组件库
  


### 介绍

Vant 是一个**轻量、可靠的移动端组件库**，于 2017 年开源。

目前 Vant 官方提供了 [Vue 2 版本](/vant/v2/)、[Vue 3 版本](/vant/)和[微信小程序版本](/vant-weapp/)，并由社区团队维护 [React 版本](https://github.com/3lang3/react-vant)和[支付宝小程序版本](https://github.com/ant-move/Vant-Aliapp)。

### 预览

扫描下方小程序二维码，体验组件库示例：



> Tips: 为了便于预览组件效果，本文档的右侧内嵌了 H5 版的 Vant 页面作为参考。在实际使用中，个别组件的表现可能与小程序上的表现有差异，请以实际效果为准。

### 快速上手

请参考 [快速上手](#/quickstart)。

### 链接

- [意见反馈](https://github.com/youzan/vant-weapp/issues)
- [设计资源](/vant/#/zh-CN/design)
- [更新日志](/vant-weapp/#/changelog)
- [官方示例](https://github.com/vant-ui/vant-demo)

## 贡献

### 核心团队

以下是 Vant 和 Vant Weapp 的核心贡献者们：

| [](https://github.com/chenjiahan/) | [](https://github.com/cookfront/) | [](https://github.com/w91/) | [](https://github.com/pangxie1991/) | [](https://github.com/rex-zsd/) | [](https://github.com/nemo-shen/) |
| :-: | :-: | :-: | :-: | :-: | :-: |
| [chenjiahan](https://github.com/chenjiahan/) | [cookfront](https://github.com/cookfront/) | [wangnaiyi](https://github.com/w91/) | [pangxie](https://github.com/pangxie1991/) | [rex-zsd](https://github.com/rex-zsd/) | [nemo-shen](https://github.com/nemo-shen/) |

| [](https://github.com/Lindysen/) | [](https://github.com/JakeLaoyu/) | [](https://github.com/landluck/) | [](https://github.com/wjw-gavin/) | [](https://github.com/inottn/) | [](https://github.com/zhousg/) |
| :-: | :-: | :-: | :-: | :-: | :-: |
| [Lindysen](https://github.com/Lindysen/) | [JakeLaoyu](https://github.com/JakeLaoyu/) | [landluck](https://github.com/landluck/) | [wjw-gavin](https://github.com/wjw-gavin/) | [inottn](https://github.com/inottn/) | [zhousg](https://github.com/zhousg/) |

### 贡献者们

感谢以下小伙伴们为 Vant Weapp 发展做出的贡献：

<a href="https://github.com/youzan/vant-weapp/graphs/contributors">
  
</a>

### 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://github.com/youzan/vant-weapp/issues) 给我们，当然，我们也非常欢迎你给我们发 [PR](https://github.com/youzan/vant-weapp/pulls)。

### 开源协议

本项目基于 [MIT](https://zh.wikipedia.org/wiki/MIT%E8%A8%B1%E5%8F%AF%E8%AD%89) 协议，请自由地享受和参与开源。

---

## File: docs/markdown/quickstart.md

# 快速上手

### 背景知识

使用 Vant Weapp 前，请确保你已经学习过微信官方的 [小程序简易教程](https://developers.weixin.qq.com/miniprogram/dev/framework/) 和 [自定义组件介绍](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/)。

## 安装

### 步骤一 通过 npm 安装

> 使用 npm 构建前，请先阅读微信官方的 [npm 支持](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html)

```bash
# 通过 npm 安装
npm i @vant/weapp -S --production

# 通过 yarn 安装
yarn add @vant/weapp --production

# 安装 0.x 版本
npm i vant-weapp -S --production
```

### 步骤二 修改 app.json

将 app.json 中的 `"style": "v2"` 去除，小程序的[新版基础组件](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html#style)强行加上了许多样式，难以覆盖，不关闭将造成部分组件样式混乱。

### 步骤三 构建 npm 包

打开微信开发者工具，点击 **工具 -> 构建 npm**，并勾选 **使用 npm 模块** 选项，构建完成后，即可引入组件。



### 步骤四 typescript 支持

如果你使用 typescript 开发小程序，还需要做如下操作，以获得顺畅的开发体验。

#### 安装 miniprogram-api-typings

```bash
# 通过 npm 安装
npm i -D miniprogram-api-typings

# 通过 yarn 安装
yarn add -D miniprogram-api-typings
```

#### 在 tsconfig.json 中增加如下配置，以防止 tsc 编译报错。

请将`path/to/node_modules/@vant/weapp`修改为项目的 `node_modules` 中 @vant/weapp 所在的目录。

```json
{
  ...
  "compilerOptions": {
    ...
    "baseUrl": ".",
    "types": ["miniprogram-api-typings"],
    "paths": {
      "@vant/weapp/*": ["path/to/node_modules/@vant/weapp/dist/*"]
    },
    "lib": ["ES6"]
  }
}
```

### 示例工程

我们提供了一个[示例工程](https://github.com/vant-ui/vant-demo)，示例工程会帮助你了解如下内容：

- 基于 Vant Weapp 搭建小程序应用
- 样式覆盖方案

## 使用

### 引入组件

以 Button 组件为例，只需要在`app.json`或`index.json`中配置 Button 对应的路径即可。

所有组件文档中的引入路径均以 npm 安装为例，如果你是通过下载源代码的方式使用 @vant/weapp，请将路径修改为项目中 @vant/weapp 所在的目录。

```json
// 通过 npm 安装
// app.json
"usingComponents": {
  "van-button": "@vant/weapp/button/index"
}
```

```json
// 通过下载源码使用 es6版本
// app.json
"usingComponents": {
  "van-button": "path/to/@vant/weapp/dist/button/index"
}
```

```json
// 通过下载源码使用 es5版本
// app.json
"usingComponents": {
  "van-button": "path/to/@vant/weapp/lib/button/index"
}
```

### 使用组件

引入组件后，可以在 wxml 中直接使用组件

```xml
<van-button type="primary">按钮</van-button>
```

## 其他

### 在开发者工具中预览示例小程序

```bash

# 将项目克隆到本地
git clone git@github.com:youzan/vant-weapp.git

# 安装项目依赖
cd vant-weapp && npm install

# 执行组件编译
npm run dev

```

接着打开微信开发者工具，导入`example`目录的项目就可以预览示例了。

### 关于用户隐私保护指引

@vant/weapp 部分组件使用了微信提供的接口，其中部分接口涉及获取用户隐私信息。

例如 `` 使用了微信提供的选择用户相册中图片接口`(wx.chooseImage)`。

当小程序引入 @vant/weapp 并发布时，
根据微信[《用户隐私保护指引填写说明》](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/)，
如检测到代码中存在涉及用户隐私信息接口则需填写用户隐私保护指引信息，如已填写则无需重复填写。

---

## File: docs/markdown/theme.md

# 定制主题

### 背景知识

小程序基于 [Shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom?hl=zh-cn) 来实现自定义组件，所以 Vant Weapp 使用与之配套的 [CSS 变量](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 来实现定制主题。链接中的内容可以帮助你对这两个概念有基本的认识，避免许多不必要的困扰。

CSS 变量 的兼容性要求可以在 [这里](https://caniuse.com/#feat=css-variables) 查看。对于不支持 CSS 变量 的设备，定制主题将不会生效，不过不必担心，默认样式仍会生效。

### 样式变量

定制使用的 CSS 变量 与 Less 变量 同名，下面是一些基本的样式变量，所有可用的颜色变量请参考 [配置文件](https://github.com/youzan/vant-weapp/blob/dev/packages/common/style/var.less)。

```less
// Component Colors
@text-color: #323233;
@border-color: #ebedf0;
@active-color: #f2f3f5;
@background-color: #f8f8f8;
@background-color-light: #fafafa;
```

## 定制方法

### 定制单个组件的主题样式

> 在 wxss 中为组件设置 CSS 变量

```html
<van-button class="my-button">
  默认按钮
</van-button>
```

```less
.my-button {
  --button-border-radius: 10px;
  --button-default-color: #f2f3f5;
}
```

> 或通过 style 属性来设置 CSS 变量，这使你能够轻松实现主题的动态切换

```html
<van-button style="{{ buttonStyle }}">
  默认按钮
</van-button>
```

```js
Page({
  data: {
    buttonStyle: `
      --button-border-radius: 10px;
      --button-default-color: green;
    `,
  },

  onLoad() {
    setTimeout(() => {
      this.setData({
        buttonStyle: `
          --button-border-radius: 2px;
          --button-default-color: pink;
        `,
      });
    }, 2000);
  },
});
```

### 定制多个组件的主题样式

> 与单个组件的定制方式类似，只需用一个 container 节点包裹住需要定制的组件，并将 CSS 变量 设置在 container 节点上

```html
<view class="container">
  <van-button bind:click="onClick">
    默认按钮
  </van-button>

  <van-toast id="van-toast" />
</view>
```

```js
import Toast from '@vant/weapp/toast/toast';

Page({
  onClick() {
    Toast('我是提示文案，建议不超过十五字~');
  },
});
```

```less
.container {
  --button-border-radius: 10px;
  --button-default-color: #f2f3f5;
  --toast-max-width: 100px;
  --toast-background-color: pink;
}
```

### 定制全局主题样式

> 在 app.wxss 中，写入 CSS 变量，即可对全局生效

```less
page {
  --button-border-radius: 10px;
  --button-default-color: #f2f3f5;
  --toast-max-width: 100px;
  --toast-background-color: pink;
}
```

---

## File: packages/uploader/README.md

# Uploader 文件上传

### 介绍

用于将本地的图片或文件上传至服务器，并在上传过程中展示预览图和上传进度。目前 Uploader 组件不包含将文件上传至服务器的接口逻辑，该步骤需要自行实现。

### 引入

在`app.json`或`index.json`中引入组件，默认为`ES6`版本，`ES5`引入方式参见[快速上手](#/quickstart)。

```json
"usingComponents": {
  "van-uploader": "@vant/weapp/uploader/index"
}
```

> Vant Weapp 1.0 版本开始支持此组件，升级方式参见[快速上手](#/quickstart)

## 代码演示

### 基础用法

文件上传完毕后会触发`after-read`回调函数，获取到对应的文件的临时地址，然后再使用`wx.uploadFile`将图片上传到远程服务器上。

```html
<van-uploader file-list="{{ fileList }}" bind:after-read="afterRead" />
```

```js
Page({
  data: {
    fileList: [],
  },

  afterRead(event) {
    const { file } = event.detail;
    // 当设置 mutiple 为 true 时, file 为数组格式，否则为对象格式
    wx.uploadFile({
      url: 'https://example.weixin.qq.com/upload', // 仅为示例，非真实的接口地址
      filePath: file.url,
      name: 'file',
      formData: { user: 'test' },
      success(res) {
        // 上传完成需要更新 fileList
        const { fileList = [] } = this.data;
        fileList.push({ ...file, url: res.data });
        this.setData({ fileList });
      },
    });
  },
});
```

### 图片预览

通过向组件传入`file-list`属性，可以绑定已经上传的图片列表，并展示图片列表的预览图。file-list 的详细结构可见下方。

```html
<van-uploader file-list="{{ fileList }}" />
```

```js
Page({
  data: {
    fileList: [
      {
        url: 'https://img.yzcdn.cn/vant/leaf.jpg',
        name: '图片1',
      },
      // Uploader 根据文件后缀来判断是否为图片文件
      // 如果图片 URL 中不包含类型信息，可以添加 isImage 标记来声明
      {
        url: 'http://iph.href.lu/60x60?text=default',
        name: '图片2',
        isImage: true,
        deletable: true,
      },
    ],
  },
});
```

### 图片可删除状态

通过`deletable`属性可控制是否开启所有图片的可删除状态，`deletable`默认为`true`，即所有图片都可删除。

若希望控制单张图片的可删除状态，可将`deletable`属性设置为`true`，并在`fileList`中为每一项设置`deletable`属性。

```html
<van-uploader file-list="{{ fileList }}" deletable="{{ true }}" />
```

```js
Page({
  data: {
    fileList: [
      {
        url: 'https://img.yzcdn.cn/vant/leaf.jpg',
      },
      {
        url: 'https://img.yzcdn.cn/vant/tree.jpg',
        deletable: false,
      },
    ],
  },
});
```

### 上传状态

通过`status`属性可以标识上传状态，`uploading`表示上传中，`failed`表示上传失败，`done`表示上传完成。

```html
<van-uploader file-list="{{ fileList }}" />
```

```js
Page({
  data: {
    fileList: [
      {
        url: 'https://img.yzcdn.cn/vant/leaf.jpg',
        status: 'uploading',
        message: '上传中',
      },
      {
        url: 'https://img.yzcdn.cn/vant/tree.jpg',
        status: 'failed',
        message: '上传失败',
      },
    ],
  },
});
```

### 限制上传数量

通过`max-count`属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏上传区域。

```html
<van-uploader
  file-list="{{ fileList }}"
  max-count="2"
  bind:after-read="afterRead"
/>
```

### 自定义上传样式

通过插槽可以自定义上传区域的样式。

```html
<van-uploader>
  <van-button icon="photo" type="primary">上传图片</van-button>
</van-uploader>
```

### 上传前校验

将`use-before-read`属性设置为`true`，然后绑定 `before-read` 事件可以在上传前进行校验，调用 `callback` 方法传入 `true` 表示校验通过，传入 `false` 表示校验失败。

```html
<van-uploader
  file-list="{{ fileList }}"
  accept="media"
  use-before-read
  bind:before-read="beforeRead"
  bind:after-read="afterRead"
/>
```

```js
Page({
  data: {
    fileList: [],
  },

  beforeRead(event) {
    const { file, callback } = event.detail;
    callback(file.type === 'image');
  },
});
```

## 云开发示例

### 上传图片至云存储

在开发中，可以利用[小程序云开发](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/getting-started.html)的云存储能力，将图片上传至云存储内。然后根据返回的`fileiId`来下载图片、删除图片和替换临时链接。

```js
// 上传图片
uploadToCloud() {
  wx.cloud.init();
  const { fileList } = this.data;
  if (!fileList.length) {
    wx.showToast({ title: '请选择图片', icon: 'none' });
  } else {
    const uploadTasks = fileList.map((file, index) => this.uploadFilePromise(`my-photo${index}.png`, file));
    Promise.all(uploadTasks)
      .then(data => {
        wx.showToast({ title: '上传成功', icon: 'none' });
        const newFileList = data.map(item => ({ url: item.fileID }));
        this.setData({ cloudPath: data, fileList: newFileList });
      })
      .catch(e => {
        wx.showToast({ title: '上传失败', icon: 'none' });
        console.log(e);
      });
  }
}

uploadFilePromise(fileName, chooseResult) {
  return wx.cloud.uploadFile({
    cloudPath: fileName,
    filePath: chooseResult.url
  });
}
```

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| name | 标识符，可以在回调函数的第二项参数中获取 | _string \| number_ | - |
| accept | 接受的文件类型, 可选值为`all` `media` `image` `file` `video` | _string_ | `image` |
| sizeType | 所选的图片的尺寸, 当`accept`为`image` \| `media` 类型时设置所选图片的尺寸可选值为`original` `compressed` | _string[]_ | `['original','compressed']` |
| preview-size | 预览图和上传区域的尺寸，默认单位为`px` | _string \| number_ | `80px` |
| preview-image | 是否在上传完成后展示预览图 | _boolean_ | `true` |
| preview-full-image | 是否在点击预览图后展示全屏图片预览 | _boolean_ | `true` |
| preview-file `v1.11.7` | 是否在点击文件预览图后预览文件 | _boolean_ | `true` |
| multiple | 是否开启图片多选，部分安卓机型不支持 | _boolean_ | `false` |
| disabled | 是否禁用文件上传 | _boolean_ | `false` |
| show-upload | 是否展示文件上传按钮 | _boolean_ | `true` |
| deletable | 是否展示删除按钮 | _boolean_ | `true` |
| capture | 图片或者视频选取模式，当`accept`为`image` \| `media` 类型时设置`capture`可选值为`camera`可以直接调起摄像头 | _string[]_ | `['album', 'camera']` |
| max-size | 文件大小限制，单位为`byte` | _number_ | - |
| max-count | 文件上传数量限制 | _number_ | - |
| upload-text | 上传区域文字提示 | _string_ | - |
| video-fit `1.10.21` | video 封面的预览图模式，可选值参考小程序`video`组件的`object-fit`属性 | _string_ | `contain` |
| image-fit | 预览图裁剪模式，可选值参考小程序`image`组件的`mode`属性 | _string_ | `scaleToFill` |
| use-before-read | 是否开启文件读取前事件 | _boolean_ | - |
| camera | 当 accept 为 `video` \| `media` 时生效，可选值为 `back` `front` | _string_ | - |
| compressed | 当 accept 为 `video` 时生效，是否压缩视频，默认为`true` | _boolean_ | - |
| max-duration | 当 accept 为 `video` \| `media` 时生效，拍摄视频最长拍摄时间，单位秒 | _number_ | `60` |
| media-type `v1.10.8` | 当 accept 为 `media` 时生效，选择的文件的文件类型，可选值为 `image` `video` `mix` | _string[]_ | `['image', 'video', 'mix']` |
| extension `v1.10.11` | 当 accept 为 `file` 时生效，根据文件拓展名过滤可选择文件。每一项都不能是空字符串。默认不过滤 | _string[] \| undefined_ | - |
| showmenu `v1.10.13` | 预览图片时，是否显示长按菜单 | _boolean_ | `true` |
| upload-icon | 上传区域图标，可选值见 [Icon 组件](#/icon) | _string_ | `plus` |
| referrer-policy `v1.11.6` | 当 accept 为 video 时生效，具体用法参考 [微信官方 - 媒体组件 / video](https://developers.weixin.qq.com/miniprogram/dev/component/video.html) | string | `no-referrer` |

#### accept 的合法值

| 参数    | 说明                                 |
| ------- | ------------------------------------ |
| `media` | 图片和视频                           |
| `image` | 图片                                 |
| `video` | 视频                                 |
| `file`  | 从客户端会话选择图片和视频以外的文件 |
| `all`   | 从客户端会话选择所有文件             |

### FileList

`file-list` 为一个对象数组，数组中的每一个对象包含以下 `key`。

| 参数 | 说明 |
| --- | --- |
| `url` | 图片和视频的网络资源地址 |
| `name` | 文件名称，视频将在全屏预览时作为标题显示 |
| `thumb` | 图片缩略图或视频封面的网络资源地址，仅对图片和视频有效，`accept` 为 `video`时，真机不会返回该属性，建议使用 `media` 和 `media-type` 配合完成视频上传 |
| `type` | 文件类型，可选值`image` `video` `file` |
| `isImage` | 手动标记图片资源 |
| `isVideo` | 手动标记视频资源 |

### Slot

| 名称 | 说明           |
| ---- | -------------- |
| -    | 自定义上传区域 |

### Events

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| bind:before-read | 文件读取前，在回调函数中返回 `false` 可终止文件读取，绑定事件的同时需要将`use-before-read`属性设置为`true` | `event.detail.file`: 当前读取的文件，`event.detail.callback`: 回调函数，调用`callback(false)`终止文件读取 |
| bind:after-read | 文件读取完成后 | `event.detail.file`: 当前读取的文件 |
| bind:oversize | 文件超出大小限制 | - |
| bind:click-preview | 点击预览图片 | `event.detail.index`: 点击图片的序号值 |
| bind:delete | 删除图片 | `event.detail.index`: 删除图片的序号值 |

---

## File: packages/tree-select/README.md

# TreeSelect 分类选择

### 介绍

用于从一组相关联的数据集合中进行选择。

### 引入

在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](#/quickstart#yin-ru-zu-jian)。

```json
"usingComponents": {
  "van-tree-select": "@vant/weapp/tree-select/index"
}
```

## 代码演示

### 单选模式

可以在任意位置上使用 van-tree-select 标签。传入对应的数据即可。此组件支持单选或多选，具体行为完全基于事件 click-item 的实现逻辑如何为属性 active-id 赋值，当 active-id 为数组时即为多选状态。

```html
<van-tree-select
  items="{{ items }}"
  main-active-index="{{ mainActiveIndex }}"
  active-id="{{ activeId }}"
  bind:click-nav="onClickNav"
  bind:click-item="onClickItem"
/>
```

```javascript
Page({
  data: {
    mainActiveIndex: 0,
    activeId: null,
  },

  onClickNav({ detail = {} }) {
    this.setData({
      mainActiveIndex: detail.index || 0,
    });
  },

  onClickItem({ detail = {} }) {
    const activeId = this.data.activeId === detail.id ? null : detail.id;

    this.setData({ activeId });
  },
});
```

### 多选模式

```html
<van-tree-select
  items="{{ items }}"
  main-active-index="{{ mainActiveIndex }}"
  active-id="{{ activeId }}"
  max="{{ max }}"
  bind:click-nav="onClickNav"
  bind:click-item="onClickItem"
/>
```

```javascript
Page({
  data: {
    mainActiveIndex: 0,
    activeId: [],
    max: 2,
  },

  onClickNav({ detail = {} }) {
    this.setData({
      mainActiveIndex: detail.index || 0,
    });
  },

  onClickItem({ detail = {} }) {
    const { activeId } = this.data;

    const index = activeId.indexOf(detail.id);
    if (index > -1) {
      activeId.splice(index, 1);
    } else {
      activeId.push(detail.id);
    }

    this.setData({ activeId });
  },
});
```

### 自定义内容

```html
<van-tree-select
  items="{{ items }}"
  height="55vw"
  main-active-index="{{ mainActiveIndex }}"
  active-id="{{ activeId }}"
  bind:click-nav="onClickNav"
  bind:click-item="onClickItem"
>
  
</van-tree-select>
```

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| items | 分类显示所需的数据 | _Array_ | `[]` |
| height | 高度，默认单位为`px` | _number \| string_ | `300` |
| main-active-index | 左侧选中项的索引 | _number_ | `0` |
| active-id | 右侧选中项的 id，支持传入数组 | _string \| number \| Array_ | `0` |
| max | 右侧项最大选中个数 | _number_ | _Infinity_ |
| selected-icon `v1.5.0` | 自定义右侧栏选中状态的图标 | _string_ | `success` |

### Events

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| bind:click-nav | 左侧导航点击时，触发的事件 | event.detail.index：被点击的导航的索引 |
| bind:click-item | 右侧选择项被点击时，会触发的事件 | event.detail: 该点击项的数据 |

### Slots

| 名称    | 说明                                             |
| ------- | ------------------------------------------------ |
| content | 自定义右侧区域内容，如果存在 items，则插入在顶部 |

### items 数据结构

`items` 整体为一个数组，数组内包含一系列描述分类的对象。每个分类里，text 表示当前分类的名称。children 表示分类里的可选项，为数组结构，id 被用来唯一标识每个选项。

```javascript
[
  {
    // 导航名称
    text: '所有城市',
    // 导航名称右上角徽标，1.5.0 版本开始支持
    badge: 3,
    // 是否在导航名称右上角显示小红点，1.5.0 版本开始支持
    dot: true,
    // 禁用选项
    disabled: false,
    // 该导航下所有的可选项
    children: [
      {
        // 名称
        text: '温州',
        // id，作为匹配选中状态的标识
        id: 1,
        // 禁用选项
        disabled: true,
      },
      {
        text: '杭州',
        id: 2,
      },
    ],
  },
];
```

### 外部样式类

| 类名                   | 说明               |
| ---------------------- | ------------------ |
| main-item-class        | 左侧选项样式类     |
| content-item-class     | 右侧选项样式类     |
| main-active-class      | 左侧选项选中样式类 |
| content-active-class   | 右侧选项选中样式类 |
| main-disabled-class    | 左侧选项禁用样式类 |
| content-disabled-class | 右侧选项禁用样式类 |

---

## File: packages/transition/README.md

# Transition 动画

### 介绍

使元素从一种样式逐渐变化为另一种样式的效果。

### 引入

在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](#/quickstart#yin-ru-zu-jian)。

```json
"usingComponents": {
  "van-transition": "@vant/weapp/transition/index"
}
```

## 代码演示

### 基础用法

将元素包裹在 transition 组件内，在元素展示/隐藏时，会有相应的过渡动画。

```html
<van-transition show="{{ show }}" custom-class="block">内容</van-transition>
```

### 动画类型

transition 组件内置了多种动画，可以通过`name`字段指定动画类型。

```html
<van-transition name="fade-up" />
```

### 高级用法

可以通过外部样式类自定义过渡效果，还可以定制进入和移出的持续时间。

```html
<van-transition
  show="{{ show }}"
  name=""
  duration="{{ { enter: 300, leave: 1000 } }}"
  enter-class="van-enter-class"
  enter-active-class="van-enter-active-class"
  leave-active-class="van-leave-active-class"
  leave-to-class="van-leave-to-class"
/>
```

```css
.van-enter-active-class,
.van-leave-active-class {
  transition-property: background-color, transform;
}

.van-enter-class,
.van-leave-to-class {
  background-color: red;
  transform: rotate(-360deg) translate3d(-100%, -100%, 0);
}
```

## API

### Props

| 参数         | 说明                 | 类型               | 默认值 |
| ------------ | -------------------- | ------------------ | ------ |
| name         | 动画类型             | _string_           | `fade` |
| show         | 是否展示组件         | _boolean_          | `true` |
| duration     | 动画时长，单位为毫秒 | _number \| object_ | `300`  |
| custom-style | 自定义样式           | _string_           | -      |

### Events

| 事件名            | 说明       | 参数 |
| ----------------- | ---------- | ---- |
| bind:before-enter | 进入前触发 | -    |
| bind:enter        | 进入中触发 | -    |
| bind:after-enter  | 进入后触发 | -    |
| bind:before-leave | 离开前触发 | -    |
| bind:leave        | 离开中触发 | -    |
| bind:after-leave  | 离开后触发 | -    |

### 外部样式类

| 类名 | 说明 |
| --- | --- |
| custom-class | 根节点样式类 |
| enter-class | 定义进入过渡的开始状态。在元素被插入之前生效，在元素被插入之后的下一帧移除。 |
| enter-active-class | 定义进入过渡生效时的状态。在整个进入过渡的阶段中应用，在元素被插入之前生效，在过渡/动画完成之后移除。这个类可以被用来定义进入过渡的过程时间，延迟和曲线函数。 |
| enter-to-class | 定义进入过渡的结束状态。在元素被插入之后下一帧生效 (与此同时 enter-class 被移除)，在过渡/动画完成之后移除。 |
| leave-class | 定义离开过渡的开始状态。在离开过渡被触发时立刻生效，下一帧被移除。 |
| leave-active-class | 定义离开过渡生效时的状态。在整个离开过渡的阶段中应用，在离开过渡被触发时立刻生效，在过渡/动画完成之后移除。这个类可以被用来定义离开过渡的过程时间，延迟和曲线函数。 |
| leave-to-class | 定义离开过渡的结束状态。在离开过渡被触发之后下一帧生效 (与此同时 leave-class 被删除)，在过渡/动画完成之后移除。 |

### 动画类型

| 名称        | 说明     |
| ----------- | -------- |
| fade        | 淡入     |
| fade-up     | 上滑淡入 |
| fade-down   | 下滑淡入 |
| fade-left   | 左滑淡入 |
| fade-right  | 右滑淡入 |
| slide-up    | 上滑进入 |
| slide-down  | 下滑进入 |
| slide-left  | 左滑进入 |
| slide-right | 右滑进入 |

---

## File: packages/toast/README.md

# Toast 轻提示

### 介绍

在页面中间弹出黑色半透明提示，用于消息通知、加载提示、操作结果提示等场景。

### 引入

在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](#/quickstart#yin-ru-zu-jian)。

```json
"usingComponents": {
  "van-toast": "@vant/weapp/toast/index"
}
```

## 代码演示

### 文字提示

```javascript
import Toast from '@vant/weapp/toast/toast';

Toast('我是提示文案，建议不超过十五字~');
```

```html
<van-toast id="van-toast" />
```

### 加载提示

使用 `Toast.loading` 方法展示加载提示，通过 `forbidClick` 属性可以禁用背景点击，通过 `loadingType` 属性可以自定义加载图标类型。

```javascript
Toast.loading({
  message: '加载中...',
  forbidClick: true,
});

// 自定义加载图标
Toast.loading({
  message: '加载中...',
  forbidClick: true,
  loadingType: 'spinner',
});
```

### 成功/失败提示

```javascript
Toast.success('成功文案');
Toast.fail('失败文案');
```

### 动态更新提示

```javascript
const toast = Toast.loading({
  duration: 0, // 持续展示 toast
  forbidClick: true,
  message: '倒计时 3 秒',
  selector: '#custom-selector',
});

let second = 3;
const timer = setInterval(() => {
  second--;
  if (second) {
    toast.setData({
      message: `倒计时 ${second} 秒`,
    });
  } else {
    clearInterval(timer);
    Toast.clear();
  }
}, 1000);
```

```html
<van-toast id="custom-selector" />
```

### OnClose 回调函数

```javascript
Toast({
  type: 'success',
  message: '提交成功',
  onClose: () => {
    console.log('执行OnClose函数');
  },
});
```

## API

### 方法

| 方法名 | 参数 | 返回值 | 介绍 |
| --- | --- | --- | --- |
| Toast | `options \| message` | toast 实例 | 展示提示 |
| Toast.loading | `options \| message` | toast 实例 | 展示加载提示 |
| Toast.success | `options \| message` | toast 实例 | 展示成功提示 |
| Toast.fail | `options \| message` | toast 实例 | 展示失败提示 |
| Toast.clear | `clearAll` | `void` | 关闭提示 |
| Toast.setDefaultOptions | `options` | `void` | 修改默认配置，对所有 Toast 生效 |
| Toast.resetDefaultOptions | - | `void` | 重置默认配置，对所有 Toast 生效 |

### Options

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| type | 提示类型，可选值为 `loading` `success` `fail` `html` | _string_ | `text` |
| position | 位置，可选值为 `top` `middle` `bottom` | _string_ | `middle` |
| message | 内容 | _string_ | `''` |
| mask | 是否显示遮罩层 | _boolean_ | `false` |
| forbidClick | 是否禁止背景点击 | _boolean_ | `false` |
| loadingType | 加载图标类型, 可选值为 `spinner` | _string_ | `circular` |
| zIndex | z-index 层级 | _number_ | `1000` |
| duration | 展示时长(ms)，值为 0 时，toast 不会消失 | _number_ | `2000` |
| selector | 自定义选择器 | _string_ | `van-toast` |
| context | 选择器的选择范围，可以传入自定义组件的 this 作为上下文 | _object_ | 当前页面 |
| onClose | 关闭时的回调函数 | _Function_ | - |

### Slot

| 名称 | 说明       |
| ---- | ---------- |
| -    | 自定义内容 |

---

## File: packages/tag/README.md

# Tag 标签

### 介绍

用于标记关键词和概括主要内容。

### 引入

在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](#/quickstart#yin-ru-zu-jian)。

```json
"usingComponents": {
  "van-tag": "@vant/weapp/tag/index"
}
```

## 代码演示

### 基础用法

通过 `type` 属性控制标签颜色，默认为灰色。

```html
<van-tag type="primary">标签</van-tag>
<van-tag type="success">标签</van-tag>
<van-tag type="danger">标签</van-tag>
<van-tag type="warning">标签</van-tag>
```

### 空心样式

设置 `plain` 属性设置为空心样式。

```html
<van-tag plain type="primary">标签</van-tag>
<van-tag plain type="success">标签</van-tag>
<van-tag plain type="danger">标签</van-tag>
<van-tag plain type="warning">标签</van-tag>
```

### 圆角样式

通过 `round` 设置为圆角样式。

```html
<van-tag round type="primary">标签</van-tag>
<van-tag round type="success">标签</van-tag>
<van-tag round type="danger">标签</van-tag>
<van-tag round type="warning">标签</van-tag>
```

### 标记样式

通过 `mark` 设置为标记样式(半圆角)。

```html
<van-tag mark type="primary">标签</van-tag>
<van-tag mark type="success">标签</van-tag>
<van-tag mark type="danger">标签</van-tag>
<van-tag mark type="warning">标签</van-tag>
```

### 自定义颜色

```html
<van-tag color="#f2826a">标签</van-tag>
<van-tag color="#7232dd">标签</van-tag>
<van-tag color="#7232dd" plain>标签</van-tag>
<van-tag color="#ffe1e1" text-color="#ad0000">标签</van-tag>
```

### 标签大小

```html
<van-tag type="danger">标签</van-tag>
<van-tag type="danger" size="medium">标签</van-tag>
<van-tag type="danger" size="large">标签</van-tag>
```

### 可关闭标签

添加 `closeable` 属性表示标签是可关闭的，关闭标签时会触发 `close` 事件，在 `close` 事件中可以执行隐藏标签的逻辑。

```html
<van-tag
  wx:if="{{ show.primary }}"
  closeable
  size="medium"
  type="primary"
  id="primary"
  bind:close="onClose"
>
  标签
</van-tag>
<van-tag
  wx:if="{{ show.success }}"
  closeable
  size="medium"
  type="success"
  id="success"
  bind:close="onClose"
>
  标签
</van-tag>
```

```js
Page({
  data: {
    show: {
      primary: true,
      success: true,
    },
  },
  onClose(event) {
    this.setData({
      [`show.${event.target.id}`]: false,
    });
  },
});
```

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| type | 类型，可选值为 `primary` `success` `danger` `warning` | _string_ | - |
| size | 大小, 可选值为 `large` `medium` | _string_ | - |
| color | 标签颜色 | _string_ | - |
| plain | 是否为空心样式 | _boolean_ | `false` |
| round | 是否为圆角样式 | _boolean_ | `false` |
| mark | 是否为标记样式 | _boolean_ | `false` |
| text-color | 文本颜色，优先级高于 `color` 属性 | _string_ | `white` |
| closeable | 是否为可关闭标签 | _boolean_ | `false` |

### Slot

| 名称 | 说明                |
| ---- | ------------------- |
| -    | 自定义 Tag 显示内容 |

### Events

| 事件名 | 说明           | 回调参数 |
| ------ | -------------- | -------- |
| bind:close  | 关闭标签时触发 | -        |

### 外部样式类

| 类名         | 说明         |
| ------------ | ------------ |
| custom-class | 根节点样式类 |