哈啰电动车Taro多端组件库实践

原创范翔宇哈啰技术

背景

随着小程序业务的不断迭代，组件越来越多，导致组件规划不清晰、复用率较低、组件重复和代码混乱，以及还有其他如UI交互一致性和提升效率等需求。

对于组件库来说，实现功能重要，而清晰的文档则更加重要，不然因为团队沟通协调成本高，还是会造成各自为战的情况，不能很好的解决组件重复和代码混乱的问题。

抽离封装电动车Taro组件库以及组件库在线演示文档解决上述问题。

方案选择

在文档这一块，PC和H5都有比较成熟的方案框架，如dumi、VitePress等，但Taro这一块还没有成熟的方案框架，即使taro官方提供的taro-ui，组件也不够丰富，而且说明和示例不对应，增加了使用者的学习成本。

所以我们选择自己手动搭建组件库。

手动搭建还有一个优势，像dumi这种框架虽然成熟，但整体很重，里面封装了过多的功能，而且大部分代码是黑盒的。对于大多数团队，只需要使用其部分核心功能，然而做减法是困难且容易出错的。框架代码的黑盒也导致后续维护困难。而手动搭建虽然一开始工作比较多，但是后续维护非常容易。

主要模块技术栈

对于一套组件库，主要模块包括组件、文档、示例三大部分：

组件：
es模块输出和按需加载是必须，rollup是最佳选择，组件编写方面，和业务项目保持一致，使用React，组件更适合使用hooks语法，然后ts，less这种就是常规项。

示例：
这里是Taro组件库和常规组件库最大的区别，文档是运行在浏览器环境里的，所以想要组件demo可以展示，则需要使用Taro框架的打包h5功能。所以单独起一个项目用来跑demo代码，使用Taro React。至于怎么把文档里的代码引入到demo项目运行，则是使用webpack-chain自定义md文件的loader，自己写一个loader去实现。

文档：
文档就是个静态页面，构建工具就选择vite，配置简单，编译速度快。markdown内容部分，使用react-markdown等插件渲染，根据路由读取不同文件即可。右侧预览部分使用iframe加载demo项目。

目录结构

├─config│   ├─vite // vite配置│   └─rollup // rollup配置├─dist // doc打包产物├─docs-dist // 文档打包产物├─packages│   ├─demo // 组件Taro demo项目│   ├─doc // api文档项目│   └─ui // 组件库├─tests├─index.html // doc入口文件└─package.json

开发dev流程&路由关系

以增加一个标签组件tag为例：

在ui/components下新增tag文件夹，组件入口tag/index.tsx，文档文件tag/README.md，组件打包产物 /dist/tag/index.js；
doc项目增加对应的路由 /tag，路由渲染菜单到左侧，当路由切换到 /tag 时，通过路由组合出import url引入 tag/README.md 文件，通过vite框架的 ?raw引入方式，读取md文件中的内容为字符串传递给 react-markdown 组件，渲染成中间的文档页面；

demo项目独立运行，打包成h5页面，通过iframe嵌入到右侧，先增加与组件路由对应的页面文件，当doc的路由变化时，iframe的路由也同步变化，demo切换到对应的路由页面，然后就可以读取对应的 tag/README.md；

demo项目通过自定义markdwon-loader读取 tag/README.md 文件中写的示例代码，对于组件的引用，通过配置webpack路径别名的方式，把@hb/rent-taro-components 指向组件产物 /dist/tag/index.js；

demo项目通过自定义markdwon-loader 把当前文档中全部示例代码组合成一个可运行页面输出，即可实时预览到全部示例代码的运行。

这套架构的优点

文档和demo在一个md文件输出，维护方便且灵活
多个demo代码单独编写，互不影响，清晰简洁
右侧demo项目独立，如有需要，可单独发布demo小程序
各模块功能清晰无黑盒，后续维护容易

各模块说明

doc

doc目录结构

├─src│   ├─components│   │   ├─markdown-render // md文件渲染组件│   │   └─... // 其他布局组件│   ├─guides // 指南文档│   ├─router│   │   ├─comp-doc.ts // 组件路由│   │   ├─guide-doc.ts // 指南路由│   │   └─index.ts // 统一导出│   ├─app.less│   └─App.tsx // 主页面└─main.tsx // 入口文件

router

comp-doc.ts:

import Button from '@ui/button/README.md?raw';import Tag from '@ui/tag/README.md?raw';
const compRoutes = [  {    name: '基础组件',    path: '/basic',    children: [      {        name: '按钮',        path: '/button',        component: Button,      },      {        name: '标签',        path: '/tag',        component: Tag,      },    ],  },];
export default compRoutes;

demo

demo目录结构

除了增加了一个自定义loader，其他文件结构和标准Taro项目完全一致。

├─config│   ├─dev.js│   ├─index.js // Taro webpack配置│   ├─markdownloader.js // 自定义md文件loader│   └─prod.js├─src│   ├─pages│   │   └─basic // 文件夹路径与doc路由保持一致│   │       ├─button│   │       │   ├─index.config.ts│   │       │   └─index.tsx│   │       └─tag│   ├─app.config.ts // 路由配置│   ├─app.less│   ├─app.ts│   └─index.html└─package.json

route&核心代码

app.config.ts:
除了 /index 部分，路由与doc路由一一对应。

export default {  pages: [    'pages/basic/button/index', // pages和index之间的部分对应doc路由    'pages/basic/tag/index'  ],  ...}

pages/basic/button/index.tsx：
只需要把 md文件当做组件引入并 export即可，md 经 markdown-loader 解析后就是一个可运行组件。

// 直接引入组件库中README.md作为demo组件，代码解析在自定义loader中完成import Demo from '@components/button/README.md';
export default Demo;

config/index.js:
通过 webpackChain 自定义loader。

const config = {  h5: {    // ...    webpackChain (chain, webpack) {      chain.merge({        module: {          rule: {            mdLoader: {              test: /\.md$/,              use: [                {                  loader: 'babel-loader',                  options: {}                },                {                  // 引入自定义loader                  loader: `${path.join(__dirname, './markdownLoader.js')}`,                  options: {}                },              ]            }          }        }      })    }    // ...  }}

ts文件配置

通过rollup-plugin-typescript2配置对应的config文件。

import RollupTypescript from 'rollup-plugin-typescript2';// ...plugins: [  // ...  RollupTypescript({    tsconfig: resolveFile('config/tsconfig.rollup.json'),  }),]

按需加载

多入口打包
通过rollup-plugin-postcss抽离样式文件
通过rollup-plugin-copy直接移动less文件到dist（因为对于业务项目，不需要打包成css）

import RollupCopy from 'rollup-plugin-copy';import RollupPostCss from 'rollup-plugin-postcss';
const inputD = {};compFiles.forEach((item) => {  const val = item.replace(cwd, '').replace('/packages/ui/src/components/', '').replace('/index.tsx', '');  inputD[`${val}`] = item;});
const config = {  input: inputD,  plugins: [    RollupPostCss({      use: [        [          'less',          {            javascriptEnabled: true,          },        ],      ],      extract: 'index.less',      extensions: ['.css', '.less'],      makeAbsoluteExternalsRelative: false,    }),    RollupCopy({      verbose: true,      targets: [{        src: resolveFile('/packages/ui/src/components/*/*.less'),        dest: resolveFile('/dist/styles'),      }],    }),  ]}

The End

如果你觉得这篇内容对你挺有启发，请你轻轻点下小手指，帮我两个小忙呗：

1、点亮「在看」，让更多的人看到这篇满满干货的内容；

2、关注公众号「哈啰技术」，可第一时间收到最新技术推文。

如果喜欢就点个👍喔，有您的喜欢⛽，我们会更有动力输出有价值的技术分享滴。

继续滑动看下一个