​ BS组件库开发-使用-维护文档

--

title: 组件库使用文档

date: 2021-03-18 10:58

--

一、简介

boss-lib 是基于 vue+webpack+gulp 的一套将博思各项目中公共组件抽离的解决方案。其开发目的是，以期在之后的项目开发中，公共组件可以以依赖的形式安装，在组件库方可以按照标准维护版本，各终端仙姑根据具体需求选择所需组件版本。

二、组件目录

|-- boss-lib
    |-- .babelrc  --------------------------------------------babel设置，包括模块引入路径匹配更换
    |-- README.md 
    |-- babel.config.js --------------------------------------babels设置
    |-- package.json
    |-- styleguide.config.js ---------------------------------styleguide基础设置
    |-- vue.config.js
    |-- build ------------------------------------------------打包配置
    |   |-- config.js ----------------------------------------配置entry、externals、alias
    |   |-- webpack.common.js --------------------------------合并打包
    |   |-- webpack.component.js -----------------------------分块打包
    |   |-- webpack.conf.js ----------------------------------
    |-- examples --------------------------------------------原src文件
    |   |-- App.vue
    |   |-- main.js
    |   |-- components
    |-- lib --------------------------------------------------打包文件。npm、_npm只需要这个
    |   |-- boss-lib.common.js ------------------------所有项目以commonjs2形式打包到当前文件
    |   |-- Directive ---------指令文件、由npm run build:utils经src文件babel转译后复制到lib中
    |   |   |-- directions.js 
    |   |   |-- index.js
    |   |-- plugins ------------------------------------------同上
    |   |   |-- defaultRenders.js
    |   |   |-- tableDefaultConfig.js
    |   |   |-- vxeTable.js
    |   |-- utils --------------------------------------------同上
    |       |-- common.js
    |   |-- theme-chalk ----------------------经build:style命令，利用gulp将css打包并复制到lib中
    |   |   |-- index.css
    |   |   |-- alifont ----------------------同上
    |-- packages ---------------------------------------------各组件文件
    |   |-- index.js -----------------------------------------引入所有组件，添加install方法
    |   |-- Crumbs -------------------------------------------面包屑组件
    |   |   |-- index.js -------------------------------------声明组件并导出
    |   |   |-- src ------------------------------------------组件内容
    |   |       |-- README.md ------此处添加项目demo，借助vue-styleguide编译，可在文档中对应生成。
    |   |       |-- index.vue 
    |   |       |-- img -------静态文件以相对路径引入，图片超过30k需压缩再放入，小于30k将转为base64
    |   |-- theme-chalk ---------------------------------------全局样式文件
    |       |-- gulpfile.js -----------------------------------打包样式文件默认配置
    |       |-- src -------------------------------------------样式文件入口
    |           |-- index.scss
    |           |-- alifont -----------------------------------font文件单独打包至lib/alifont
    |           |-- common ------------------------------------cmomon文件将添加至index.css中
    |-- src --------------组件开发时，以boss/src/util引入对应文件，经打包后将自动转为boss/lib/util
    |   |-- Directive
    |   |-- plugins
    |   |-- utils
    |-- styleguide  
        |-- README.md --------------------------------------------styleguide使用文档
        |-- global.requires.js ----Styleguidist不加载main.js文件。为了在demo中使用组件，当在此文件																		中声明引用
        |-- theme.js --------------------------------------------styleguide主题配置

三、新增组件步骤

1. 新建Button文件夹至packages

   |-- Button
       |-- index.js
       |-- src
           |-- README.md
           |-- index.vue
           |-- img    -------------------------------------------根据需要添加  

2. 新建index.js

   import BsButton from "./src/index.vue";
   BsButton.install = function(Vue) {
     Vue.component(BsButton.name, BsButton);
   };
   export default BsButton;

3. 新建src/index.vue文件，根据具体情况添加注释。 注释具体规则在附录或组件库styleguide/README.md中

   <template>
     <div class="bs-button" :class="buttonClass">
         <!--------- 此处为插槽注释 --------->
         <el-button></el-button>	
         <!-- @slot Use this slot header -->
         <slot name="header"><h1>{{ title }}</h1></slot>
       </div>
     </div>
   </template>
   
   <script>
   /**
    * 按钮组件  -- Author:Titans        --------------此处为组件基本信息注释
    */
   export default {
     name: 'BsButton',
     props: {
       /**
        * butonClass
        * ...更多注释
        */
       buttonClass: {
         type: String,
         default: ''
       }
   	},
     methods: {
       onBtnClick(index) {
         /**
          * 某某点击事件
          * @property {object} crumbsdatain 数据注释
          * @property {number} index 数据注释
          */
         this.$emit('onCrumbsClick', {k:'fuck'}, index)
       }
     }
   }
   </script>
   <style lang="scss">
   </style>
   

4. 新建README.md文件，vue-styleguide会自动将其编译，转为demo样例。

   ​```vue 
     new Vue({
       template: `
         <div>
           <BsButton /> // 此处组件名当与组件名一致。
         </div>
       `
     })
   ​```

5. 添加当前文件到packages/index.js文件中

   // * 如果是一般组件，则按规则添加到components数组，经map注册。
   components.map((component) => Vue.component(component.name, component));
   // * 若为功能组件，则在引入之后，可挂载到Vue原型之上。   
   Vue.prototype.$LoadingMark = LoadingMark

6. 资源引入

   • 第三方插件引入：组件内部引入，并在build/comfig -- externals 添加。

     externals = [Object.assign({
       vue: 'vue',
       'element-ui': 'element-ui',
       'file-saver': 'file-saver',
       'vue-splitpane': 'vue-splitpane'
     }, externals), nodeExternals()];

   • 组件库utils引入：

     import { extend } from 'boss-lib/src/utils/common.js'

     打包后将将自动转为"boss-lib/lib/utils/common.js"

   • 静态资源引入：img文件放入./src/文件底下。 图片超过30k，需压缩替换，未超过30k将自动转为base64。

四、 $http与vuex的处理

因项目需求特殊性，无法将组件库纯粹抽离成功能性组件。组件中需添加对vuex、基于axios封装&http的支持，故而对组件做了如下处理：

• 组件只支持全局引入。 且在项目中引入使用之前，需在Vue原型上添加$http方法。

  // 
  import lib from 'boss-lib'
  import 'boss-lib/lib/theme-chalk/index.css'
  import 'boss-lib/lib/theme-chalk/alifont/iconfont.css'
  // 实际项目中$http已封装好，无需多做处理
  const promise = function () {
    return new Promise((res) => {
      console.log('调用接口')
      res('1')
    })
  }
  // 模拟接口 防止报错
  Vue.prototype.$http = {
    get: promise,
    post: promise,
    put: promise,
    del: promise,
    postStringify: promise,
    DownLoadToFile: promise,
    downLoad: promise,
    DownLoadToExcel: promise,
    httpGlobalGatewayAgent: promise
  }
  Vue.use(lib).

  如此，在执行Vue.use(lib)之后，boss-lib组件库可以拿到绑定在原型上的$http方法。

  vuex同理，可通过原型上的$store方法，进行vuex的获取与写入。

  也正因此，组件不再支持分包加载，webpack.component.js文件废弃，只做参考学习之用。

  另，vue-styleguide不加载main.js文件，所有demo中依赖组件、样式、uitls都需要global.requires.js声明。故对同样问题的处理方案也是如此。在global.requires.js添加对应内容。

五、打包发布流程规范

1. 发布前更新版本号，规则如下：

   版本号一般格式为 x.y.z，解释为主版本.次要版本.补丁版本。一般更新原则为：
   *	如果只是修复 bug，需要更新 z 位。
   * 如果是新增了功能，但是向下兼容，需要更新 y 位。
   * 如果有大变动，向下不兼容，需要更新 x 位。

2. 更新根目录README。 因verdaccio无tag功能，发布信息需要手动在readme维护。

   feat： 新增 feature
   fix: 修复 bug
   docs: 仅仅修改了文档，比如 README, CHANGELOG, CONTRIBUTE等等
   style: 仅仅修改了空格、格式缩进、逗号等等，不改变代码逻辑
   refactor: 代码重构，没有加新功能或者修复 bug
   perf: 优化相关，比如提升性能、体验
   test: 测试用例，包括单元测试、集成测试等
   chore: 改变构建流程、或者增加依赖库、工具等
   revert: 回滚到上一个版本

3. 执行打包命令

   npm run dist
   // "dist": "npm run clean && npm run common && npm run build:utils && npm run build:style"
   * npm run clean:  清除既有打包内容
   * npm run common: 所有组件打包至lib/boss-lib.common.js
   * npm run build:utils: 编译所有src下所有工具文件，并复制粘贴到lib下。通过.babelrc文件module-resolver的alias设置，所有组件对boss-lib/src的引用将自动转为boss-lib/lib。
   * npm run build:style: 打包所有公共样式文件。   webpack中配置了extract: false，所有组件内的css都将强制内联。

4. npm切入私源，执行npm publish

五、账号备注

verdaccio 账号
qingyu 123456

npm
boss-npm
boss243267674

六、更新日志

• 版本1.0.1。发版人：轻语

  refactor: 重整项目结构。

• 版本1.0.0。 发版人：轻语

  feat: 新增Button组件