Vux 2.0 升级指南：从 Vue 1.x 到 Vue 2.x 的平滑迁移

Vux 2.0 升级指南：从 Vue 1.x 到 Vue 2.x 的平滑迁移

vux Mobile UI Components based on Vue & WeUI 项目地址: https://gitcode.com/gh_mirrors/vu/vux

前言

随着 Vue.js 2.0 的发布，基于 Vue 的 UI 组件库 Vux 也迎来了重大版本更新。本文将详细介绍如何将项目从 Vux 1.x 升级到 2.x 版本，帮助开发者顺利完成迁移工作。

Vue 2.x 核心变更

Vux 2.x 基于 Vue 2.x 构建，因此首先需要了解 Vue 2.x 的主要变更点：

1. 双向绑定语法变更：废弃了 :value.sync 语法，统一使用 v-model
2. 事件系统调整：组件上的 @click 需要改为 @click.native
3. v-for 参数顺序：从 (index, item) 变为 (item, index)
4. 广播机制：broadcast 方法已被废弃

建议开发者先熟悉 Vue 2.x 的官方迁移指南，这对理解后续的 Vux 组件变更很有帮助。

路由系统升级

与 Vue 2.x 配套的 vue-router 也需要升级到 2.0 以上版本：

路由配置变更

const routes = [{
  path: '/vux/2.0',
  component: Vux2Demo
}]

const router = new VueRouter({
  routes
})

路由挂载方式

new Vue({
  router,
  render: h => h(App)
}).$mount('#app')

路由跳转变更

• 废弃 go 方法，改用 push
• 废弃 v-link 指令，改用 <router-link> 组件

Vux 2.x 主要变更点

构建系统优化

Vux 2.x 不再默认生成 UMD 文件，但可以通过 npm run build-components 命令手动构建。

双向绑定统一

所有组件的 :value.sync 语法都已统一为 Vue 2.x 标准的 v-model：

// 旧版本
<component :value.sync="someValue"></component>

// 新版本
<component v-model="someValue"></component>

引入 vux-loader

Vux 2.x 推荐使用 vux-loader 来简化配置：

const vuxLoader = require('vux-loader')
module.exports = vuxLoader.merge(webpackConfig, {
  options: {},
  plugins: [
    {
      name: 'vux-ui'
    }
  ]
})

使用 vux-loader 后，可以更简洁地引入组件：

import { Group, Cell } from 'vux'

组件命名规范

为避免与 HTML5 原生标签冲突，部分组件增加了 x- 前缀：

| 原组件名 | 新组件名 | |---------|---------| | Progress | XProgress | | Switch | XSwitch | | Dialog | XDialog | | Address | XAddress | | Circle | XCircle |

特定组件变更详解

Swiper 组件

引入路径发生了变化：

// 旧版本
import Swiper from 'vux/src/components/swiper'
import SwiperItem from 'vux/src/components/swiper-item'

// 新版本
import Swiper from 'vux/src/components/swiper/swiper'
import SwiperItem from 'vux/src/components/swiper/swiper-item'

废弃组件说明

1. ColorPicker：将在后续版本中移除，建议使用 Cell 组件配合 slot 实现类似功能
2. Countdown：功能较为单一，建议开发者自行实现更符合业务需求的倒计时组件

Scroller 组件重大更新

由于 Vue 2.x 废弃了 broadcast 方法，Scroller 组件的 API 有较大变化：

• 使用 ref 的 reset() 方法替代原来的 reset 方法
• pullup 相关操作改为 ref 方法：
  • donePullup()
  • disablePullup()
  • enablePullup()
• pulldown 操作改为 donePulldown()
• 状态绑定改为 v-model 方式：

status: {
  pullupStatus: 'default',
  pulldownStatus: 'default'
}

表单组件行为变更

1. 必填项默认值：与 HTML 规范保持一致，XInput 和 Checklist 组件的 required 属性默认为 true
2. Checklist 错误提示：不再自动显示错误样式，改为触发错误事件，开发者可通过 slot 自定义错误显示
3. XInput 验证：由于 Vue 2.x 的 ref 不再是响应式的，需要在提交时通过 ref 获取验证结果

XAddress 数据更新

Vux 2.x 使用了最新的行政区划数据：

import { XAddress, ChinaAddressData } from 'vux'

如需使用旧版数据：

import { XAddress, ChinaAddressV1Data } from 'vux'

注意：新版数据基于官方最新发布，部分区域已调整或取消，升级前请评估对现有数据的影响。

升级建议

1. 逐步升级：建议先升级 Vue 和 vue-router，再处理 Vux 组件
2. 全面测试：特别注意表单验证和路由跳转等核心功能
3. 备份数据：特别是使用 XAddress 组件的项目，行政区划数据变更可能导致数据不一致

通过本文的指导，开发者应该能够顺利完成 Vux 从 1.x 到 2.x 的升级工作。如在升级过程中遇到特殊问题，建议查阅 Vux 的详细文档获取更多帮助。

vux Mobile UI Components based on Vue & WeUI 项目地址: https://gitcode.com/gh_mirrors/vu/vux