简单汇总

2024年1月10日

Button 按钮

文档链接: https://vant-contrib.gitee.io/vant/#/zh-CN/button

在 Vue3 + TS + 配置自动加载后可直接使用

基本语法

<van-button>文字</van-button>

文档示例特征

  • 可设置类型 type: default(白色), primary(蓝色), success(绿色), warning(黄色), danger(红色)
  • 朴素按钮, 即白色背景按钮, 只要包含 plain 属性即可.
  • 细边框, 只要含有 hairline 属性, 即可展示 0.5px 的细边框.
  • 禁用状态, 使用 disabled 属性即可 (样式上置灰).
  • 加载状态, 使用 loading属性. 可以设置加载图标 (loading-type), 以及文字 loading-text.
  • 按钮形状. 默认为圆角矩形. 可以设置 square 方矩形. 和 round 胶囊形.
  • 图标按钮. 使用 icon 属性添加图标.
  • 按钮尺寸. size 属性, 可取值: large, normal, small, mini.
  • 块级元素. 使用 block 属性.
  • 页面导航. 使用 url 属性, 或 to 属性.
  • 自定义颜色. 使用 color 属性. 支持使用梯度渐变色.
  • 动画按钮. 组合使用 Button 和 Swip 组件. 将轮播嵌入到 按钮 中.

Cell 单元格

文档地址: https://vant-contrib.gitee.io/vant/#/zh-CN/cell

基本语法:

<van-cell 
  title="标题"
  value="右侧内容"
  label="标题下方的描述文字"       
></van-cell>

一般以横向分组列表的形式展示数据项. 逻辑样式与手机中设置的样式类似.

常用属性有:

  • title 主题标题
  • label 标题下方的子标题
  • value 右侧是文字
  • is-link 显示右侧箭头
  • url 或 to 用来设置导航. 配合 replace 来设置是否替换页面历史.
  • required 当用作表单的时候, 显示必填星号.
  • center 在同时使用 title 和 label 后, 行高会变高, 用于控制右侧是否垂直居中.

附加组件 CellGroup

作为容器使用:

<van-cell-group></van-cell-group>

常用属性:

  • title 设置分组标题.

ConfigProvider 全局配置

文档: https://vant-contrib.gitee.io/vant/#/zh-CN/config-provider

基本语法:

<van-config-provider></van-config-provider>

作为全局容器使用, 可以配置一些全局属性. 例如主题等.

具体用法暂未整理.

Icon 图标

文档链接: https://vant-contrib.gitee.io/vant/#/zh-CN/icon

使用 name 属性来指定图标内容.

使用语法:

<van-icon name="图标名"></van-icon>

使用的时候查即可.

常用属性:

  • 徽标 badge
  • 右上角点: dot
  • 自定义颜色 color

Image 图片

文档地址: https://vant-contrib.gitee.io/vant/#/zh-CN/image

基本语法:

<vant-image width="100" height="100" src="..."></vant-image>

常用属性:

  • width 和 height 设置宽高. 默认为 inline-block 元素.
  • src 用来设置图片地址.
  • 填充模式: fit, 常用取值: cover, 还有特定时候才会使用.
  • 圆形图片. 使用 round 属性即可. 在设置图标或头像的时候会使用到.

懒加载的用法:

  1. 引入 Lazyload 组件, 该组件是指令的形式. 因此建议使用全局加载.
  2. 在需要加载图片的组件中, 使用 v-lazy 来代替 src
  3. 需要作为背景样式加载图片的时候使用 v-lazy:background-image, 属性值为图片地址.
  4. 如果要懒加载组件. 全局注册时使用 lazyComponent: true 的选项. 使用 lazy-component 组件作为组件容器.

注意文档中使用的属性不同:

  • img 使用 v-lazy 指定图片. 经过演示, img 标签不支持使用 lazy-load 实现懒加载, 只适用于 v-lazy 方法.
  • image 使用 src 指定图片, 带上 lazy-load 属性. 直接使用 v-lazy 无法加载图片.

演示后发现不起作用.

Layout 布局

文档链接:https://vant-contrib.gitee.io/vant/#/zh-CN/col

两个组件: van-row 和 van-col 来构造栅格布局. 默认 24 分栏.

基本语法:

<van-row>
  <van-col></van-col>
</van-row>

基本用法与其他框架一致. 常用属性有:

  • gutter, 用来设置间距, 使用数组分别表示横向与纵向间距.
  • justify 和 align 对标 flex 的对齐方式.
  • span 和 offset 来布局单元格.

文档地址: https://vant-contrib.gitee.io/vant/#/zh-CN/popup

基本用法:

<van-popup v-model:show=""></van-popup>

基本模型可以看成 antd 中的 Modal 这类组件.

常用属性:

  • position 属性, 控制弹窗位置, 可取值为: top, bottom, left, right. 默认是居中弹出.
  • closeable 控制右上角显示关闭图标.
  • 监听事件: open, opened, close, 和 closed. 可以处理在关闭时对表单等数据做初始化.
  • close-on-click-overlay, 控制点击遮罩层关闭.
  • before-close 关闭前的回调函数, 返回 false 禁止关闭, 支持 Promise.

Space 间距

文档: https://vant-contrib.gitee.io/vant/#/zh-CN/space

基本用法:

<van-space></van-space>

常用属性:

  • 默认水平排列, 且不会自动填充
  • 使用 direction 属性来设置方向: vertical 表示竖直布局.
  • size 用于定义间距.
  • 使用 align 设置对齐.
  • fill 将 组件设置为块级元素, 填充容器.

Style 内置样式

文档地址: https://vant-contrib.gitee.io/vant/#/zh-CN/style

直接使用类样式名来使用:

  • 文字省略: van-ellipsis, van-multi-ellipsis--l2, van-multi-ellipsis--l3.
  • 1px 边框: van-hairline--{{direction}}
    • top, bottom, left, right, top-bottom, surround
  • 安全区 (适配 iPhoneX 的部分机型) van-safe-area-top, van-safe-area-bottom
  • 动画
  • 触碰反馈 van-haptics-feedback
  • 清除浮动 van-clearfix

注意, 文字省略的多行文本后面的字母 l, 不是数字 1.

动画的使用:

<transition name="..."></transition>

可用动画有:

  • van-fade
  • van-slide-up
  • van-slide-down
  • van-slide-left
  • van-slide-right

需要注意, 动画元素并未脱离文档流, 需要设置定位后, 再应用动画.

Toast 轻提示

网址: https://vant-contrib.gitee.io/vant/#/zh-CN/toast

一个函数式的 API. 在页面中显示一个半透明的黑色消息框.

需要导入使用, 语法:

import { showToast } from 'vant'
showToast('消息内容')

该组件提供了很多函数封装, 适用不同样式:

  • 加载提示: showLoadingToast, 可用属性 message 显示消息, forbidClick 禁用背景点击.
  • 成功失败提示: showSuccessToast('成功文案'), showFailToast('失败文案').
  • 自定义图标: showToast(), 使用 icon 属性, 来指定图标.
  • 自定义位置: showToast(), 使用 position 来设置位置, 可选 top, bottom.
  • 文字换行方式: showToast(), 使用 wordBreak 属性, 可取 break-all(截断单词换行), break-word.
  • 动态更新提示. showToast() 返回实例引用, 使用 message 响应式属性即可. 逻辑上将 duration 设置为 0, 不会自动关闭, 在利用计时器最后调用 closeToast() 关闭提示框. 默认轻提示是单例的.
  • 多实例用法.
    1. 调用 allowMultipleToast() 方法.
    2. 每次调用 showToast() 返回一个实例.
    3. 调用实例的 close() 方法关闭.
  • 修改默认配置
    1. 调用 setToastOptions({ ... }) 来进行配置.
    2. 调用 resetToastDefaultOptions() 来重置.
    3. 可以单独设置某个类型的 配置.
  • 组件用法 (逻辑上对标 antd 的 Modal), 需要定制提示内容时使用.
    1. 单独注册组件 (例如全局注册)
    2. 使用 <van-toast></van-toast>
    3. 使用 v-model:show 控制显示
    4. 使用 message 插槽来定义内容
Last Updated:
Contributors: jk