CodingUIKit

使用

1. 全局导入 CSS 样式

从 JS 中导入:

import 'coding-ui-kit';

或从 SCSS 中导入:

@import '～coding-ui-kit';

在使用 CSS Module 的 SCSS 中导入：

:global {
    @import '~coding-ui-kit';
}

2. 按需导入组件

为了做到 minimum import，要求必须逐个 import，不支持 import { aComponent, bComponent } from 'coding-ui-kit'; 的方式

import Pagination from 'coding-ui-kit/pagination';
import IconTasks from 'coding-ui-kit/icon/tasks';

使用文档

请连接 Coding VPN 并打开：http://uikit.coding.test

组件开发

目录

components
├── _util                                    // 通用工具类
│   ├── createChainedFunction.js
│   └── splitObject.js
├── avatar                                   // 组件目录
│   ├── demo                                 // 示例
│   │   ├── shape.md                         // 示例中必须包含一个代码部分
│   │   └── size.md
│   ├── index.jsx                            // 组件入口文件，必须存在
│   ├── index.zh-CN.md                       // 文档入口文件，必须存在
│   ├── style                                // 样式文件
│   │   ├── index.scss                       // 样式需要引用全局变量：@import '../../style/index';
│   │   └── mixin.scss
│   └── tests                                // 测试
│       ├── __snapshots__                    // jest snapshot 文件
│       └── avatar.spec.js
└── style                                    // 公用样式
    ├── core                                 // 全局通用样式，例如：clearfix, ellipsis 之类
    │   ├── animation.scss
    │   ├── common.scss
    │   └── index.scss
    ├── functions                            // sass function
    │   ├── color.scss
    │   └── index.scss
    ├── index.scss                           // 公用样式入口文件
    ├── mixins                               // sass mixin
    │   ├── clearfix.scss
    │   ├── index.scss
    │   ├── opacity.scss
    │   └── size.scss
    └── themes                               // 公用变量定义
        └── default.scss

步骤

1. 创建如下目录

   components/new-component                     // 目录名称多个单词 `-` 隔开
   ├── demo
   │   └── basic.md                             // 示例文件
   ├── index.jsx                                // 需要 export default NewComponent;
   ├── index.zh-CN.md
   ├── style
   │   └── index.scss                           // 样式文件
   └── tests
       └── avatar.spec.js                       // 测试文件
   
   

2. index.zh-CN.md 基本格式

   ---
   category: Components
   chinese: 新组件
   type: Form Controls
   english: NewComponent
   ---
   
   ## API
   
   ### NewComponent
   
   | 参数      | 说明             | 类型      | 默认值  |
   |----------|------------------|----------|--------|
   | x | <说明> | Boolean  | false |
   | onClick | <说明> | Function(e: Event)  | - |
   
   

   最上面的元信息中， type 类型包含：Basic，Form Controls，Views，Navigation，Other，category 保持 Components 不变。

3. demo/basic.demo 基本格式

   ---
   order: 1
   title:
   zh-CN: 基本使用
   en-US: Basic
   ---
   
   ````jsx
   import NewComponent from 'coding-ui-kit/new-component';
   
   ReactDOM.render(
       <div style={{ margin: '10px 0' }}>
           <NewComponent />
       </div>,
       mountNode
   );
   
   ````
   

   其中 order 表示 demo 排列顺序，从 0 开始计数；title 分为中文和英文两个版本，都需要填写。

   代码部分将直接在文档页面渲染出该组件，所以可以利用 demo 示例进行组件开发的 Debug。

4. 组件基本格式

   • 样式

     @import '../../style/index';
      
     $new-component-height: 30px;
      
     .cuk-new-component {
         height: $new-component-height;
         line-height: $new-component-height;
     }

   • 组件

     import React, {
         Component,
         PropTypes,
     } from 'react';
     import classnames from 'classnames';
     import './style/index.scss';
      
     class NewComponent extends Component {
         render() {
             const {
                 children,
                 className,
             } = this.props;
      
             const classNames = classnames({
                 'cuk-new-component': true,
                 [className]: className,
             });
      
             return (
                 <div className={classNames}>
                     {children}
                 </div>
             );
         }
     }
      
     NewComponent.propTypes = {
         className: PropTypes.string,
     };
     NewComponent.defaultProps = {};
      
     export default NewComponent;
      

   • 测试

     import React from 'react';
     import renderer from 'react-test-renderer';
     import NewComponent from '../index';
      
     it('render new component correctly', () => {
         const component = renderer.create(
             <NewComponent className="customized-component-class" />
         );
         const tree = component.toJSON();
         expect(tree).toMatchSnapshot();
     });

组件提交

1. pre-commit

   我们采用 eslint 和 jest 来检查和测试代码，这些检查会在你 git commit 之前触发。 如果你在开发阶段频繁的 commit，可能会感觉 pre-commit 很烦恼，建议在 git commit 前手动执行 yarn run lint && yarn test； 或者在开发阶段开启测试的 watch 模式：yarn test -- --watch 并在提交前执行 yarn run lint，并且更慎重的提交你的组件代码。

   关于 lint , 你可能需要前往 http://eslint.org/docs/rules 查看，哪种代码风格能够通过 lint 检查，或者你可以在相关讨论组直接贴出错误提示询问。

2. git commit

   我们使用 git cz 来代替 git commit 生成统一的 commit message，关于 git cz, 请前往 https://github.com/commitizen/cz-cli 自行学习和安装。

3. 创建 Merge Request

   在 git cz 后，你可以直接利用 Coding 提供的快捷创建 Merge Request 的方式来获得 code review，使用以下脚本可以轻松创建一个以 commit message 标题 + 描述的 Merge Request:

   git push origin [local-component-branch]:mr/[remote-target-branch]/[local-component-branch]

   Example:

   git push origin radio-component:mr/master/radio-component

说明:

将本地的 radio-component 分支推送到远程分支 mr/master/radio-component 上，并创建目标分支为 master 的 Merge Request。

注意事项

1. 样式文件中的颜色必须优先选取 style/theme/default.scss 中存在的颜色，如果需要的颜色不存在，并且该颜色有一定通用性，可在 default.scss 中添加新的变量

2. 需要添加全局通用的样式，请现在 style/core 中搜索是否已存在，不存在则可以在其中的 common.scss 文件中添加，如果需要用到 mixin 或者 function，需单独 @import 需要的 scss 文件。

3. 每个组件都需要支持 className 参数，便于外部扩展。

4. 新增组件后，请在 CHANGELOG.md 文件的 ## Unreleased 的 ### Added 下（没有该项目则新增一个）添加相关新增组件说明（一句话说明），不允许使用 git log 信息当作 changelog 内容（第一个版本除外）。

5. 已存在组件发生 Breaking Changes 时，必须在 CHANGELOG.md 文件的 ## Unreleased 的 ### Changed下（没有该项目则新增一个）添加 change 说明（一句话说明）；如需要 Deprecated API 时，请在 CHANGELOG.md 文件的 ## Deprecated 下新增一句话说明。

发布文档

我们采用 bisheng 作为文档生成工具，轻松使用以下工具就能将最新的文档发布至 Coding Pages 上：

yarn run deploy

发布到 NPM

1. 修改 package.json 的 version 参数，并将 CHANGELOG.md 中的 ## Unreleased 改为 ## [新版本号]，并新增空的 ## Unreleased 项

2. 将最新改动合并至 master 分支

3. 使用 yarn run pub 即可

4. 使用 yarn run deploy 更新文档中的 ChangeLog

如果需要在发布前测试编译后的组件库是否表现正常，可按如下步骤测试：

1. 执行 yarn run pre-publish 将代码编译到 lib 目录下

2. 执行 pwd 记录当前组件项目根目录，下面用 LIB_ROOT 来表示

3. 在另外一个示例项目中执行 yarn install LIB_ROOT/lib 进行本地安装

4. 在示例项目中使用 coding-ui-kit 进行测试确认