| nav |
|---|
zh-CN |
2.1.0 ~ 3.0.0 之间版本不会有影响升级的 `break change`，请放心及时更新版本。
0.x 版本文档不完整，并且已经不再维护。请更新或者直接使用`2.x`。
如果你想查看`0.x`组件代码和 Demo 代码，请查看 [master 分支](https://github.com/airyland/vux/tree/master)
访问 `0.x` 文档地址
Vux（读音 [v'ju:z]，同views）是基于WeUI和Vue(2.x)开发的移动端UI组件库，主要服务于微信页面。
基于webpack+vue-loader+vux可以快速开发移动端页面，配合vux-loader方便你在WeUI的基础上定制需要的样式。
vux-loader保证了组件按需使用，因此不用担心最终打包了整个vux的组件库代码。
vux并不完全依赖于WeUI，但是尽量保持整体UI样式接近WeUI的设计规范。最初目标是创建一个易用，实用，美观的移动端UI组件库，现在离理想状态还有不少距离，因此需要大家及时反馈问题及贡献代码。
即使你不使用vux的代码, 但能从源码得到一些参考那么也是件让人高兴的事情。
[email protected] 推荐`webpack+vue-loader`方式的开发，如果要使用`umd`文件，请参照下面文档。不建议使用引入`script`的方式进行开发，因为它会带来一系列的开发、维护、效率、部署问题。
Life is short, use webpack.
如果你的产品在使用
VUX, 欢迎邮箱发送Logo+链接给我。
如果你从没使用过`VUX`，请直接看下面的快速入门。
直接安装或者更新：
npm install vux --save或者使用 yarn
yarn add vux // 安装
yarn upgrade vux // 更新如果你是从0.x更新，请参考： 更新到2.x
vux2必须配合`vux-loader`使用, 请在`build/webpack.base.conf.js`里参照如下代码进行配置：
const vuxLoader = require('vux-loader')
module.exports = vuxLoader.merge(webpackConfig, {
options: {},
plugins: [
{
name: 'vux-ui'
}
]
})[email protected] 已经停止维护，请尽快迁移到 [email protected] & [email protected] & [email protected]，虽然要花点时间，但是完全值得。
使用
vue-cli工具和airyland/vux2模板快速初始化项目
默认为 webpack2 模板，如果你需要使用
webpack1，请使用 vue init airyland/vux2#webpack1 projectPath
npm install vue-cli -g // 如果还没安装
vue init airyland/vux2 projectPath
cd projectPath
npm install --registry=https://registry.npm.taobao.org
npm run dev
请特别注意，直接使用 cnpm 可能会导致依赖不正确。强烈建议给 npm 设置 taobao 的 registry。
npm install --registry=https://registry.npm.taobao.org
如果你已经用上了 yarn，建议这样
yarn config set registry https://registry.npm.taobao.org
``` yarn ```
.vue文件中调用组件
<template>
<div>
<group>
<cell title="title" value="value"></cell>
</group>
</div>
</template>
<script>
import { Group, Cell } from 'vux'
export default {
components: {
Group,
Cell
}
}
</script>main.js中调用plugin
import { AlertPlugin, ToastPlugin } from 'vux'
Vue.use(AlertPlugin)
Vue.use(ToastPlugin)
// 详细使用请参考对应组件文档折腾能力强的同学参考一下，下面即vuxjs/vux2模板主要处理的事项:
注意的是下面事项并非表示Vux使用繁琐，部分只是出于确保有正确的依赖和配置，而部分是出于优化。
-
引入
reset.less，默认样式不包含reset，并且部分用户自己有一套reset样式，因此需要在App.vue进行手动引入<style lang="less"> @import '~vux/src/styles/reset.less'; </style>
-
配置vue-loader（通过配置vux-loader实现）
// vux-loader plugins: [{ name: 'vux-ui' }]
-
配置babel-loader以正确编译Vux的js源码（通过配置vux-loader实现）
plugins: [{ name: 'vux-ui' }]
-
安装less-loader以正确编译less源码
npm install less less-loader --save-dev
-
安装 yaml-loader 以正确进行语言文件读取
npm install yaml-loader --save-dev
-
添加viewport meta
<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=0">
-
添加Fastclick移除移动端点击延迟
const FastClick = require('fastclick') FastClick.attach(document.body)
-
添加vue-router（如果不需要前端路由，可忽略）
import VueRouter from 'vue-router' Vue.use(VueRouter)
-
添加webpack plugin, 在构建后去除重复css代码（通过配置vux-loader实现）
plugins: [{ name: 'duplicate-style' }]
-
如果你使用 webpack-simple 模板或者 webpack 配置里缺少 .vue extension 配置，请记得配置：
resolve: { extensions: ['.js', '.vue', '.json']
如果你是新项目，请直接使用webpack方式，umd构建产生的问题处理优先级会比较低。在下个主版本将只支持webpack。
详细请参照 文档
暂时只支持配合`vux-loader`使用。
如果你只需要默认的中文组件，那么你可以略过下面说明，只要启用`vux-ui`插件即可。
默认不配置此插件时，vux源码会按照默认语言zh-CN进行静态编译，和原来的使用没有明显不同。
详细请参照 vux-loader的vux-i18n文档
暂时只支持配合`vux-loader`使用。
注意的是主题文件不能引入其他less文件，只能为变量列表。
请配置vux-loader的less-theme插件，指定用以覆盖的less文件路径：
{
name: 'less-theme',
path: 'src/styles/theme.less'
}
源码地址：https://github.com/airyland/vux/blob/v2/src/styles/variable.less
更多配置需求请通过 issue 提出。
源代码地址：https://github.com/airyland/vux/blob/v2/src/theme.less
推荐使用官方 vue-router，VUX组件link属性直接支持vue-router的链接参数，VUX2模板也是内置了vue-router。
如果使用了过渡(转场动画)，在`iPhone`上使用`左划返回`时动画会再执行一遍，目前没有找到可行的处理方法，如果你有处理方案，欢迎`PR`。
单页面应用切换时要手动触发页面统计，首先在index.html里引入谷歌统计代码：
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-yourID', 'auto')
ga('send', 'pageview') // 是否要统计着陆页面访问，取决于你的需求，这个不一定需要，会和`router`统计有重复// main.js 里，如果你使用了 vue-router
router.afterEach(function (to) {
if (window.ga) {
window.ga('set', 'page', to.fullPath) // 你可能想根据请求参数添加其他参数，可以修改这里的 to.fullPath
window.ga('send', 'pageview')
}
})该插件提供了commonJS的引入方式。
分享接口只有认证公众号才能使用，域名必须备案且在微信后台设置。
先确认已经满足使用`jssdk`的要求再进行编码。
`WechatPlugin`在`vux@^2.1.0-rc.19`开始支持
import { WechatPlugin } from 'vux'
Vue.use(WechatPlugin)
console.log(Vue.wechat) // 可以直接访问 wx 对象。那么之后任何组件中都可以通过 this.$wechat 访问到 wx 对象。
考虑到你需要在引入插件后调用wx.config方法进行配置，你可以通过 Vue.wechat 在组件外部访问wx对象。
jssdk需要请求签名配置，你可以直接使用下面的ajaxPlugin。
`AjaxPlugin`在`vux@^2.1.0-rc.20`开始支持
import { AjaxPlugin } from 'vux'
Vue.use(AjaxPlugin)
console.log(Vue.http)然后你可以和vue-resource一样在组件内使用this.$http进行调用了。
AjaxPlugin 插件依赖于 axios，需要注意的是axios是基于Promise的，因此如果你需要兼容低版本浏览器(caniuse)，需要引入polyfill。
Polyfill 推荐使用 es6-promise
require('es6-promise').polyfill()移动端如果使用异步组件加载那么还是需要一点等待时间的，在网络慢时等待时间会更长。显示Loading状态缓解一下用户等待情绪就十分重要。
如果你使用vue-router和vuex，那么可以很容易实现。
首先，注册一个module来保存状态
const store = new Vuex.Store({}) // 这里你可能已经有其他 module
store.registerModule('vux', { // 名字自己定义
state: {
isLoading: false
},
mutations: {
updateLoadingStatus (state, payload) {
state.isLoading = payload.isLoading
}
}
})然后使用vue-router的beforeEach和afterEach来更改loading状态
router.beforeEach(function (to, from, next) {
store.commit('updateLoadingStatus', {isLoading: true})
next()
})
router.afterEach(function (to) {
store.commit('updateLoadingStatus', {isLoading: false})
})在App.vue里使用loading组件并从vuex获取isLoading状态
<loading v-model="isLoading"></loading>import { Loading } from 'vux'
import { mapState } from 'vuex'
export default {
components: {
Loading
},
computed: {
...mapState({
isLoading: state => state.vux.isLoading
})
}
}done.
如果你觉得在加载比较快时Loading组件一闪而过体验也不大好，那么你可以延迟设置loading=false。
在main.js里引用fastclick
const FastClick = require('fastclick')
FastClick.attach(document.body)将所有页面组件一次性加载是一个很浪费资源和考验用户耐心的做法，尤其在移动端。
webpack 提供了code splitting，你可以按照下面写法实现当切换到特定路由时才加载代码。
{
path: '/somepath',
component: function (resolve) {
require(['./demos/somepath.vue'], resolve)
}
}
manifest文件为路径配置和异步组件名字列表，该做法可以减少一个`http`请求。
确保 `vux-loader`更新到 `^1.0.35`
首先在页面的</body>前加入代码：
<%=htmlWebpackPlugin.files.webpackManifest%>然后在vux-loader配置的 plugins 列表中加入inline-manifest插件
{
name: 'inline-manifest'
}或者简化写法直接使用名字：
'inline-manifest'在微信iOS webview更新到WKWebView之前我们可以通过加载一个iframe来实现单页面应用title更改。但是17年初更新到WKWebView后该方法也失效，据对开发者十分特别不友好的把所有文档放在同一个页面不能通过url区分甚至连锚点也懒得做的的微信开发文档(链接)说，3月份会修复。
原话如下：
使用WKWebView，在单页应用中通过document.title多次修改原生title的方法将失效，该问题将于微信3月份发布的版本中解决。
微信对于部分合作方开放了jssdk的setBounceBackground及setNavigationBarColor权限，目测暂无申请入口。
如果你需要让一个工具函数在每个组件可用，可以把方法挂载到 Vue.prototype上。
main.js 中
Vue.prototype.method = function () {}那么组件代码里
this.method()vue官方模板的设置是last 2 versions，相对来说支持浏览器版本过少，会导致你在某些Android机子上出现问题。
如果你使用 last 7 versions 会生成不必要的-ms前缀代码.
因此建议同WeUI一样，使用配置 ['iOS >= 7', 'Android >= 4.1']
并不推荐禁用eslint, 编码规范可以一定程序上保证代码质量。但是如果你确实想禁用，可以删除build/webpack.base.conf.js里的相关代码。
preLoaders: [
{
test: /\.vue$/,
loader: 'eslint',
include: [
path.join(projectRoot, 'src')
],
exclude: /node_modules/
},
{
test: /\.js$/,
loader: 'eslint',
include: [
path.join(projectRoot, 'src')
],
exclude: /node_modules/
}
]如果你只是想禁用对某一文件的检测，那么可以在.eslintignore里添加规则。
如果你是想禁止某一行的检测，那么可以使用// eslint-disable-line。
更加灵活的使用参考 eslint文档。
实际项目开发中会有很多工具函数的需求，`VUX`提供这些工具库并不会让你的项目代码变得臃肿。
所有组件或者工具函数都是**按需使用**。
对于有相关需求的开发者来说，不用自己写或者花时间去寻求合适的第三方库了，开箱即用。
请注意了解 `debounce` 和 `throttle` 的区别。如果尚不清楚，请`google`之。
import { debounce } from 'vux'
debounce(func, [wait=0], [options={}])import { throttle } from 'vux'
throttle(func, [wait=0], [options={}])import { cookie } from 'vux'get *cookie.get(name, [options])*
获取 cookie 值。options 参数可选，取值如下：
converter转换函数。如果所获取的 cookie 有值，会在返回前传给converter函数进行转换。- 选项对象。对象中可以有两个属性：
converter和raw.raw是布尔值，为真时，不会对获取到的 cookie 值进行 URI 解码。
注：如果要获取的 cookie 键值不存在，则返回 undefined.
例子：
// setup
document.cookie = 'foo=1'
document.cookie = 'bar=2'
cookie.get('foo')
// returns '1'
cookie.get('bar', function(s) { return parseInt(s); } )
// returns 2set *cookie.set(name, value, [options])
设置 cookie 值。参数 options 可选，可以有以下属性：path（字符串）、domain（字符串）、
expires（数值或日期对象）、raw（布尔值）。当 raw 为真值时，在设置 cookie 值时，不会进行
URI 编码。
例子：
cookie.set('foo', 3)
cookie.set('bar', 4, {
domain: 'example.com',
path: '/',
expires: 30
})remove *cookie.remove(name, [options])
移除指定的 cookie.
例子：
cookie.remove('foo')
cookie.remove('bar', {
domain: 'example.com',
path: '/'
})import { base64 } from 'vux'
base64.encode('VUX')
base64.decode('VlVY')
该工具直接依赖于 [blueimp-md5](https://github.com/blueimp/JavaScript-MD5)
注意: `md5`是消息摘要算法并非加密算法，用于需要加密的场景会有安全问题。
import { md5 } from 'vux'
md5('VUX')
相对moment来说十分轻量的实现。
import { dateFormat } from 'vux'
dateFormat(new Date(), 'YYYY-MM-DD HH:mm:ss')numberComma用于分割数字，默认为3位分割，一般用于格式化金额。
numberPad用于按照位数补0
numberRandom用于生成两个整数范围内的随机整数
import { numberComma, numberPad, numberRandom } from 'vux'
numberComma(21342132) // 21,342,132
numberComma(21342132, 4) // 2134,2132
numberComma(21342132.234) // 21,342,132.234
numberPad(1) // 01
numberPad(234, 4) // 0234
numberRandom(1, 7) // 2import { stringTrim } from 'vux'
stringTrim(' 1024 ') // 1024import { querystring } from 'vux'
querystring.parse('a=b&c=d') // {a:'b',c:'d'}, 默认参数为 location.search
querystring.stringify({a:'b',c:'d'}) // 'a=b&c=d'，注意不支持复杂嵌套的结构-
能否在微信小程序里使用
Sorry，不能。微信小程序是个相对封闭的平台，无法方便地适配。
-
文档是用什么工具编写的？
-
Can't resolve '../inline-desc' in
webpack resolve配置
resolve: { extensions: ['', '.js', '.vue', '.json'] }
-
初始化时eslint选择 airbnb 报import extension
项目目录下的.eslintrc.js 修改：
'rules': { // don't require .vue extension when importing 'import/extensions': ['off', 'always', { // 设为 off 'js': 'never', 'vue': 'never' }], 'import/no-unresolved': [0, {commonjs: true, amd: true}], // 添加这一行 // allow debugger during development 'no-debugger': process.env.NODE_ENV === 'production' ? 2 : 0 }
报
document不存在，请在rules前添加配置：'globals': { 'document': true }, 'rules' balabala
-
$t is not defined
请参照文档配置
vux-loaderdemo例子使用
$t是因为demo启用了i18n，如果你没有使用vuex-i18n等相关i18n插件，请不要使用$t函数如果已经配置
vux-loader但依然有错误，请清除node_modules使用npm install重新安装，cnpm install可能会导致出问题。 -
Uncaught SyntaxError: Unexpected token export
原因是Vux的js源码没配置babel，你可以在webpack配置的loaders加上
{
test: /vux.src.*?js$/,
loader: 'babel'
}或者启用vux-loader的vux-ui插件。
-
样式冗余
调试时有多个重复样式是正常的，因为不同组件引用了同样的less源码，而调试时是直接把不同组件样式用
<style>标签插入页面。确保在vux-loader里使用
duplicate-style来实现对构建css进行压缩。 -
Vux 是否为微信官方项目
否。但是依赖的WeUI是微信团队的开源项目，感谢微信团队。
-
为什么部分组件要加
x-前缀若不更名，可能在开发时与标准html标签相同而导致冲突或者bug。从[email protected]开始已经强制不能使用原生html标签。
-
为什么不把组件打包成js进行分发
代码冗余，无法在构建时优化，出错时难以跟踪，作为组件维护者可能要打包多份代码出来满足不同需求(压缩版，未压缩，不同语言版)。在webpack中如果不加配置还会被多次打包。
整体打包成一个js和一个css在移动端属于严重浪费，降低体验和性能。
就上面的问题来说，源码分发的方式完美解决。
vux-playground支持在线编辑和预览基于vux的页面，也是为了方便重现bugvux-shop基于vux的完整前端商城模板
请更新 `NodeJS` 版本到 `v7.6.0` 以上，`build` 命令逐步使用 `async`。
yarn // 使用 yarn.lock 保证依赖版本一致
yarn devnpm run build-docs // 构建文档
npm run docs // 使用 docute 预览文档遵从 Github 上的 contribution template.
如果修改了组件代码，需要在组件目录的metas.yml加上changes，直接使用next作为版本号(如果已经存在该版本号，则直接添加变更条目即可)。
中括号内为变更类型，可选值 fix enhance feature change
比如：
changes:
next:
en:
- '[fix] fix *** bug #issueId'
zh-CN:
- '[fix] 修复 *** bug #issueId'目前英文文档并不完善，欢迎帮忙翻译。文档格式为yml，位于每个组件目录下的metas.yml文件，你可以参阅一些相对完善的组件文档进行更新。
当PR被合并后，文档服务器会在5分钟内拉取最新代码并执行npm run build-docs及npm run build实现文档及demo更新。
使用本项目意味着你也有义务帮助其变得更好。
不要浪费维护者时间。
不要让维护者帮你学习Vue，帮你熟悉vue-loader，甚至帮你写代码。
不要认为随便一句话就能让维护者明白你的意思，我们没有你想象的那么厉害。
不要提没有任何意义的、代码中带有业务逻辑不方便重现的Issue。
直接关闭你的issue不是对你不满，是你提问题方式不对，没有必要再浪费时间说明为什么要关闭你的issue。
Vux 参考或者使用了以下开源项目的代码