cube-ui 移动端 Vue 组件库完全上手指南：安装、按需引入与本地开发-开发者社区

前端
UI组件
移动开发

【免费下载链接】cube-ui

:large_orange_diamond: A fantastic mobile ui lib implement by Vue

项目地址：https://gitcode.com/gh_mirrors/cu/cube-ui

cube-ui 是由滴滴出行开源的移动端 UI 组件库，基于 Vue 2.x 实现，目标是提供一套高质量、可定制、体验接近原生 App 的移动端组件解决方案。本文以仓库内的 README_zh-CN.md 为骨架，完整覆盖从新项目初始化、全量/按需引入、到本地开发调试的完整链路，并深入源码说明其插件安装机制与底层实现，帮助你快速在自己的 Vue 移动端项目中落地 cube-ui。

项目概览：cube-ui 是什么

cube-ui 的官方定位是一套"A fantastic mobile ui lib implement by Vue"，即基于 Vue 实现的移动端 UI 库。从 package.json 可以确认，当前仓库对应版本为1.12.56，包名cube-ui，入口配置如下：

main:lib/index.js（UMD 构建产物，供 CommonJS/浏览器直接使用）
module:src/index.js（ES Module 源码入口，供支持 tree-shaking 的打包器使用）
typings:types/index.d.ts（TypeScript 类型声明）
peerDependencies:vue ^2.5.13（明确要求 Vue 2.5.13 及以上版本）
运行时依赖仅两个：better-scroll ~1.12.6与vue-create-api ^0.2.3

这意味着 cube-ui 组件库在组件维度上覆盖了基础交互（Button、Loading、Tip、Toolbar）、表单（Checkbox、Radio、Input、Select、Switch、Rate、Validator、Upload、Form）、弹层（Popup、Toast、Picker、Dialog、ActionSheet、Drawer、ImagePreview）、滚动交互（Scroll、Slide、IndexList、Swipe、Sticky、ScrollNav、RecycleList）四大类，全部组件清单可以在 src/module.js 中查看到。

新项目：使用官方模板快速初始化

如果你是从零开始的新项目，README 推荐使用基于 vue-cli 的官方模板 cube-template 来初始化配置与代码，一条命令即可：

$ vue init cube-ui/cube-template projectname

该模板会帮你完成 Vue 项目脚手架搭建，并预置 cube-ui 相关的构建配置（例如按需加载所需的 babel 插件配置）。如果你的项目不是新项目，而是已有工程，则直接跳到下一步"安装"即可。

安装 cube-ui

在任意 Vue 2.x 项目中，通过 npm 安装并保存为运行依赖：

npm install cube-ui --save

安装完成后，你的package.json的dependencies中会出现cube-ui条目。由于 cube-ui 依赖 Vue 2.x，请确保项目中的 Vue 版本不低于2.5.13（见 package.json 的peerDependencies）。

全量引入：一行代码注册全部组件

最直接的用法是整体引入并注册，在项目的入口文件（通常是main.js）中：

import Vue from 'vue' import Cube from 'cube-ui' Vue.use(Cube)

执行Vue.use(Cube)后，所有组件与样式都会被全局注册。从源码 src/index.js 可以看到这一过程的实现细节：

src/index.js从./module聚合导入全部组件，组装成一个components数组；
定义install(Vue)函数，遍历数组调用每个组件的install方法完成全局注册（Radio组件除外，因为它以RadioGroup.Radio的子组件形式提供，见 src/module.js）；
最终导出的Cube对象上除了install，还挂载了BScroll（即 better-scroll 的直接引用）和createAPI两个工具，并且每个组件也以首字母大写的属性形式暴露在Cube上，例如Cube.Button、Cube.Toast；
如果页面环境存在全局window.Vue，还会自动执行window.Vue.use(install)实现免 import 的自动注册。

组件注册的底层依赖install方法，例如 src/modules/button/index.js：

import Button from '../../components/button/button.vue' Button.install = function (Vue) { Vue.component(Button.name, Button) } export default Button

可以看到每个模块都是标准 Vue 插件形态：通过Vue.component以组件自身的name（形如cube-button）注册为全局组件。

按需使用：显著减小打包体积

全量引入会打包所有组件，对于只需要其中部分组件的业务场景，README 提供了按需使用的方式。只需按命名导出引入所需组件，并逐个注册：

import Vue from 'vue' import { /* eslint-disable no-unused-vars */ Style, Button, ActionSheet } from 'cube-ui' Vue.use(Button) Vue.use(ActionSheet)

这段代码有两个关键细节：

Style必须引入：Style是样式模块，对应 src/modules/style/index.js，其内部只是import '../../common/stylus/index.styl'导入全局样式并在install()中空实现。按需引入时若不导入Style，组件虽然注册成功，但缺少基础样式与主题变量。引入Style后虽然对其调用Vue.use无实际效果，但按需场景下建议与其他组件一并引入（或通过构建配置单独注入样式）。
依赖babel-plugin-transform-modules：README 明确说明，上述按需命名导入依赖 Babel 插件 babel-plugin-transform-modules，需要先在.babelrc中配置，例如：

{ "plugins": [ ["transform-modules", { "cube-ui": { "transform": "cube-ui/lib/${member}", "kebabCase": true } }] ] }

配置后，import { Button } from 'cube-ui'会被编译为从cube-ui/lib/button引入，从而只打包 Button 组件及其依赖，未配置该插件时按需写法无法生效。

深入源码：createAPI 与命令式组件调用

cube-ui 的一大特色是支持以命令式 API 调用组件（如Toast、Dialog、ActionSheet等弹层类组件），这依赖vue-create-api。仓库在 src/common/helpers/create-api.js 中封装了入口：

import createAPIComponent from 'vue-create-api' export default function createAPI (Vue, Component, events, single) { Vue.use(createAPIComponent, {componentPrefix: 'cube-'}) const api = Vue.createAPI(Component, events, single) return api }

其工作流程是：先以cube-作为组件名前缀安装vue-create-api插件，再通过Vue.createAPI(Component, events, single)生成命令式调用方法。以 Toast 为例，开发者可以在任意组件中直接this.$createToast({ txt: 'Hello' }).show()，无需在模板中声明<cube-toast>。single参数控制该组件实例是否为单例模式，例如提示类组件通常希望全局只有一个实例。

createAPI作为独立模块通过 src/modules/create-api/index.js 对外导出，并在 src/index.js 中挂载到Cube.createAPI上，方便第三方组件作者复用同样的机制为自己的组件生成命令式 API。

本地开发：克隆仓库并运行

如果你想在本地运行 cube-ui 的示例工程或参与源码开发，README 给出了完整步骤：

git clone git@github.com:didi/cube-ui.git cd cube-ui npm install npm run dev # or run document development npm run doc-dev

对应的 npm scripts 定义在 package.json：

命令	作用
`npm run dev`	启动组件示例（example）开发服务器
`npm run doc-dev`	同时启动文档站与示例开发服务器
`npm run build`	执行构建，产出`lib/`下的 UMD 产物
`npm run doc-build`/`demo-build`	分别构建文档站与示例站点
`npm run lint`	对`src`与测试目录执行 ESLint 检查
`npm run unit`	通过 Karma 运行单元测试（见 test/unit/karma.conf.js）
`npm run test`	运行单元测试并上报 codecov 覆盖率

npm install会拉取全部依赖，包括构建链路的 webpack 3、babel、stylus 等（见 package.json 的devDependencies）。注意项目要求 Node >= 4、npm >= 3（见engines字段），如使用较新的 Node 版本出现兼容问题，建议参考 CI 配置中的 Node 版本运行。

npm run dev启动后，示例应用与文档应用均基于 webpack-dev-server 提供热更新。文档应用入口在 document/main.js，示例应用入口在 example/main.js，两者的页面路由分别由 document/router/index.js 与 example/router/index.js 管理。

仓库结构导览：源码、产物与文档

阅读源码时可按以下路径快速定位：

组件源码：所有.vue组件集中在 src/components 下，每个组件一个目录，如button/button.vue、toast/toast.vue；
模块包装层：src/modules 下的同名目录负责为每个组件补齐install方法并导出，是"全量引入"与"按需引入"两条路径的公共出口；
公共能力：src/common/helpers 提供create-api.js、dom.js、util.js等工具，src/common/mixins 提供popup.js、scroll.js、input.js等复用逻辑；
构建产物：lib 目录存放每个组件独立的*.min.js/*.min.css与总包cube.min.js/cube.min.css，按需引入时 babel 插件实际指向这里；
类型声明：types 与 test/test-dts 提供 TypeScript 类型与类型测试，vetur 提供 Vetur 的标签与属性补全元数据；
文档与示例：document 是文档站源码（含中英文 45 篇组件文档），example 是组件示例工程，docs 是构建后的静态站点产物。

版本说明与适用前提

本文所有结论均基于当前仓库的实际内容：

当前仓库版本为1.12.56，仅面向Vue 2.x（peerDependencyvue ^2.5.13），不适用于 Vue 3 项目；
全量引入最简单，但体积较大；按需引入需要额外配置babel-plugin-transform-modules；
命令式 API（如this.$createToast）依赖vue-create-api，已在 src/common/helpers/create-api.js 中统一封装。

对于希望直接上手体验的读者，可以用手机扫描 assets/example-qr.png 中的示例二维码，或在本地按上文"本地开发"一节启动示例工程后访问示例页面，直观查看各组件在真实移动端视口下的交互效果。掌握上述安装、引入与开发三条路径后，你便可以在自己的 Vue 移动端项目中熟练使用 cube-ui 了。