ElementUI 是一套为开发者、设计师和产品经理准备的基于 Vue 2.0 的桌面端组件库。

0、前言

老规矩，带着问题看源码：

  • 组件全量引入和按需引入是如何做的？
  • 主题是如何实现定制的？
  • 国际化是如何实现的？
  • 怎样支持CDN引入和基于webpack的两种开发模式？
  • 开发组件时，组件MD文档是如何处理的？

1、目录结构

  • 基本结构
    build：存放构建相关的 shell 脚本和 js 脚本
    examples：Element 官方网站前端代码
    packages：组件库代码
    src：官方网站的入口文件和一些公用代码，如utils,mixins,directives,transitions等
    test：单元测试代码
    types：类型定义文件（typescript）
    注意这里没有最终编译生成的文件夹 lib，源码都这样，得运行脚本来构建lib
  • package.json
  1.   // 待发布的npm包由哪些目录组成
  2. "files": [
  3.   "lib",
  4.   "src",
  5.   "packages",
  6.   "types"
  7. ],
  8. // npm 包的入口
  9. "main": "lib/element-ui.common.js",
  10. // 类型定义入口
  11. "typings": "types/index.d.ts",
  12. "scripts": {
  13.     "bootstrap": "yarn || npm i",
  14.     "build:file": "node build/bin/iconInit.js & node build/bin/build-entry.js & node build/bin/i18n.js & node build/bin/version.js",
  15.     "build:theme": "node build/bin/gen-cssfile && gulp build --gulpfile packages/theme-chalk/gulpfile.js && cp-cli packages/theme-chalk/lib lib/theme-chalk",
  16.     "build:utils": "cross-env BABEL_ENV=utils babel src --out-dir lib --ignore src/index.js",
  17.     "build:umd": "node build/bin/build-locale.js",
  18.     "clean": "rimraf lib && rimraf packages/*/lib && rimraf test/**/coverage",
  19.     "deploy:build": "npm run build:file && cross-env NODE_ENV=production webpack --config build/webpack.demo.js && echo element.eleme.io>>examples/element-ui/CNAME",
  20.     "dev": "npm run bootstrap && npm run build:file && cross-env NODE_ENV=development webpack-dev-server --config build/webpack.demo.js & node build/bin/template.js",
  21.     "dev:play": "npm run build:file && cross-env NODE_ENV=development PLAY_ENV=true webpack-dev-server --config build/webpack.demo.js",
  22.     "dist": "npm run clean && npm run build:file && npm run lint && webpack --config build/webpack.conf.js && webpack --config build/webpack.common.js && webpack --config build/webpack.component.js && npm run build:utils && npm run build:umd && npm run build:theme",
  23.     "i18n": "node build/bin/i18n.js",
  24.     "lint": "eslint src/**/* test/**/* packages/**/* build/**/* --quiet",
  25.     "pub": "npm run bootstrap && sh build/git-release.sh && sh build/release.sh && node build/bin/gen-indices.js && sh build/deploy-faas.sh",
  26.     "test": "npm run lint && npm run build:theme && cross-env CI_ENV=/dev/ BABEL_ENV=test karma start test/unit/karma.conf.js --single-run",
  27.     "test:watch": "npm run build:theme && cross-env BABEL_ENV=test karma start test/unit/karma.conf.js"
  28.   },

2、构建脚本分析

2.1、npm run dev

  • npm run build:file 并行执行以下四个js脚本
    1、node build/bin/iconInit.js
    通过 postcss 解析 icon.scss ，筛选出类名并最终导出到 icon.json 文件
  1. // node build/bin/iconInit.js
  2. 'use strict';
  4. var postcss = require('postcss');
  5. var fs = require('fs');
  6. var path = require('path');
  7. var fontFile = fs.readFileSync(path.resolve(__dirname, '../../packages/theme-chalk/src/icon.scss'), 'utf8');
  8. var nodes = postcss.parse(fontFile).nodes;
  9. var classList = [];
  11. nodes.forEach((node) => {
  12.   var selector = node.selector || '';
  13.   var reg = new RegExp(/\.el-icon-([^:]+):before/);
  14.   var arr = selector.match(reg);
  16.   if (arr && arr[1]) {
  17.     classList.push(arr[1]);
  18.   }
  19. });
  21. classList.reverse(); // 希望按 css 文件顺序倒序排列
  23. fs.writeFile(path.resolve(__dirname, '../../examples/icon.json'), JSON.stringify(classList), () => {});
  25. // 效果：
  26. // icon.scss 部分
  27. .el-icon-platform-eleme:before {
  28.   content: "\e7ca";
  29. }
  30. // 生成的 icon.json
  31. ['platform-eleme']

至于生成的 icon.json 有啥用先不管。

2、node build/bin/build-entry.js
构建 src/index.js 这个文件，这个文件可能随着组件的增加删除会经常变动，故用脚本来产生

  1. var Components = require('../../components.json'); // 所有可用组件的映射表（组件名=>组件定义）
  2. var fs = require('fs');
  3. var render = require('json-templater/string'); // 模板渲染工具
  4. var uppercamelcase = require('uppercamelcase'); // 转驼峰 a-bc =>ABc
  5. var path = require('path');
  6. var endOfLine = require('os').EOL;
  8. var OUTPUT_PATH = path.join(__dirname, '../../src/index.js');
  9. var IMPORT_TEMPLATE = 'import {{name}} from \'../packages/{{package}}/index.js\';';
  10. var INSTALL_COMPONENT_TEMPLATE = '  {{name}}';
  11. var MAIN_TEMPLATE = `/* Automatically generated by './build/bin/build-entry.js' */
  13. {{include}}
  14. import locale from 'element-ui/src/locale';
  15. import CollapseTransition from 'element-ui/src/transitions/collapse-transition';
  17. const components = [
  18. {{install}},
  19.   CollapseTransition
  20. ];
  22. const install = function(Vue, opts = {}) {
  23.   locale.use(opts.locale);
  24.   locale.i18n(opts.i18n);
  26.   components.forEach(component => {
  27.     Vue.component(component.name, component);
  28.   });
  30.   Vue.use(Loading.directive);
  32.   Vue.prototype.$ELEMENT = {
  33.     size: opts.size || '',
  34.     zIndex: opts.zIndex || 2000
  35.   };
  37.   Vue.prototype.$loading = Loading.service;
  38.   Vue.prototype.$msgbox = MessageBox;
  39.   Vue.prototype.$alert = MessageBox.alert;
  40.   Vue.prototype.$confirm = MessageBox.confirm;
  41.   Vue.prototype.$prompt = MessageBox.prompt;
  42.   Vue.prototype.$notify = Notification;
  43.   Vue.prototype.$message = Message;
  45. };
  47. /* istanbul ignore if */
  48. if (typeof window !== 'undefined' && window.Vue) {
  49.   install(window.Vue);
  50. }
  52. export default {
  53.   version: '{{version}}',
  54.   locale: locale.use,
  55.   i18n: locale.i18n,
  56.   install,
  57.   CollapseTransition,
  58.   Loading,
  59. {{list}}
  60. };
  61. `;
  63. delete Components.font;
  65. var ComponentNames = Object.keys(Components);
  67. var includeComponentTemplate = [];
  68. var installTemplate = [];
  69. var listTemplate = [];
  71. ComponentNames.forEach(name => {
  72.   var componentName = uppercamelcase(name);
  74.   includeComponentTemplate.push(render(IMPORT_TEMPLATE, {
  75.     name: componentName,
  76.     package: name
  77.   }));
  79.   if (['Loading', 'MessageBox', 'Notification', 'Message'].indexOf(componentName) === -1) {
  80.     installTemplate.push(render(INSTALL_COMPONENT_TEMPLATE, {
  81.       name: componentName,
  82.       component: name
  83.     }));
  84.   }
  86.   if (componentName !== 'Loading') listTemplate.push(`  ${componentName}`);
  87. });
  89. var template = render(MAIN_TEMPLATE, {
  90.   include: includeComponentTemplate.join(endOfLine),
  91.   install: installTemplate.join(',' + endOfLine),
  92.   version: process.env.VERSION || require('../../package.json').version,
  93.   list: listTemplate.join(',' + endOfLine)
  94. });
  96. fs.writeFileSync(OUTPUT_PATH, template);
  97. console.log('[build entry] DONE:', OUTPUT_PATH);

缺点：components.json需要自行维护，不够自动化

3、node build/bin/i18n.js
以 i18n/page.json 作为数据，以 pages/templates 作为模版来生成 pages 目录下的多语言版本。官方网站支持多语言版本就是这么来的

  1. 'use strict';
  3. var fs = require('fs');
  4. var path = require('path');
  5. var langConfig = require('../../examples/i18n/page.json');
  7. langConfig.forEach(lang => {
  8.   try {
  9.     fs.statSync(path.resolve(__dirname, `../../examples/pages/${ lang.lang }`));
  10.   } catch (e) {
  11.     fs.mkdirSync(path.resolve(__dirname, `../../examples/pages/${ lang.lang }`));
  12.   }
  14.   Object.keys(lang.pages).forEach(page => {
  15.     var templatePath = path.resolve(__dirname, `../../examples/pages/template/${ page }.tpl`);
  16.     var outputPath = path.resolve(__dirname, `../../examples/pages/${ lang.lang }/${ page }.vue`);
  17.     var content = fs.readFileSync(templatePath, 'utf8');
  18.     var pairs = lang.pages[page];
  20.     Object.keys(pairs).forEach(key => {
  21.       content = content.replace(new RegExp(`<%=\\s*${ key }\\s*>`, 'g'), pairs[key]);
  22.     });
  24.     fs.writeFileSync(outputPath, content);
  25.   });
  26. });

4、node build/bin/version.js
记录 Element 版本号到examples/version.json，这个需要再官方网站上切换展示

  1. var fs = require('fs');
  2. var path = require('path');
  3. var version = process.env.VERSION || require('../../package.json').version;
  4. var content = { '1.4.13': '1.4', '2.0.11': '2.0', '2.1.0': '2.1', '2.2.2': '2.2', '2.3.9': '2.3', '2.4.11': '2.4', '2.5.4': '2.5', '2.6.3': '2.6', '2.7': '2.7.2' };
  5. if (!content[version]) content[version] = '2.8';
  6. fs.writeFileSync(path.resolve(__dirname, '../../examples/versions.json'), JSON.stringify(content));
  • webpack-dev-server —config build/webpack.demo.js 与 node build/bin/template.js 并行执行
    1、node build/bin/template.js
    监听 examples/pages/template 下文件的变化并运行 npm run i18n 重新生成多语言版本的 pages
  1. const path = require('path');
  2. const templates = path.resolve(process.cwd(), './examples/pages/template');
  4. const chokidar = require('chokidar'); // 专门用于文件监控的库
  5. let watcher = chokidar.watch([templates]);
  7. watcher.on('ready', function() {
  8.   watcher
  9.     .on('change', function() {
  10.       exec('npm run i18n');
  11.     });
  12. });
  14. function exec(cmd) {
  15.   return require('child_process').execSync(cmd).toString().trim();
  16. }

2、build/webpack.demo.js
这个就是正式启动本地开发模式了，内容就不说了

2.2、分析 npm run dist

  • npm run clean && npm run build:file && npm run lint
    同上，略过
  • webpack —config build/webpack.conf.js
    构建入口为src/index.js ; 出口为 lib/index.js 用于打出UMD格式的包，供CDN方式引入
  1. <!-- 引入样式 -->
  2. <link rel="stylesheet" href="https://unpkg.com/element-ui/lib/theme-chalk/index.css">
  3. <!-- 引入组件库 -->
  4. <script src="https://unpkg.com/element-ui/lib/index.js"></script>

这里 index.css 的生成请看 npm run build:theme 的分析

  • npm run build:theme
    1、node build/bin/gen-cssfile
    产生 index.scss / index.css 文件，这个文件引入了所有组件的 scss/css 文件
    2、gulp build —gulpfile packages/theme-chalk/gulpfile.js
    编译 scss 文件为 css 文件，包括各组件的 css 文件和一个总的 css 文件
    3、cp-cli packages/theme-chalk/lib lib/theme-chalk
    复制 packages/theme-chalk/lib 至 lib/theme-chalk
  • webpack —config build/webpack.component.js
    构建入口为 components.json ; 出口为 lib/[name].js 用于将 packages 中的所有组件单独打出一个 js 文件用于做按需加载
  • webpack —config build/webpack.common.js
    构建入口为src/index.js ; 出口为 lib/element-ui.common.js 用于打出commonjs格式的包，用以完全导入方式使用，产生的 element-ui.common.js 也是 package.json 的 main 入口
  • npm run build:utils
    将 src 目录下除 index.js 外的所有文件 Babel 编译到 lib 目录下。算是除了组件库以外，额外提供了一些小工具供开发者使用，如:
  1. import { kebabCase } from 'element-ui/src/utils/util';
  • npm run build:umd
    将 src/locale/lang 下的ES6格式的文件转为UMD格式，放在 lib/umd/locale。用于CDN方式加载。

3、小结&收获

小结

回答下开头的问题：

  • 组件全量引入和按需引入是如何做的？
    如果是 cdn 方式来加载，则只能全量引入。如果是用 webpack 这种工程方式引入，则两种方式都可以，其中按需引入借助了 babel-plugin-component
  1. // .babelrc
  2. {
  3.   "presets": [["es2015", { "modules": false }]],
  4.   "plugins": [
  5.     [
  6.       "component",
  7.       {
  8.         "libraryName": "element-ui",
  9.         "styleLibraryName": "theme-chalk"
  10.       }
  11.     ]
  12.   ]
  13. }
  14. // 上述配置会转换以下代码
  15. import { Button } from 'element-ui';
  16. // 转为
  17. import Button from 'element-ui/lib/button.js'
  18. import Button from 'element-ui/lib/theme-chalk/button.css'
  • 主题是如何实现定制的？
    有两种主要方式：1、如果使用scss，则是通过修改 scss 变量来实现主题定制；2、如果使用css，则手动引入定制好的css文件来替换默认的css文件
  • 组件国际化是如何实现的？
    将组件中的使用的文本抽离出来，然后用各种不同的语言去填充即可实现。难点在于怎样提供多语言版本的文件
  • 怎样支持CDN引入和基于webpack的两种开发模式？
    一套源码打两套格式的包，一种umd格式，一种 commonjs2 格式。
  • 开发组件时，组件MD文档是如何处理的？
    ElementUI 开发了一个 md-loader 来把 .md 文档封装成 .vue 组件，实现了组件文档的渲染

收获

  • postcss.parse 可以将 scss 文件内容处理成 js 对象，再通过 postcss.stringify 转回 scss 文件。放便对scss文件做批处理
  • 可通过 require(‘child_process’).execSync(cmd).toString().trim() 来获取 shell 脚本执行的结果
  • cross-env 设置环境变量可屏蔽 mac 和 window 系统的差异
  • commonjs , commonjs2 区别(一个用 exports导出，一个用module.exports，所以我们平时用的都是commonjs2)
  1. commonjs: exports['MyLibrary'] = entry_return
  2. commonjs2: module.exports = entry_return