开发向导

快速上手

1. 克隆代码到本地

git clone [email protected]:cloud_pt/platform/components/hq-ui.git

2. 安装 pnpm 包管理工具

注意 node 版本切换到 v14.20.0

# 安装pnpm
npm install -g [email protected] --registory=https://registry.npm.taobao.org

# 设置 `pnpm-store` 和 `pnpm-cache` 目录，注意：要和项目代码放在同一个磁盘
pnpm config set store-dir "D:/.pnpm-store"
pnpm config set cache-dir "D:/.pnpm-cache"

3. 安装代码依赖

进入代码目录，使用 pnpm 安装依赖并初始化项目

pnpm install

4. 打开组件调试页面

执行下面命令可打开调试页面，可用来测试组件，编写文档和例子。

pnpm doc:dev

组件库代码结构

主要关注两个目录：src 和 docs 。组件的编写、调试、文档都是基于这两个目录进行。

|-- hqui
    |-- docs                        // 文档目录
    |   |-- README.md
    |   |-- .vuepress               // vuepress 配置目录
    |   |   |-- config.js           // vuepress 配置文件，在此配置文档路由
    |   |   |-- enhanceApp.js       // vuepress 扩展配置，在此扩展 vuepress 功能
    |   |   |-- public              // 静态文件存放目录
    |   |-- component               // 组件文档存放目录
    |   |   |-- dialog.md
    |   |   |-- ...
    |   |-- developer               // 组件开发文档存放目录
    |   |   |-- README.md
    |   |-- examples                // 组件示例存放目录，用于调试组件，和在文档中引用
    |   |   |-- dialog
    |   |       |-- base.vue
    |   |       |-- ...
    |   |-- routes.js               // 组件路由配置文件
    |
    |-- src                         // 组件源码目录
        |-- index.js                // 组件源码入口文件，在此添加组件引用
        |-- mixins                  // 组件全局 mixins 存放目录
        |   |-- emitter.js
        |-- packages                // 组件源码目录
        |   |-- dialog
        |   |   |-- Dialog.vue
        |   |   |-- index.js
        |   |-- ...
        |-- styles                  // 组件样式目录
        |   |-- dialog.less
        |   |-- index.less
        |   |-- common              // 组件公共样式存放目录
        |   |   |-- var.less
        |   |-- mixins              // 组件公共样式 mixins 存放目录
        |       |-- mixins.less
        |-- utils                   // 组件工具类存放目录
            |-- assist.js

如何添加新组件？

1. 创建组件文件，比如要创建一个 dialog 组件，需要创建 dialog Dialog.vue index.js dialog.less 文件

|-- src
    |-- index.js
    |-- packages
    |   |-- dialog          // 需要创建的目录
    |   |   |-- Dialog.vue  // 需要创建的文件
    |   |   |-- index.js    // 需要创建的文件
    |   |-- ...
    |-- styles
    |   |-- dialog.less     // 需要创建的文件
    |   |-- index.less

/src/dialog/Dialog.vue

注意：组件名称命名空间以 Hq 开头，比如dialog组件名称为 HqDialog

<template>
  <div class="hq-dialog">
  </div>
</template>

<script>
export default {
  name: 'HqDialog',
  props: {},
  data() {
    return {}
  },
  methods: {},
}
</script>

src/dialog/index.js

import Dialog from './Dialog.vue'

Dialog.install = function (Vue) {
    Vue.component(Dialog.name, Dialog)
}

export default Dialog

src/styles/dialog.less

注意：组件样式以命名空间 hq 开头，比如dialog组件名称为 hq-dialog

@charset "utf-8";
@import './common/var.less';
@import './mixins/mixins.less';

.hq-dialog {
}

2. 导出组件 /src/index.js

import Dialog from './packages/dialog'

const components = [
    Dialog, // 在此导出组件
]

const install = function (Vue, options = {}) {
    components.forEach((component) => {
        Vue.use(component)
    })
}

export default {install}

3. 导出样式 /src/index.js

@charset "utf-8";

@import './dialog.less'; // 在此导出样式

4. 注册组件 /build/components.json 此处注册组件后才会被打打包到lib目录

{
  "dialog": "packages/dialog/index.js",
}

如何添加新组件的文档？

1. 创建组件 markdown 文件，比如要创建一个 dialog 组件

|-- hqui
    |-- docs
    |   |-- .vuepress
    |   |   |-- config.js
    |   |-- component
    |   |   |-- dialog.md           // 需要创建的文件
    |   |-- routes.js

/docs/component/dialog.md

---
title: Dialog
---

# 弹出框

## 基本用法

Dialog 弹出一个对话框，显示一条消息，使用内置确认取消按钮。

<example file="dialog/base" />

## API

## 属性

| 参数   | 说明     | 类型     | 默认值 |
| ------ | -------- | -------- | ------ |
| `name` | 图标名称 | _string_ | `-`    |

## 事件

| 事件名  | 说明           | 参数           |
| ------- | -------------- | -------------- |
| `click` | 点击图标时触发 | `event: Event` |

## 插槽

| 插槽名  | 说明           | 参数           |
| ------- | -------------- | -------------- |
| `click` | 点击图标时触发 | `event: Event` |

2. 添加文件对应的路由

/docs/routes.js

module.exports = {
    sidebar: {
        '/': [
            {
                title: '组件',
                collapsable: false,
                children: [
                    '/component/dialog',
                    // others
                ],
            },
        ],
    },
}

代码规范

代码规范已通过 eslint stylelint 进行配置，不符合规范的代码 git 会阻止提交， 为了更好的开发需安装 ESLint Prettier - Code formatter Stylelint 插件，安装后编写代码，如果有不符合规范的代码，编辑器会有错误提示并且保存时会自动格式化代码。

组件日志维护

组件开发和修改后的功能，需要通过以下命令添加到 CHANGELOG.md 中，按照提示进行操作，操作完后会生成临时文件，最终发版时可生成统一的 CHANGELOG.md 文件。

pnpm ca

1. 选版本

2. 填写更新内容

组件打包 & 发版

1. 更新版本 & CHANGELOG.md

pnpm cv

2. 打包 & 发布到公司私有仓库

pnpm release

3. 查看发布结果