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
指
<div id="container">
<ul>
<li v-for="item in list">
<img v-lazy.container="item">
</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 |
Slot
name | 描述 |
---|---|
start | 滑块左侧 DOM |
end | 滑块右侧 DOM |
Progress
进度条。
引入
-
import { Progress } from 'mint-ui';
-
Vue.component(Progress.name, Progress);
例子
传入 value
作为进度条的值。可自定义它的线宽
<mt-progress :value="20" :bar-height="5"></mt-progress>
可在进度条两侧显示文字
-
<mt-progress :value="60">
-
<div slot="start">0%</div>
-
<div slot="end">100%</div></mt-progress>
API
参数 | 说明 | 类型 | 可选值 | 默认值 |
---|---|---|---|---|
value | 进度条的值(%) | Number | ||
barHeight | 进度条的线宽(像素) | Number | 1 |
Slot
name | 描述 |
---|---|
start | 进度条左侧 DOM |
end | 进度条右侧 DOM |
Picker
选择器,支持多 slot 联动。
引入
-
import { Picker } from 'mint-ui';