# 使用指南

# 安装

使用包管理器安装:

# 使用 yarn
yarn add @dcbfe/ui

# 或者,使用 npm
npm i @dcbfe/ui

# 或者,使用 pnpm
pnpm add @dcbfe/ui

若在国内,可使用 tbify (opens new window) 加速。

# 使用

在项目入口页(一般是 src/main.js)按需引入项目中要使用到的所有组件并注册即可。

由于 @dcbfe/ui 本身支持摇树优化,因此用这种方式只会引入你指定的组件,不会引入其他组件增加构建产物大小。

import Vue from 'vue';

import { Button, Icon } from '@dcbfe/ui';
Vue.use(Button);
Vue.use(Icon);

你可使用下面的工具选择项目中要用到的组件生成代码:

引入组件后在项目中即可使用:

确定
<template>
  <d-button @click="handleClick">确定</d-button>
  
</template>

<script>
  export default {
    methods: {
      handleClick() {
        alert('hello');
      },
    },
  };
</script>

# 参与贡献

前置要求

# 1、Fork 仓库

打开 dcb-fe/dcb-ui (opens new window),点击右上角 Fork 按钮:

# 2、克隆仓库

提示

若你是首次克隆来自 GitHub 的仓库,你需要在 GitHub 添加你的 SSH 密钥 (opens new window)

去到你 Fork 后的仓库,复制仓库的 SSH 地址:

将仓库克隆到你的电脑上:

# 3、创建分支

在项目中以 master 为基础创建分支,分支名最好以 类型/作用域 命名,如 feat/buttonfix/buttonfeat/iconfix/icon 等等。

# 4、初始化项目

切换去创建好的分支,在控制台输入 yarn 开始安装依赖:

依赖安装完成后项目就初始化完毕了。

# 5、开始开发

点击命令 dev 启动文档:

然后在浏览器打开文档,并切换到组件页:

# 6、添加组件

点击命令 new-component 选择组件分类、输入组件名、输入组件中文名后回车:

添加后的组件相关文件在 src/components 目录下。

# 7、编写组件

组件样式必须同组件设计(蓝湖 (opens new window))一致,组件 API (属性、插槽、事件等)可参考 Vant (opens new window) 设计。

组件编写与日常开发无异,不过为了方便行事,做一些约定:

  • 若组件有属性、插槽、事件,必须在组件定义时显式声明(目的在于方便组件 API 文档生成)。
  • 组件样式采用 CSS Modules 设计,在组件模板中以 _.类名 引用具体类名(目的在于方便样式书写)。

以上约定的具体示例请参考 src/components/button/button.vue

# 8、编写文档

组件文档位于组件同级目录下的同名 .md 文件中。

组件文档的具体示例请参考 src/components/button/button.md

# 9、测试组件

组件测试逻辑位于组件同级目录下的同名 .test.js 文件中。

测试的目的就是让开发者敢加新功能(既有测试可告诉你这个新功能会不会产生 bug),让使用者敢采用(完善的测试说明这个东西基本没有什么大 bug)。

总体基于 Jest (opens new window)Vue Test Utils (opens new window)

  • 逻辑:采用单元测试。
  • 视图:采用快照测试。
  • 样式:不测试,由 UI 进行验收。

组件测试的具体示例请参考 src/components/button/button.test.js

# 10、Git 提交

提示

由于开发工作不可能一蹴而就,可能你在提交时,dcb-fe/dcb-ui (opens new window) 仓库(下称上游仓库)的代码已经发生了变化,但你 Fork 过来的代码是不会自动同步的。

因此,在每次提交前,必须手动更新下上游仓库的代码以保证代码同步。

首先,配置上游库(该操作仅需执行一次):

git remote add upstream https://github.com/dcb-fe/dcb-ui.git

然后,在每次提交前这样操作:

  • 首先,切换到 master 分支更新上游代码:

    git checkout master
    git pull --rebase upstream master
    
  • 接着,再切换到我们创建的 feat/xxxfix/xxx 等分支,同步代码:

    git checkout feat/xxx
    git rebase master
    

以上,我们的 master 分支仅是作为代码同步的作用,真正的开发在 feat/xxxfix/xxx 等分支进行。

上述步骤略显繁复但有迹可循,因此我们准备了个脚本让你可以一键执行以上操作,点击 NPM SCRIPTS 下的 rebase 即可:

Git 提交前会对代码进行如下检查,有一项不通过都会被阻止:

  • 代码质量检查(通过 ESLint);

  • 文件命名检查(通过 lslint):

    src 目录下的所有子目录、文件遵循下划线命名风格。举例:

    button
    list_item
    __demo__
    
  • Git 提交信息格式检查(通过 commitlint):

    遵循 约定式提交 (opens new window) 规范。举例:

    # 新增特性
    feat: 新增 Button 组件
    
    # 解决 bug
    fix(Button): 点击应该触发 click 事件
    
    # 文档
    docs(Button): 完善 size 属性的描述
    
    # 杂项
    chore: 清理无用代码
    

若你的提交被阻止,请打开 Git 输出查看具体错误并改正后再次提交:

# 11、请求合并

将代码提交后,可到 GitHub 发起合并请求:

接着填写请求标题、请求内容,点击 Create pull request

如果你的合并请求 CI 运行不通过,或者存在其他问题,可能会要求你修改后再提交。

上次更新时间: 2/17/2023, 8:18:51 AM