vue mint ui 手册文档(基于Vue.js的移动端开发组件)

最新推荐文章于 2026-03-28 03:03:51 发布

原创最新推荐文章于 2026-03-28 03:03:51 发布 · 819 阅读

本内容遵循CC 4.0 BY-SA版权协议

npm 安装

推荐使用 npm 的方式安装，它能更好地和 webpack 打包工具配合使用。

npm i mint-ui -S

CDN

目前可以通过 unpkg.com/mint-ui 获取到最新版本的资源，在页面上引入 js 和 css 文件即可开始使用。

<!-- 引入样式 -->
<link rel="stylesheet" href="https://unpkg.com/mint-ui/lib/style.css">
<!-- 引入组件库 -->
<script src="https://unpkg.com/mint-ui/lib/index.js"></script>

Hello world

通过 CDN 的方式我们可以很容易地使用 Mint UI 写出一个 Hello world 页面。

<!DOCTYPE html>
<html>
  <head>
     <meta charset="UTF-8">
     <!-- 引入样式 -->
     <link rel="stylesheet" href="https://unpkg.com/mint-ui/lib/style.css">
  </head>
  <body>
     <div id="app">
         <mt-button @click.native="handleClick">按钮</mt-button>
     </div>
  </body>
  <!-- 先引入 Vue -->
  <script src="https://unpkg.com/vue/dist/vue.js"></script>
  <!-- 引入组件库 -->
  <script src="https://unpkg.com/mint-ui/lib/index.js"></script>
  <script>
    new Vue({
      el: '#app',
      methods: {
        handleClick: function() {
          this.$toast('Hello world!')
        }
      }
    })
  </script>
</html>

如果是通过 npm 安装，并希望配合 webpack 使用，请阅读下一节：快速上手。

关于事件绑定

在 Vue 2.0 中，为自定义组件绑定原生事件必须使用 .native 修饰符：

<my-component @click.native="handleClick">Click Me</my-component>

从易用性的角度出发，我们对 Button 组件进行了处理，使它可以监听 click 事件：

<mt-button @click="handleButtonClick">Click Me</mt-button>

但是对于其他组件，还是需要添加 .native 修饰符。

快速上手

本节将介绍如何在项目中使用 Mint UI。

使用 vue-cli

npm install -g vue-cli
vue init webpack projectname

引入 Mint UI

你可以引入整个 Mint UI，或是根据需要仅引入部分组件。我们先介绍如何引入完整的 Mint UI。

完整引入

在 main.js 中写入以下内容：

import Vue from 'vue'import MintUI from 'mint-ui'import 'mint-ui/lib/style.css'import App from './App.vue'
Vue.use(MintUI)
new Vue({
  el: '#app',
  components: { App }
})

以上代码便完成了 Mint UI 的引入。需要注意的是，样式文件需要单独引入。

按需引入

借助 babel-plugin-component，我们可以只引入需要的组件，以达到减小项目体积的目的。

首先，安装 babel-plugin-component：

npm install babel-plugin-component -D

然后，将 .babelrc 修改为：

{
  "presets": [
    ["es2015", { "modules": false }]
  ],
  "plugins": [["component", [
    {
      "libraryName": "mint-ui",
      "style": true
    }
  ]]]
}

如果你只希望引入部分组件，比如 Button 和 Cell，那么需要在 main.js 中写入以下内容：

import Vue from 'vue'import { Button, Cell } from 'mint-ui'import App from './App.vue'
Vue.component(Button.name, Button)
Vue.component(Cell.name, Cell)
/* 或写为
 * Vue.use(Button)
 * Vue.use(Cell)
 */
new Vue({
  el: '#app',
  components: { App }
})

开始使用

至此，一个基于 Vue 和 Mint UI 的开发环境已经搭建完毕，现在就可以编写代码了。启动开发模式：

npm run dev

编译：

npm run build

各个组件的使用方法请参阅它们各自的文档。

Toast

简短的消息提示框，支持自定义位置、持续时间和样式

引入

import { Toast } from 'mint-ui';

例子

基本用法

Toast('提示信息');

在调用 Toast 时传入一个对象即可配置更多选项

Toast({
message: '提示',
position: 'bottom',
duration: 5000
});

若需在文字上方显示一个 icon 图标，可以将图标的类名作为 iconClass 的值传给 Toast（图标需自行准备）

Toast({
message: '操作成功',
iconClass: 'icon icon-success'
});

执行 Toast 方法会返回一个 Toast 实例，每个实例都有 close 方法，用于手动关闭 Toast

let instance = Toast('提示信息');
setTimeout(() => {
instance.close();
}, 2000);

API

参数	说明	类型	可选值	默认值
message	文本内容	String
position	Toast 的位置	String	'top' 'bottom' 'middle'	'middle'
duration	持续时间（毫秒），若为 -1 则不会自动关闭	Number		3000
className	Toast 的类名。可以为其添加样式	String
iconClass	icon 图标的类名	String

下拉/上拉刷新，支持自定义 HTML 模板。

引入

import { Loadmore } from 'mint-ui';
Vue.component(Loadmore.name, Loadmore);

例子

<mt-loadmore :top-method="loadTop" :bottom-method="loadBottom" :bottom-all-
  loaded="allLoaded" ref="loadmore">
  <ul>
    <li v-for="item in list">{{ item }}</li>
  </ul>
</mt-loadmore>

以列表顶部的下拉刷新为例：按住列表，下拉一定距离（通过 topDistance 配置）后释放，被指定为 top-method 的方法就会执行

loadTop() {
  ...// 加载更多数据
  this.$refs.loadmore.onTopLoaded();
}

注意在这个方法的最后需要手动调用 loadmore 的 onTopLoaded 事件。这是因为在加载数据后需要对组件进行一些重新定位的操作。

列表底部的上拉刷新与之类似

loadBottom() {
  ...// 加载更多数据
  this.allLoaded = true;// 若数据已全部获取完毕
  this.$refs.loadmore.onBottomLoaded();
}

唯一的区别是，当底部数据全部获取完毕时，可以将绑定到组件 bottom-all-loaded 属性的变量赋值为 true，这样 bottom-method 就不会再次执行了。

手指在屏幕上滑动的距离与组件实际移动的距离比值可以通过 distance-index 参数配置，默认值为 2。

自定义 HTML 模板

可以为列表顶部和底部的加载提示区域提供自定义的 HTML 模板

<template>
  <mt-loadmore :top-method="loadTop" @top-status-change="handleTopChange">
    <ul>
      <li v-for="item in list">{{ item }}</li>
    </ul>
    <div slot="top" class="mint-loadmore-top">
      <span v-show="topStatus !== 'loading'" :class="{ 'rotate': topStatus === 'drop' }">↓</span>
      <span v-show="topStatus === 'loading'">Loading...</span>
    </div>
  </mt-loadmore></template><script>
  export default {
    data() {
      return {
        topStatus: '',
        // ...
      };
    },
    methods: {
      handleTopChange(status) {
        this.topStatus = status;
      },
      // ...
    },
    // ...
  };
</script>

比如需要配置列表顶部的 HTML，则需要为自定义 HTML 模板的最外层标签设置 slot 属性为 top，类名为 mint-loadmore-top。当用户滑动组件时，组件会有以下几个状态：

pull：组件已经被按下，但按下的距离未达到 topDistance，此时释放不会触发 top-method，列表会回到初始位置
drop：按下的距离不小于 topDistance，此时释放会触发 top-method
loading：组件已被释放，top-method 正在执行每当组件的状态发生变化时，loadmore 都会触发 top-status-change 方法，参数为组件目前的状态。因此可以像本例一样，使用一个 handleTopChange 方法来处理组件状态的变化。

配置加载提示区域的文字

在不使用自定义 HTML 模板的情况下，可以配置 loadmore 本身自带的加载提示区域的文字。以列表顶部为例，对应于 status 的三个状态，可配置的属性依次为 topPullText、topDropText 和 topLoadingText。与之对应的底部属性为 bottomPullText、bottomDropText 和 bottomLoadingText。

自动检测

loadmore 在初始化时会自动检测它的高度是否能够撑满其容器，如果不能则会调用 bottom-method，直到撑满容器为止。如果不希望使用这一机制，可以将 auto-fill 设为 false。

API

参数	说明	类型	默认值
autoFill	若为真，`loadmore` 会自动检测并撑满其容器	Boolean	true
distanceIndex	手指移动与组件移动距离的比值	Number	2
maxDistance	组件可移动的最大距离（像素），若为 0 则不限制	Number	0
topPullText	`topStatus` 为 `pull` 时加载提示区域的文字	String	'下拉刷新'
topDropText	`topStatus` 为 `drop` 时加载提示区域的文字	String	'释放更新'
topLoadingText	`topStatus` 为 `loading` 时加载提示区域的文字	String	'加载中...'
topDistance	触发 `topMethod` 的下拉距离阈值（像素）	Number	70
topMethod	下拉刷新执行的方法	Function
bottomPullText	`bottomStatus` 为 `pull` 时加载提示区域的文字	String	'上拉刷新'
bottomDropText	`bottomStatus` 为 `drop` 时加载提示区域的文字	String	'释放更新'
bottomLoadingText	`bottomStatus` 为 `loading` 时加载提示区域的文字	String	'加载中...'
bottomDistance	触发 `bottomMethod` 的上拉距离阈值（像素）	Number	70
bottomMethod	上拉刷新执行的方法	Function
bottomAllLoaded	若为真，则 `bottomMethod` 不会被再次触发	Boolean	false

Events

事件名称	说明	回调参数
top-status-change	组件顶部状态发生变化时的回调函数	组件顶部的新状态名
bottom-status-change	组件底部状态发生变化时的回调函数	组件底部的新状态名

Slot

name	描述
-	数据列表
top	自定义顶部加载提示区域 HTML 模板
bottom	自定义底部加载提示区域 HTML 模板

Infinite scroll

无限滚动指令。

引入

import { InfiniteScroll } from 'mint-ui';
Vue.use(InfiniteScroll);

例子

为 HTML 元素添加 v-infinite-scroll 指令即可使用无限滚动。滚动该元素，当其底部与被滚动元素底部的距离小于给定的阈值（通过 infinite-scroll-distance 设置）时，绑定到 v-infinite-scroll 指令的方法就会被触发。

<ul v-infinite-scroll="loadMore"
    infinite-scroll-disabled="loading"
    infinite-scroll-distance="10">
  <li v-for="item in list">{{ item }}</li>
</ul>

loadMore() {
  this.loading = true;
  setTimeout(() => {
    let last = this.list[this.list.length - 1];
    for (let i = 1; i <= 10; i++) {
      this.list.push(last + i);
    }
    this.loading = false;
  }, 2500);
}

API

参数	说明	类型	可选值	默认值
infinite-scroll-disabled	若为真，则无限滚动不会被触发	Boolean		false
infinite-scroll-distance	触发加载方法的滚动距离阈值（像素）	Number		0
infinite-scroll-immediate-check	若为真，则指令被绑定到元素上后会立即检查是否需要执行加载方法。在初始状态下内容有可能撑不满容器时十分有用。	Boolean		true
infinite-scroll-listen-for-event	一个 event，被执行时会立即检查是否需要执行加载方法。	Function

Message box

弹出式提示框，有多种交互形式。

引入

import { MessageBox } from 'mint-ui';

例子

以标题与内容字符串为参数进行调用

MessageBox('提示', '操作成功');

或者传入一个对象

MessageBox({
  title: '提示',
  message: '确定执行此操作?',
  showCancelButton: true
});

此外，MessageBox 还提供了 alert、confirm 和 prompt 三个方法，它们都返回一个 Promise

MessageBox.alert(message, title);

MessageBox.alert('操作成功').then(action => {
  ...
});

MessageBox.confirm(message, title);

MessageBox.confirm('确定执行此操作?').then(action => {
  ...
});

MessageBox.prompt(message, title);

MessageBox.prompt('请输入姓名').then(({ value, action }) => {
  ...
});

在 prompt 中，若用户点击了取消按钮，则 Promise 的状态会变为 rejected

API

参数	说明	类型	可选值	默认值
title	提示框的标题	String
message	提示框的内容	String
showConfirmButton	是否显示确认按钮	Boolean		true
showCancelButton	是否显示取消按钮	Boolean		false
confirmButtonText	确认按钮的文本	String
confirmButtonHighlight	是否将确认按钮的文本加粗显示	Boolean		false
confirmButtonClass	确认按钮的类名	String
cancelButtonText	取消按钮的文本	String
cancelButtonHighlight	是否将取消按钮的文本加粗显示	Boolean		false
cancelButtonClass	取消按钮的类名	String
closeOnClickModal	是否在点击遮罩时关闭提示光	Boolean	true (alert 为 false)
showInput	是否显示一个输入框	Boolean		false
inputType	输入框的类型	String		'text'
inputValue	输入框的值	String
inputPlaceholder	输入框的占位符	String

Action sheet

操作表，从屏幕下方移入。

引入

import { Actionsheet } from 'mint-ui';
Vue.component(Actionsheet.name, Actionsheet);

例子

actions 属性绑定一个由对象组成的数组，每个对象有 name 和 method 两个键，name 为菜单项的文本，method 为点击该菜单项的回调函数。

将 v-model 绑定到一个本地变量，通过操作这个变量即可控制 actionsheet 的显示与隐藏。

<mt-actionsheet
  :actions="actions"
  v-model="sheetVisible"></mt-actionsheet>

API

参数	说明	类型	可选值	默认值
actions	菜单项数组	Array
cancelText	取消按钮的文本。若设为空字符串，则不显示取消按钮	String		'取消'
closeOnClickModal	是否可以通过点击 modal 层来关闭 `actionsheet`	Boolean		true

Popup

弹出框，可自定义内容。

引入

import { Popup } from 'mint-ui';
Vue.component(Popup.name, Popup);

例子

position 属性指定了 popup 的位置。比如，position 为 'bottom' 时，popup 会从屏幕下方移入，并最终固定在屏幕下方。移入/移出的动效会根据 position 的不同而自动改变，无需手动配置。

将 v-model 绑定到一个本地变量，通过操作这个变量即可控制 popup 的显示与隐藏。

<mt-popup
  v-model="popupVisible"
  position="bottom">
  ...
</mt-popup>

若省略 position 属性，则 popup 会相对于屏幕居中显示（若不想让其居中，可通过 CSS 对其重新定位）。此时建议将动效设置为 popup-fade，这样在显示/隐藏时会有淡入/淡出效果。

<mt-popup
  v-model="popupVisible"
  popup-transition="popup-fade">
  ...
</mt-popup>

API

参数	说明	类型	可选值	默认值
position	`popup` 的位置。省略则居中显示	String	'top' 'right' 'bottom' 'left'
pop-transition	显示/隐藏时的动效，仅在省略 `position` 时可配置	String	'popup-fade'
modal	是否创建一个 modal 层	Boolean		true
closeOnClickModal	是否可以通过点击 modal 层来关闭 `popup`	Boolean		true

Slot

name	描述
-	弹出框的内容

Swipe

轮播图，可自定义轮播时间间隔、动画时长等。

引入

import { Swipe, SwipeItem } from 'mint-ui';
Vue.component(Swipe.name, Swipe);
Vue.component(SwipeItem.name, SwipeItem);

例子

基础用法

<mt-swipe :auto="4000">
  <mt-swipe-item>1</mt-swipe-item>
  <mt-swipe-item>2</mt-swipe-item>
  <mt-swipe-item>3</mt-swipe-item></mt-swipe>

隐藏 indicators

<mt-swipe :show-indicators="false">
  <mt-swipe-item>1</mt-swipe-item>
  <mt-swipe-item>2</mt-swipe-item>
  <mt-swipe-item>3</mt-swipe-item></mt-swipe>

取消自动播放

<mt-swipe :auto="0">
  <mt-swipe-item>1</mt-swipe-item>
  <mt-swipe-item>2</mt-swipe-item>
  <mt-swipe-item>3</mt-swipe-item></mt-swipe>

change 事件

轮播图切换时会触发 change 事件，参数为切入轮播图的索引

<mt-swipe @change="handleChange">
  <mt-swipe-item>1</mt-swipe-item>
  <mt-swipe-item>2</mt-swipe-item>
  <mt-swipe-item>3</mt-swipe-item></mt-swipe>

methods: {
  handleChange(index) {
    ...
  }
}

API

参数	说明	类型	默认值
speed	动画持时（毫秒）	Number	300
auto	自动播放的时间间隔（毫秒）	Number	3000
defaultIndex	初始显示的轮播图的索引	Number	0
continuous	是否可以循环播放	Boolean	true
showIndicators	是否显示 indicators	Boolean	true
prevent	是否在 touchstart 事件触发时阻止事件的默认行为。设为 true 可提高运行在低版本安卓浏览器时的性能	Boolean	false
stopPropagation	是否在 touchstart 事件触发时阻止冒泡。	Boolean	false

Slot

mt-swipe

name	描述
-	一个或多个 `mt-swipe-item` 组件

mt-swipe-item

name	描述
-	单个轮播图的内容

Lazy load

图片懒加载指令。

引入

import { Lazyload } from 'mint-ui';
Vue.use(Lazyload);

例子

为 img 元素添加 v-lazy 指令，指令的值为图片的地址。同时需要设置图片在加载时的样式。

<ul>
  <li v-for="item in list">
    <img v-lazy="item">
  </li></ul>

image[lazy=loading] { width: 40px; height: 300px; margin: auto; }

若列表不在 window 上滚动，则需要将被滚动元素的 id 属性以修饰符的形式传递给 v-lazy 指

<ul>

</li>

</ul></div>

Range

滑块，支持自定义步长、区间等。

引入

import { Range } from 'mint-ui';
Vue.component(Range.name, Range);

例子

将一个本地变量与 range 的 value 属性同步即可实现双向绑定

<mt-range v-model="rangeValue"></mt-range>

更多的配置项

<mt-range
  v-model="rangeValue"
  :min="10"
  :max="90"
  :step="10"
  :bar-height="5"></mt-range>

可在滑块两侧显示文字

<mt-range v-model="rangeValue">
  <div slot="start">0</div>
  <div slot="end">100</div></mt-range>

API

参数	说明	类型	默认值
value	滑块的值	Number
min	最小值	Number	0
max	最大值	Number	100
step	步长	Number	1
disabled	是否禁用	Boolean	false
barHeight	滑槽的线宽（像素）	Number	1