jiku-ui/README.md

A Component Library for Vue.js.

> A Vue.js 2.0 UI Toolkit for Web.

# 起步
## 项目概述
1. 此项目名为Heiner，意欲为“海纳百川，有容乃大”
2. 此项目基于element-ui 2.12.0版本改造
3. 此项目版本规范遵循[Semantic Versioning 2.0.0](https://semver.org/)
4. 此项目只维护3个分支（不建议新增其他分支），分别为：master，dev，gl-pages
    - master为核心稳定分支，一般情况下不建议手动操作，通过脚本自动更新即可
    - gl-pages为官网分支（包含所有版本官网的构建产物），一般情况下不建议手动操作，通过脚本自动更新即可
    - dev为开发分支（包含下个版本的最新改动），是MR（merge request）允许的唯一分支
## 项目初始化
```bash
-> git clone git@gitlab.qipeipu.net:btr-ui/heiner.git

-> cd heiner

# 安装依赖
-> npm run bootstrap
```
## 项目结构
- 仓库的组件代码位于 packages 下，每个组件一个文件夹
- docs 目录下是文档站点的代码，本地开发时可以在根目录下运行 npm run dev 开启文档站点
目录结构如下：
```
heiner
├─ build     # 构建
├─ docs      # 文档
├─ packages  # 组件
├─ src       # 工具
├─ test      # 单测
└─ types     # 类型
```

# 开发
## 组件开发
1. 如需新增组件，运行命令：
    ```bash
    -> npm run new 组件名（小写、中横线） 组件中文名
    例: npm run new viewer 相册
    ```
    以上命令运行后，则会生成/更新如下文件（以viewer为例子）：
    ```
    heiner
    |- docs
    |  ├─ markdown
    |  |    ├─ viewer.md            # 组件Markdown文档
    |  |    └─ styles
    |  |         ├─ index.scss      # 文档站点示例样式入口
    |  |         └─ viewer.scss     # 组件示例样式
    |  └─ site
    |       └─ nav.config.json      # 文档站点侧边导航栏
    |- packages
    |  ├─ viewer                    # 组件包
    |  |    ├─ index.js             # 组件入口
    |  |    └─ src
    |  |        └─ main.vue
    |  └─ theme-chalk
    |       └─ src
    |           ├─ index.scss       # chalk主题入口
    |           └─ viewer.scss      # 组件样式
    |- test
    |  └─ unit
    |       └─ specs  
    |           └─ viewer.spec.js   # 组件测试用例
    |- types
    |  ├─ heiner-ui.d.ts            # 组件库声明文件
    |  └─ viewer.d.ts               # 组件声明文件
    └─ components.json              # 组件列表
    ```
2. 组件新增完毕后，可进行开发调试，运行命令：
    ```bash
    -> npm run play
    ```
3. 使用浏览器访问 http://localhost:8085，打开组件开发调试专用页面
4. 在 docs/site/play/index.vue 中直接引入需要开发调试的组件，保存后即会热更新到浏览器界面，简单方便
## 官网编辑与更新
1. 运行命令：
    ```bash
    -> npm run dev
    ```
2. 使用浏览器访问 http://localhost:8085，打开本地官网
3. 在 docs/markdown/*.md 中直接修改需要更新的md文档，保存后即会热更新到浏览器界面，简单方便
    - 注：md文档中示例的样式是在对应的docs/styles/*.scss中添加的
4. 编辑完后，进行本地Git提交（注意[commit消息规范](https://juejin.im/post/5c9832de6fb9a070fb3707ab)）
5. 接着，运行命令：
    ```bash
    -> npm run update
    ```
6. 待本地提示操作成功后，可到GitLab查看[更新进度](https://gitlab.qipeipu.net/btr-ui/heiner/-/jobs)。当Job（pages）的status更新为passed时，即表明线上官网已更新完毕
7. 最后，使用浏览器访问 https://btr-ui.qipeipu.net/heiner，验收线上官网
## 组件库发版
1. 登录npm私服（如果已登录，忽略此步骤），运行命令：
    ```
    -> npm login --registry=http://172.16.16.92:7001/

    Username: (zoujiaqi) zoujiaqi
    Password: (<default hidden>) 
    Email: (this IS public) (zoujiaqi@qipeipu.com) zoujiaqi@qipeipu.com
    Logged in as zoujiaqi on http://172.16.16.92:7001/.
    ```
2. 登录后，即可进行发版，运行命令：
    ```bash
    -> npm run release
    ```
3. 待本地提示操作成功后，可到[npm私服](http://npm.qipeipu.net/package/jiku-ui)查看组件库发布情况。同时，官网的[更新进度](https://gitlab.qipeipu.net/btr-ui/heiner/-/jobs)也可以在GitLab上查看，当Job（pages）的status更新为passed时，即表明线上官网已更新完毕