企业官网建设流程全解析

• 前端
• UI组件
• 移动开发

cube-ui 是一套由滴滴开源、基于 Vue 实现的移动端 UI 组件库，本指南以官方快速上手文档为主线，系统讲解从脚手架初始化、NPM/CDN 安装、后编译与普通编译两种构建方式，到全量引入与按需引入、以及 TypeScript 开发环境配置的完整链路。读完本文，你将能在新项目或现有 Vue 项目中快速集成 cube-ui，并理解其模块化导出与按需打包的底层原理。

一、项目脚手架初始化

cube-ui 官方为不同版本的 Vue CLI 提供了两套脚手架方案，可以直接生成包含 cube-ui 配置与基础代码的项目骨架。

vue-cli >= 3：使用插件vue add cube-ui

如果你正在使用新版 Vue CLI（vue-cli@3 及以上），官方推荐直接使用vue-cli-plugin-cube-ui插件。在项目初始化完成后，于项目根目录执行：

$ vue add cube-ui

执行过程中会询问一系列配置项，这些配置项与老版本模板（cube-template）的配置一致，例如是否使用后编译、是否需要内置基础样式等。选择完成后即可直接进入本文「使用 cube-ui」章节。

vue-cli < 3：使用脚手架模板

如果你打算在一个新项目中使用 cube-ui，可以通过官方提供的基于 vue-cli 实现的脚手架模板 cube-template 来初始化项目配置和基础代码：

$ vue init cube-ui/cube-template projectname

初始化时同样会询问特殊的配置项，选择符合项目需求的选项即可。通过脚手架初始化的项目会自动完成依赖与构建配置，可以跳过下方「安装」步骤，直接进入「使用」环节；而如果是在现有项目中接入 cube-ui，则需要先完成安装与构建配置。

二、安装 cube-ui

注意：以下安装部分主要针对 vue-cli < 3 的手工集成场景；使用脚手架模板初始化的项目可以跳过。

NPM 安装

$ npm install cube-ui --save

从当前仓库的 package.json 可以看到，cube-ui 的main指向lib/index.js（编译产物入口）、module指向src/index.js（源码入口，供后编译使用），peerDependencies要求 Vue^2.5.13，运行时依赖better-scroll（滚动能力）与vue-create-api（函数式 API 基础）。安装后需要根据构建方式修改应用依赖与配置。

cube-ui 搭配 webpack 2+ 支持后编译（post-compile）和普通编译两种构建方式，默认使用后编译。两种方式的本质区别在于：

• 后编译：直接以cube-ui/src/**的 Stylus / Vue 源码参与构建，样式可随主题变量定制，需要额外引入 Stylus 相关 loader 和两个 webpack 插件；
• 普通编译：使用cube-ui/lib/**下预编译好的 JS 与 CSS 产物，构建更简单，但样式定制能力受限。

后编译配置（推荐）

后编译需要修改 4 处配置，让 webpack 能处理 cube-ui 的源码与 Stylus 样式。

1. 修改 package.json 并安装依赖

webpack-transform-modules-plugin插件依赖transformModules字段，将cube-ui的模块导入路径重写为源码目录：

{ // webpack-transform-modules-plugin 依赖 transformModules "transformModules": { "cube-ui": { "transform": "cube-ui/src/modules/${member}", "kebabCase": true } }, "devDependencies": { // 新增 stylus 相关依赖 "stylus": "^0.54.5", "stylus-loader": "^2.1.1", "webpack-post-compile-plugin": "^1.0.0", "webpack-transform-modules-plugin": "^0.4.3" } }

其中kebabCase: true表示导入路径中的驼峰命名会自动转换为 kebab-case，与 src/modules 下的目录命名保持一致（例如import { DatePicker } from 'cube-ui'会被重写到cube-ui/src/modules/date-picker）。

2. 修改 webpack.base.conf.js，注册两个插件

var PostCompilePlugin = require('webpack-post-compile-plugin') var TransformModulesPlugin = require('webpack-transform-modules-plugin') module.exports = { // ... plugins: [ // ... new PostCompilePlugin(), new TransformModulesPlugin() ] // ... }

PostCompilePlugin负责把 node_modules 中需要后编译的源码（即 cube-ui 的src目录）纳入编译管线；TransformModulesPlugin负责执行路径重写。

3. 修改 build/utils.js 中的exports.cssLoaders函数

为 Stylus 开启resolve url，使样式内引用的字体、图片等资源路径可以被正确解析：

exports.cssLoaders = function (options) { // ... const stylusOptions = { 'resolve url': true } // https://vue-loader.vuejs.org/en/configurations/extract-css.html return { css: generateLoaders(), postcss: generateLoaders(), less: generateLoaders('less'), sass: generateLoaders('sass', { indentedSyntax: true }), scss: generateLoaders('sass'), stylus: generateLoaders('stylus', stylusOptions), styl: generateLoaders('stylus', stylusOptions) } }

4. 修改 vue-loader.conf.js

确保 vue-loader 使用上述 cssLoaders，并关闭样式抽离（extract: false，交由后编译统一处理）：

module.exports = { loaders: utils.cssLoaders({ sourceMap: sourceMapEnabled, extract: false }), // ... }

普通编译配置

如果不想引入 Stylus 编译链路，可以使用普通编译，直接消费lib目录下的预编译产物（当前仓库 lib 目录中每个组件均有独立目录及*.min.js/*.min.css）。

1. 修改 package.json 并安装依赖

{ // webpack-transform-modules-plugin 依赖 transformModules "transformModules": { "cube-ui": { "transform": "cube-ui/lib/${member}", "kebabCase": true, "style": { "ignore": ["create-api", "better-scroll", "locale"] } } }, "devDependencies": { "webpack-transform-modules-plugin": "^0.4.3" } }

transform指向cube-ui/lib/${member}，即预编译产物目录；style.ignore列表中的模块（create-api、better-scroll、locale）是纯 JS 模块，不附带独立样式，因此不进行样式导入。

2. 修改 webpack 配置

// webpack.config.js var TransformModulesPlugin = require('webpack-transform-modules-plugin') module.exports = { // ... resolve: { // ... alias: { // ... 'cube-ui': 'cube-ui/lib' // ... } // ... } // ... plugins: [ // ... new TransformModulesPlugin() ] // ... }

通过alias将cube-ui指向cube-ui/lib，配合TransformModulesPlugin完成按需路径重写。

CDN 引入

在不使用构建工具的场景（如纯静态页面、快速 Demo），可以直接通过 CDN 引入全量编译产物：

<script src="https://unpkg.com/cube-ui/lib/cube.min.js"></script> <link rel="stylesheet" href="https://unpkg.com/cube-ui/lib/cube.min.css">

cube.min.js与cube.min.css即当前仓库 lib 目录下的全量打包文件，引入后window.Vue存在时 cube-ui 会自动执行安装（见下文源码说明）。

三、使用 cube-ui

全部引入

一般在入口文件（如src/main.js）中全量注册：

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

从仓库入口 src/index.js 的源码可以看到全量引入的完整行为：Cube对象暴露了version、install、BScroll与createAPI；install方法遍历全部组件数组，逐个调用Component.install(Vue)完成全局注册，其中Radio被显式跳过——因为它是RadioGroup的内部子组件，已随 RadioGroup 一并注册。此外，文件末尾还处理了 CDN 场景：当window存在且已有window.Vue时自动调用Vue.use(install)，这正是上一节 CDN 引入无需手动Vue.use的原因。

按需引入

按需引入可以显著减小打包体积，例如只引入按钮组件：

import { /* eslint-disable no-unused-vars */ Style, Button } from 'cube-ui'

注意：按需引入时，基础样式（内置 icon、reset、通用样式）不会被自动打包，因此需要同时引入Style模块。关于基础样式的具体内容（内置 icon 列表、reset.css、base.css、1px 边框工具类等），可参考 style 模块文档；其源码实现见 src/modules/style/index.js，本质是引入src/common/stylus/index.styl的样式入口模块。

推荐对按需引入的组件直接进行全局注册，避免在每个页面重复 import：

// 全局注册 Vue.use(Button) // ...

每个组件的模块文件都实现了标准的install方法，例如 src/modules/button/index.js 中即通过Vue.component(Button.name, Button)完成注册。

所有可按需引入的组件与模块

cube-ui 支持按需引入的全部组件与模块清单如下（与 src/module.js 的导出保持一致）：

import { // 基础样式 Style, // basic Button, Loading, Tip, Toolbar, // form Checkbox, CheckboxGroup, Radio, Checker, Input, Textarea, Select, Switch, Rate, Validator, Upload, Form, // popup Popup, Toast, Picker, CascadePicker, DatePicker, TimePicker, SegmentPicker, Dialog, ActionSheet, Drawer, // scroll Scroll, Slide, IndexList, Swipe } from 'cube-ui'

其中部分组件还附带子组件导出，如Form.Item/Form.Group、Slide.Item、Swipe.Item、Drawer.Panel/Drawer.Item、Sticky.Ele、TabBar.Tab、TabPanels.Panel、Checker.Item等，均可在 src/module.js 中查到对应导出。

除了组件，还可以引入三个核心模块：

import { createAPI, BetterScroll, Locale } from 'cube-ui'

• createAPI：让组件支持this.$createXxx()函数式调用。其实现见 src/common/helpers/create-api.js，内部基于vue-create-api并以cube-作为组件前缀，例如$createDialog、$createToast；
• BetterScroll：基于 better-scroll 封装的滚动能力，cube-ui 的 Scroll、Slide、IndexList 等滚动类组件都建立在它之上；
• Locale：多语言配置模块，其源码见 src/modules/locale/index.js，同时导出localeMixin供组件复用。

完整示例

以下示例演示了按需引入组件配合createAPI函数式调用的典型用法：

<template> <cube-button @click="showDialog">show dialog</cube-button> </template> <script> export default { methods: { showDialog() { this.$createDialog({ type: 'alert', title: 'Alert', content: 'dialog content' }).show() } } } </script>

四、TypeScript 开发环境配置

cube-ui 从 v1.12.39 开始提供更好的 TypeScript 支持（当前仓库版本为 1.12.56，已包含该能力）。若使用 Visual Studio Code + Vetur 进行开发，需要满足以下版本要求：

TypeScript 类型声明文件位于仓库 types 目录，入口为 types/index.d.ts，其内部转出完整的 cube-ui.d.ts，后者覆盖了全部组件的 props、方法、事件与函数式 API 的类型定义，各组件独立类型声明位于 types/components 目录（如 Button、Dialog、Toast 等）。同时 package.json 中typings字段已指向types/index.d.ts，vetur字段指向 vetur/tags.json 与 vetur/attributes.json，使 IDE 可以自动获得组件标签与属性提示。满足版本要求后，在 tsconfig 中引入 cube-ui 即可获得完整的类型检查与编辑器智能提示。

五、小结

本文完整梳理了 cube-ui 的接入路径：脚手架层面支持 vue-cli 3+ 的vue add cube-ui与 vue-cli < 3 的模板初始化；构建层面可按需选择后编译（灵活定制 Stylus 样式）或普通编译（直接消费lib预编译产物），也可通过 CDN 零构建接入；使用层面支持Vue.use(Cube)全量注册与import { Style, Button }按需引入两种方式，配合createAPI、BetterScroll、Locale三大模块可满足移动端项目的大部分交互需求。仓库源码（src/index.js、src/module.js、src/modules）与类型声明（types）为理解内部注册机制与 TS 接入提供了直接参考，更多组件细节可继续阅读 docs 文档目录下的各组件说明。

• 前端
• UI组件
• 移动开发