java-antdv-component UI 组件库

简介

java-antdv-component ui 组件库是一套基于 Vue3，Typescript，Ant Design Vue(3.x) 再次封装的 Vue3 UI 组件库，用于 owms 海外仓系统重构，包含了按钮，下拉选择器，级联选择器，倒计时，日期时间选择器，表单，表格，图标，条形码，二维码，对话框，图片预览等等组件。

为什么开发它

• 为 owms 海外仓系统重构，保证统一不同页面层级的信息架构、视觉表达和交互体验，解决团队成员由于认知不同采用不同组件导致的视觉和操作差异问题。
• 减少冗余，优化性能，极大提高团队的开发效率（35%左右），开发人员只需要专注于业务逻辑，无需考虑基础组件的复用性，扩展性，稳定性等问题。
• 为团队组件库的开发实践积累经验，打下基础，方便团队成员参与组件库的建设。

技术看点

拥抱 Vue3

• 引入 Vue3 新特性 Composition API、Teleport、Emits 等；
• 采用组合式 API Composition 语法重构，结构清晰，功能模块化；
• 组件 emits 事件单独提取，增强代码可读性；
• 使用 Teleport 新特性重构挂载类组件。

构建工具使用 Vite

弃用 webpack，引入下一代前端构建工具 Vite。启动速度由原来 30s 提升到 500ms 左右，将大幅提升开发效率。

全面使用 TypeScipt

使用 TypeScript 作为主要开发语言，在前端应用复杂度不断飙升的大背景下，应对组件不易维护且难于扩展的问题。

兼容性

• 兼容主流的 PC 浏览器，如 Chrome Firefox Safari Edge 等；
• 不支持 IE 浏览器。

整体架构

代码组织方式

组件库的整体架构设计核心就是组织和管理代码，本项目采用单包架构，将所有组件当成一个整体，一起打包发布。单个仓库，单个包，统一维护和管理。

采用单包架构的优点是可以通过相对路径实现组件与组件的引用，公共代码之间的引用，因此也带来一个缺点，组件完全耦合在了一起，必须把它作为一个整体统一发包。就算只改一个组件的一个非常小的功能，都要对整个包发布更新。但在开发层面的便捷性来说，瑕不掩瑜。

功能组成

整个项目包含了组件库，使用文档，工程化构建，本地服务，代码质量检查等功能。

• 组件库，包含一个个组件，如 Form，Table，Modal 等等。
• 使用文档，可以实时运行的文档服务，支持组件的展示，以及附带源码的效果。
• 工程化构建，采用 Vite2.x 版本构建，支持 esm, cjs 等格式的产物。
• 代码质量检查，使用 eslint, stylelint, prettier, commitlint 等工具保证代码质量和风格统一。

项目结构

java-antdv-component
├─ .browserslistrc                       # 兼容浏览器配置
├─ .eslintignore                         # eslint忽略文件
├─ .eslintrc.js                          # eslint
├─ .husky                                # git钩子配置
├─ .lintstagedrc                         # lintstaged配置
├─ .prettierignore                       # prettier忽略
├─ .stylelintignore                      # stylelint忽略
├─ .stylelintrc                          # stylelint配置
├─ babel.config.js                       # babel配置
├─ build                                 # 文档构建配置
│  ├─ loaders                            #
│  │  ├─ ComponentDemoTemplate.vue       # 组件demo样板
│  │  ├─ convert-md-to-demo.js           # markdown转组件demo
│  │  ├─ convert-md-to-doc.js            # markdown转文档页面
│  │  ├─ convert-vue-to-demo.js          # vue转组件demo
│  │  ├─ demo-loader.js                  # demo加载器
│  │  ├─ doc-loader.js                   # 文档加载器
│  │  ├─ md-renderer.js                  # markdown标记转换器
│  │  └─ project-path.js                 #
│  ├─ utils                              #
│  │  ├─ get-demo-by-path.js             # 根据demo格式使用不同加载器加载
│  │  ├─ handle-merge-code.js            # 拼接demo代码
│  │  └─ tsToJs.js                       # ts代码转js
│  └─ vite-plugin-demo.js                # vite demo插件
├─ commitlint.config.js                  # commitlint配置
├─ install-intro.md                      # 安装介绍
├─ jest.config.ts                        # jest配置
├─ npm-version.md                        # npm版本管理介绍
├─ package.json                          #
├─ packages                              # 组件库
│  ├─ antdvStyles.ts                     # 按需引入ant design vue组件样式
│  ├─ api-cascader                       # 远程加载的级联选择器，所有组件结构都是如此
│  │  ├─ demos                           # 组件demo
│  │  │  ├─ basic.demo.vue               #
│  │  │  └─ index.demo-entry.md          #
│  │  ├─ index.ts                        # 组件导出
│  │  └─ src                             # 组件源码
│  │     ├─ ApiCascader.vue              #
│  │     └─ types.ts                     #
│  ├─ components.ts                      # 所有组件导出
│  ├─ composables                        # hooks
│  ├─ config.json                        # 所有组件描述，根据该文件生成文档导航
│  ├─ index.ts                           #
│  ├─ styles                             # 样式
│  └─ utils                              # utils函数库
├─ postcss.config.js                     # postcss配置
├─ prettier.config.js                    # prettier配置
├─ README.md                             # 说明
├─ sftp.json                             # ftp工具，文档打包后自动上传部署
├─ src                                   # 文档服务源码
│  ├─ App.vue                            #
│  ├─ assets                             # 文档静态资源
│  ├─ components                         # 文档公用组件
│  ├─ icons                              # 文档图标
│  ├─ layouts                            # 文档布局
│  ├─ main.ts                            # 文档入口
│  ├─ router.ts                          # 文档路由
│  ├─ styles                             # 文档样式
│  └─ views                              # 文档页面
├─ tests                                 # 测试
├─ tools                                 # 工具
│  ├─ createComponentMode.js             # 创建组件模板
│  ├─ generate-components-dts.js         # 生成组件全局dts文件
│  └─ sample.js                          # 组件源码样板
├─ tsconfig.json                         # typescript配置
├─ typings                               # 全局typescript类型
├─ vite.config.build.ts                  # vite 库模式构建配置
└─ vite.config.ts                        # vite 开发配置

组件库开发与扩展

拉取代码

git clone http://git.eminxing.com/java-web/owms/commoncomponent-pc.git

开启开发服务器

npm run dev

构建开发文档

# 构建成功后将自动通过sftp插件上传至开发服务器
npm run build

构建组件库

npm run build:lib

发布到 npm

前提：注册一个 npm 仓库账号

# 发布之前先更改版本号, 版本号管理采用semver语义化版本号，见npm-version.md
npm version patch
npm login
npm publish

快速创建组件

执行以下命令来快速创建一个组件

npm run add

接着根据提示，输入组件名，组件描述，作者等信息，完成后将在 packages 目录下自动创建基于该组件名的目录。