npm package: @pitrix/lego-ui
Description: QingCloud UI Component
Author: QingCloud
Latest version: 0.3.6

# Lego-UI

> React & CSS UI Framework.

<br/>

## 文档

- [设计规范](http://192.168.14.44/general/)
- [组件](http://192.168.14.44/components/)
- [更新日志](http://192.168.14.44/changelog/)

<br/>

## 安装

```bash
npm install @pitrix/lego-ui --save
```

<br/>

## 使用示例

```jsx
import { LocaleProvider, Button } from '@pitrix/lego-ui';
import { Locales } from './locales';

const App = () => (
  <LocaleProvider locales={locales}>
    <Button>Button</Button>
  </LocaleProvider>
);

ReactDOM.render(<App />, mountNode);
```

> lego-ui 部分组件有使用 `locale`, `LocaleProvider` 默认会加载 lego-ui 的本地化文件，你也可以在你的项目中使用，只需要自定你的`locales`, 关于国际化请查看 [LocaleProvider](http://192.168.5.217/components/locale)。

<br/>

## 引入样式

如果没有定制需求，可以直接引入 css 样式文件：

<br/>

```jsx
import '@pitrix/lego-ui/lib/scss/lego-ui.min.css';
```

<br/>

或者引入 scss 样式文件：

<br/>

```jsx
import '@pitrix/lego-ui/lib/scss/index.scss';
```

这样可以直接使用 lego-ui 的默认主题样式。

<br/>

## 定制主题

lego-ui 设计规范上支持一定程度的样式定制，以满足不同产品的多样化视觉需求，包括但不限于主色、圆角、边框和部分组件的视觉定制。

<br/>

#### 样式变量

<br/>
lego-ui 的样式使用 Sass 作为预处理器，一定程度上依赖于 CSS 库 Bulma，并定义了一系列全局/组件的样式变量，你可以根据需求进行相应调整。所有的主题变量可以在 `/src/scss/themes/default.scss` 下查看。

- [默认样式变量](https://git.internal.yunify.com/elvis/lego-ui/blob/dev/src/scss/themes/default.scss)

<br/>

#### 定制方式

<br/>
用 scss 文件进行变量覆盖。

建立一个单独的 scss 文件如下，然后再引入这个文件：

<br/>

```scss
// 引入默认主题
@import '~@pitrix/lego-ui/lib/scss/themes/default';

// 引入 SVG 图标组件的样式
@import '~@pitrix/lego-ui/lib/scss/base/icon';

// 在这里定义你要覆盖的变量
// $primary: blue;
// $button-color: #ccc;

// 引入核心的 Bulma 样式与组件样式
@import '~@pitrix/lego-ui/lib/scss/core.scss';
```

- 注意：这种方式已经载入了所有组件的样式。

<br/>

## 目录结构

```bash
|-- build/            _____________________ # 构建脚本
|-- config/           _____________________ # 构建环境配置
|-- dist/             _____________________ # 文档站点构建输出目录
|-- lib/              _____________________ # npm 发布代码目录
|-- mock/             _____________________ # mock 脚本
|-- site/             _____________________ # 文档站点
|   |-- assets/       _____________________ # 静态资源文件
|   |-- layout/       _____________________ # 页面布局
|   |-- pages/        _____________________ # 文档内容
|   |-- routes/       _____________________ # 站点路由
|   |-- scss/         _____________________ # 样式文件
|-- src/              _____________________ # 源码
|   |-- assets/       _____________________ # 静态资源文件
|   |-- components/   _____________________ # 组件源码
|   |-- locales/      _____________________ # 本地化文件
|   |-- scss/         _____________________ # 样式
|   `-- utils/        _____________________ # 工具类
|-- static/           _____________________ # 静态资源
```

<br/>

## 脚本说明

<br/>

```bash
    # 运行本地开发服务，默认端口 3000
    npm run dev

    # 构建文档站点
    npm run build

    # 代码检查
    npm run lint

    # js，jsx， markdown 文件代码检查
    npm run eslint

    # scss 文件代码检查
    npm run stylelint

    # 代码格式化
    npm run formatter

    # 构建 npm 发布需要的代码
    npm run build:lib

    # 单独构建 scss 文件
    npm run build:sass

    # 单独构建 icon
    npm run build:icon

    # 构建 版本的 badge 图标
    npm run build:badge

    # 发布新版
    npm run release

```

<br/>

## 关于图标库

<br/>
图标库的路径在 `/src/assets/icons`

如需要向图标库中添加图标

- 复制图标到对应的目录，例如 `/src/assets/icons/object`
- 构建 `npm run build:icon`;
- 将新图标添加到 `site/pages/docs/components/icon.md`

**⚠️ 注意**：svg 图片大小、颜色(#324558)。

<br/>

## git commit 提交规范

<br/>
- 默认分支为 `dev`
- 开发新组件/功能/fix bug 需要新建分支上进行，然后提交 mr 到 dev 分支；
- 发布新版本将 dev 合并到 master 分支并加上当前版本的 tag；

<br/>

Commit Message 需要遵循以下格式：

> type(scope?): subject #scope is optional

<br/>

其中：

- type: 用于定义这次提交的类型，可选值包括：feat / fix / perf / refactor / revert / build / ci / chore / style / test / docs。
- scope: 用于定义这次提交的改动范围关键字，小写，可选。
- subject: 用于描述这次提交的改动内容，建议统一中文。

提交的过程中会做 eslint 检查，不通过则不能提交。

<br/>

## 编码规范

<br/>
- 默认使用 Airbnb 的 ESLint 规则。 项目中已经配置好了 eslint 和 stylelint，尽量不要调整规则；
- 尽量不要再代码中使用 eslint-disable 和 eslint-disable-line 等忽略规则；
- 给你的编辑器装上 editorconfig，eslint，prettier 等插件，会减少不必要的麻烦，推荐使用 vscode，因为项目中有 `.vscode` 的项目配置， 保证大家有统一的代码格式；

<br/>

## 版本发布流程

<br/>

**标准版本:**

<br/>

```bash
npm run release
qnpm publish
```

构建发布到仓库中所需的文件，standard-version 会生成 changelog，打上 tag 并提交 commit;

你也可以指定版本

```bash
qnpm run release -- --release-as 1.1.0
```

<br/>

**预发布版本：**

<br/>

预发布版本不希望生成 changelog， 所以可以在 package.json 中 手动调整版本号，例如 0.1.5-xx，发布时需要指定 tag 为 next。

```bash
qnpm publish --tag=next
```

<br/>

## 文档站点

<br/>
如有更新，需要更新文档站点，可以在 Jenkins 进行构建

[http://172.16.60.3:8080/view/f2e/job/lego-ui/](http://172.16.60.3:8080/view/f2e/job/lego-ui/)

<br/>

## 关于 CHANGELOG

<br/>
- 文档站的 CHANGELOG 内容和 CHANGELOG.md 是使用 [standard-version](https://github.com/conventional-changelog/standard-version) 自动生成；
- 当 Commit Message 中 `type` 为 feat / fix / perf 等 commit 会添加到发布时生成的 CHANGELOG 中，其它的 `type` 类型则忽略；