npm package: @riil/css_builder
Description: ![image](http://172.17.189.70/relax_group/css_builder/raw/master/functional.jpg) ### 功能 1. 支持批量编译。 1. 支持增量编译module中scss,scss文件新增，修改，删除工具相应会自动生成样式。 1. 支持插件scss开发编译。 1. 减少平台级代码维护，仅作为工具单独维护。    > 之前工具代码和版本一起，需要维护多个版本源码。 1. 支持图片覆盖`/(jpeg|png|gif|svg|jp
Author: zhoumingqiang@ruijie.com.cn
Latest version: 1.0.33

![image](http://172.17.189.70/relax_group/css_builder/raw/master/functional.jpg)
### 功能
1. 支持批量编译。
1. 支持增量编译module中scss,scss文件新增，修改，删除工具相应会自动生成样式。
1. 支持插件scss开发编译。
1. 减少平台级代码维护，仅作为工具单独维护。
   > 之前工具代码和版本一起，需要维护多个版本源码。
1. 支持图片覆盖`/(jpeg|png|gif|svg|jpg)/i`。

 
### 更新日志
[点击查看](http://172.17.189.70/relax_group/css_builder/raw/master/changelog.md)

### 安装
1. 参考[npm私有仓库配置使用](http://172.17.189.71:7001/#/detail/@ruijie/test)配置npm仓库环境设置全局registry`npm 
registry`
   或者直接使用 `npm install --registry http://172.17.189.71:7001`设置当前项目的`registry`。
1. 在任意文件夹下创建config.json文件并配置以下参数
    ```json
     {
       "config":{
         "source":"theme_src路径",  
         "onlyModule":false,
         "colors":["light","dark"],  
         "theme": ["darkblue", "hd", "green", "blue", "diamond-blue", "red", "darkred"],
         "target": "theme文件夹输出路径"
       }
    }
  
    ```
    **`以下选填为json对象中可无此属性，程序使用默认值进行处理！`**
    1. `source`**必填**,是指定pc端模块样式目录，一般是`theme_src`文件夹路径。结尾必须为`theme_src`。
    1. `onlyModule`选填,是否只输出module，默认false全部输出。true只输出module
    1. `colors`选填,是指色系，默认为`["light","dark"]`。
    1. `theme`选填,是指主题，默认为`["darkblue", "hd", "green", "blue", "diamond-blue", "red","darkred"]`,一般为了加快编译，
    可以设置成当前需要测试的主题，比如设置只显示网办主题`[red]`。
    1. `target`选填,是指最终编译输出的theme文件地址，默认为config.json同级目录。

1. 命令行执行`npm install @ione/css_builder`在config.json同级文件夹中生成`node_modules`文件夹。

### 依赖
* node >= 6.9.2
* npm  >= 3

建议使用最新LTS版本(8.12.0)。
 
### 运行
#### 编译并监控source中的scss,图片

*  mac/linux
```shell
./node_modules/.bin/gulp -f ./node_modules/@ione/css_builder/gulpfile.js
```
*  windows
```shell
.\node_modules\.bin\gulp -f .\node_modules\@ione\css_builder\gulpfile.js
```

#### 仅仅监控source中的scss，图片
*  mac/linux
```shell
./node_modules/.bin/gulp -f ./node_modules/@ione/css_builder/gulpfile.js watch
```
*  windows
```shell
.\node_modules\.bin\gulp -f .\node_modules\@ione\css_builder\gulpfile.js watch
```

#### 编译输出主题
 
*  mac/linux
```shell
./node_modules/.bin/gulp -f ./node_modules/@ione/css_builder/gulpfile.js compile
```
*  windows
```shell
.\node_modules\.bin\gulp -f .\node_modules\@ione\css_builder\gulpfile.js compile
```

### git仓库
[ssh://git@172.17.189.70:1431/relax_group/css_builder.git](ssh://git@172.17.189.70:1431/relax_group/css_builder.git)


## 原理

### compile
![image](http://172.17.189.70/relax_group/css_builder/raw/master/css_builder.png)
1. 启动`compile`会清空`tmp`、`theme`文件夹。
2. 工作时序图如上。
3. 时序图中名词解释
    * coreScss 
        - 在css_builder项目中的theme_src,包含内容结构`附1`
        - 包含平台级的公共主题皮肤变量，平台级的图片
        - 由平台级同事维护并发布到npm仓库。
        - 包含默认的平台级的 css/plugin、css/package样式。
    * source
       - 编译时候指定的路径，该路径必须以theme_src结尾，目录大致如`附1`。
       - source中图片可以覆盖平台级的图片，允许存放图片的位置的路径规则如下:
         ```javascript
            // source为config.json中配置的source的绝对路径。
             new Regexp(`^${source}/image`)
             new Regexp(`^${source}/(${color.join('|')})/(${theme.join('|')})/image`)
         ```
        - source中scss可以覆盖平台级scss，允许覆盖平台级的scss路径规则如下:
          ```javascript
             // source为config.json中配置的source的绝对路径。
              new Regexp(`^${source}/css`)
          ```
        - 图片和scss覆盖只需路径以以上路径开始即为满足，如果平台级有此文件，覆盖，否则添加。
        - css下`_variables.scss`变量文件，原则上不允许覆盖。
    * tmp
        - 编译的工作临时目录，只需`compile`命令时会清空。
        - 目录中包含从`coreScss`、`source`中复制的`theme_src`
        - 目录中的从css目录分发到`colors/theme/`,例`light/red`下的结构如下
            ```
                ├── _layout.scss
                ├── _variables.scss
                ├── css                     //分发后产生。
                │   ├── _variables.scss
                │   ├── module
                │   ├── package
                │   └── plugin
                └── image
    
            ```
    * theme
       - 编译输出最终样式的目录。
       - 默认不配置，文件夹产生的位置和config.json同级目录。
       

***

### watch
  1. 主要工作流程同`compile`,但是执行`watch`命令不会清空`tmp`、`theme`文件夹。
  1. **如果需要增量编译监控文件则建议直接执行默认命令(不指定参数或者指定参数为`default`)**
     ```
      //当前命令为
      ./node_modules/.bin/gulp -f ./node_modules/@ione/css_builder/gulpfile.js 
      ./node_modules/.bin/gulp -f ./node_modules/@ione/css_builder/gulpfile.js default
     ```
  1. 文件回滚
     - 回滚只会产生于`watch`过程中,`compile`中不存在回滚功能。
     - 当`source`中覆盖了`coreScss`的文件(图片、scss)被删除后，自动将coreScss中文件编译输出到`theme`中。
     
### 注意事项
1. 不建议直接使用`watch`方式，建议调用`default`方式先编译再监控。
1. `watch`只会对当前文件进行增量编译，未能处理当前文件中存在有引用当前文件的同步编译处理。
1. sass中认为_name.scss和name.scss为同一个文件，但是在文件系统中未作处理，如果相同目录下存在类似文件命名
   会产生错误。
1. 提醒如果一个文件被命名以`_`开头，则表示此文件不需要编译生成css文件,仅做依赖。
1. 开发人员不要在${source}/css中创建`_variables.scss`或者`variables.scss`,会覆盖coreScss中的`_variables
.scss`文件导致编译出的结果不正确。













***
### 附
#### 1. coreScss目录结构
```
├── css
│   ├── _variables.scss
│   ├── package
│   │   ├── alertify
│   │   │   └── alertify.scss
│   │   ├── bootstrap
│   │   │   ├── bootstrap.scss
│   │   │   └── fonts
│   │   │       └── bootstrap
│   │   │           ├── glyphicons-halflings-regular.eot
│   │   │           ├── glyphicons-halflings-regular.svg
│   │   │           ├── glyphicons-halflings-regular.ttf
│   │   │           ├── glyphicons-halflings-regular.woff
│   │   │           └── glyphicons-halflings-regular.woff2
│   │   ├── bootstrap-datetimepicke
│   │   │   └── datetimepicke.scss
│   │   ├── bootstrap-table
│   │   │   └── bootstrap-table.scss
│   │   ├── codemirror
│   │   │   └── codemirror.scss
│   │   ├── datatables
│   │   │   └── datatables.scss
│   │   ├── datatables-select
│   │   │   └── select-datatables.scss
│   │   ├── daterangepicker
│   │   │   └── daterangepicker.scss
│   │   ├── dropzone
│   │   │   └── basic.scss
│   │   ├── editable
│   │   │   └── editable.scss
│   │   ├── gridstack
│   │   │   └── gridstack.scss
│   │   ├── jstree
│   │   │   └── jstree.scss
│   │   ├── select2
│   │   │   └── select2.scss
│   │   ├── switch
│   │   │   └── switch.scss
│   │   ├── toastr
│   │   │   └── toastr.scss
│   │   └── webui-popover
│   │       └── webui-popover.scss
│   └── plugin
│       ├── activityrecord.scss
│       ├── business
│       │   └── condition.scss
│       ├── commentlist.scss
│       ├── cron.scss
│       ├── drawer.scss
│       ├── filelist.scss
│       ├── jquery.datachooser.scss
│       ├── lightselect.scss
│       ├── listeditable.scss
│       ├── marktip.scss
│       ├── moblie.scss
│       ├── pearl.scss
│       ├── relationworkorder.scss
│       ├── roleuserselect.scss
│       ├── search.scss
│       ├── selectinput.scss
│       ├── step.scss
│       ├── table.scss
│       ├── widget.scss
│       └── workbench.scss
├── dark
│   ├── _color.scss
│   ├── _variables.scss
│   ├── blue
│   │   ├── _layout.scss
│   │   ├── _variables.scss
│   │   └── image
│   │       ├── chrome.png
│   │       ├── emotion
│   │       │   ├── body-bg.jpg
│   │       │   ├── login-bg.jpg
│   │       │   ├── login-logo.png
│   │       │   └── logo.png
│   │       ├── firefox.png
│   │       ├── logo2.png
│   │       ├── relax
│   │       │   ├── login-bg.jpg
│   │       │   ├── login-logo.png
│   │       │   └── logo.png
│   │       └── theme-diamond.png
│   └── diamond-blue
│       ├── _layout.scss
│       ├── _variables.scss
│       └── image
│           ├── chrome.png
│           ├── emotion
│           │   ├── body-bg.jpg
│           │   ├── login-bg.jpg
│           │   ├── login-logo.png
│           │   └── logo.png
│           ├── firefox.png
│           ├── logo2.png
│           ├── relax
│           │   ├── login-bg.jpg
│           │   ├── login-logo.png
│           │   └── logo.png
│           └── theme-diamond.png
├── global
│   ├── _global.scss
│   ├── _layout.scss
│   └── bootstrap
│       ├── _badge.scss
│       ├── _bootstrap-weight.scss
│       ├── _button-groups.scss
│       ├── _buttons.scss
│       ├── _checkbox.scss
│       ├── _code.scss
│       ├── _dropdowns.scss
│       ├── _form.scss
│       ├── _labels.scss
│       ├── _list-group.scss
│       ├── _media.scss
│       ├── _mixins.scss
│       ├── _modals.scss
│       ├── _nav.scss
│       ├── _panels.scss
│       ├── _progress-bars.scss
│       ├── _tables.scss
│       ├── _tooltip.scss
│       ├── _type.scss
│       ├── _variables.scss
│       ├── _wells.scss
│       └── mixins
│           ├── _buttons.scss
│           ├── _forms.scss
│           ├── _layout.scss
│           ├── _line.scss
│           └── _tab-focus.scss
├── image
│   └── relax
│       ├── callcenter
│       │   ├── call.png
│       │   ├── callout.png
│       │   └── empty.png
│       ├── default_login-logo.png
│       ├── default_logo.png
│       ├── icon-bill.png
│       ├── icon-service.png
│       ├── login-logo.png
│       ├── logo.png
│       ├── portal
│       │   ├── bigscreen
│       │   │   └── his
│       │   │       ├── bg.png
│       │   │       ├── footer.png
│       │   │       ├── main-title.png
│       │   │       └── title-bg.png
│       │   └── dashboard_empty.png
│       └── webchat
│           └── config
│               ├── bg-1.png
│               ├── bg-2.png
│               ├── bg-3.png
│               ├── bg-4.png
│               ├── bg-5.png
│               ├── bg-6.png
│               └── bg-7.png
├── light
│   ├── _color.scss
│   ├── _variables.scss
│   ├── darkblue
│   │   ├── _layout.scss
│   │   ├── _variables.scss
│   │   └── image
│   │       ├── card-item-empty.png
│   │       ├── chrome.png
│   │       ├── data-empty.png
│   │       ├── emotion
│   │       │   ├── login-bg.jpg
│   │       │   ├── login-logo.png
│   │       │   └── logo.png
│   │       ├── empty-order.png
│   │       ├── empty-state-noservice.png
│   │       ├── firefox.png
│   │       ├── grid-item-empty.png
│   │       ├── icon-service.png
│   │       ├── inquire.png
│   │       ├── no-service-icon.png
│   │       ├── none-service.png
│   │       ├── relax
│   │       │   ├── body-bg.jpg
│   │       │   ├── default_login-logo.png
│   │       │   ├── default_logo.png
│   │       │   ├── login-bg.jpg
│   │       │   ├── login-logo.png
│   │       │   └── logo.png
│   │       ├── service-home.png
│   │       ├── setting.png
│   │       └── user.png
│   ├── green
│   │   ├── _layout.scss
│   │   ├── _variables.scss
│   │   └── image
│   │       ├── chrome.png
│   │       ├── emotion
│   │       │   ├── login-bg.jpg
│   │       │   ├── login-logo.png
│   │       │   └── logo.png
│   │       ├── firefox.png
│   │       ├── logo2.png
│   │       ├── relax
│   │       │   ├── login-bg.jpg
│   │       │   ├── login-logo.png
│   │       │   └── logo.png
│   │       └── theme-diamond.png
│   ├── hd
│   │   ├── _layout.scss
│   │   ├── _variables.scss
│   │   └── image
│   │       ├── card-item-empty.png
│   │       ├── chrome.png
│   │       ├── data-empty.png
│   │       ├── emotion
│   │       │   ├── login-bg.jpg
│   │       │   ├── login-logo.png
│   │       │   └── logo.png
│   │       ├── empty-order.jpg
│   │       ├── empty-order.png
│   │       ├── firefox.png
│   │       ├── grid-item-empty.png
│   │       ├── inquire.png
│   │       ├── none-service.png
│   │       ├── relax
│   │       │   ├── body-bg.jpg
│   │       │   ├── default_login-logo.png
│   │       │   ├── default_logo.png
│   │       │   ├── login-bg.jpg
│   │       │   ├── login-logo.png
│   │       │   └── logo.png
│   │       ├── setting.png
│   │       └── user.png
│   └── red
│       ├── _layout.scss
│       ├── _variables.scss
│       └── image
│           ├── card-item-empty.png
│           ├── chrome.png
│           ├── data-empty.png
│           ├── emotion
│           │   ├── login-bg.jpg
│           │   ├── login-logo.png
│           │   └── logo.png
│           ├── empty-order.png
│           ├── empty-state-noservice.png
│           ├── firefox.png
│           ├── grid-item-empty.png
│           ├── icon-service.png
│           ├── inquire.png
│           ├── no-service-icon.png
│           ├── none-service.png
│           ├── relax
│           │   ├── body-bg.jpg
│           │   ├── default_login-logo.png
│           │   ├── default_logo.png
│           │   ├── login-bg.jpg
│           │   ├── login-logo.png
│           │   └── logo.png
│           ├── service-home.png
│           ├── setting.png
│           └── user.png
└── package
    ├── bootstrap
    │   └── stylesheets
    │       ├── _bootstrap-compass.scss
    │       ├── _bootstrap-mincer.scss
    │       ├── _bootstrap-sprockets.scss
    │       ├── _bootstrap.scss
    │       └── bootstrap
    │           ├── _alerts.scss
    │           ├── _badges.scss
    │           ├── _breadcrumbs.scss
    │           ├── _button-groups.scss
    │           ├── _buttons.scss
    │           ├── _carousel.scss
    │           ├── _close.scss
    │           ├── _code.scss
    │           ├── _component-animations.scss
    │           ├── _dropdowns.scss
    │           ├── _forms.scss
    │           ├── _glyphicons.scss
    │           ├── _grid.scss
    │           ├── _input-groups.scss
    │           ├── _jumbotron.scss
    │           ├── _labels.scss
    │           ├── _list-group.scss
    │           ├── _media.scss
    │           ├── _mixins.scss
    │           ├── _modals.scss
    │           ├── _navbar.scss
    │           ├── _navs.scss
    │           ├── _normalize.scss
    │           ├── _pager.scss
    │           ├── _pagination.scss
    │           ├── _panels.scss
    │           ├── _popovers.scss
    │           ├── _print.scss
    │           ├── _progress-bars.scss
    │           ├── _responsive-embed.scss
    │           ├── _responsive-utilities.scss
    │           ├── _scaffolding.scss
    │           ├── _tables.scss
    │           ├── _theme.scss
    │           ├── _thumbnails.scss
    │           ├── _tooltip.scss
    │           ├── _type.scss
    │           ├── _utilities.scss
    │           ├── _variables.scss
    │           ├── _wells.scss
    │           └── mixins
    │               ├── _alerts.scss
    │               ├── _background-variant.scss
    │               ├── _border-radius.scss
    │               ├── _buttons.scss
    │               ├── _center-block.scss
    │               ├── _clearfix.scss
    │               ├── _forms.scss
    │               ├── _gradients.scss
    │               ├── _grid-framework.scss
    │               ├── _grid.scss
    │               ├── _hide-text.scss
    │               ├── _image.scss
    │               ├── _labels.scss
    │               ├── _list-group.scss
    │               ├── _nav-divider.scss
    │               ├── _nav-vertical-align.scss
    │               ├── _opacity.scss
    │               ├── _pagination.scss
    │               ├── _panels.scss
    │               ├── _progress-bar.scss
    │               ├── _reset-filter.scss
    │               ├── _reset-text.scss
    │               ├── _resize.scss
    │               ├── _responsive-visibility.scss
    │               ├── _size.scss
    │               ├── _tab-focus.scss
    │               ├── _table-row.scss
    │               ├── _text-emphasis.scss
    │               ├── _text-overflow.scss
    │               └── _vendor-prefixes.scss
    ├── bootstrap-table
    │   └── bootstrap-table.scss
    ├── font
    │   └── fontAwsome
    │       ├── FontAwesome.otf
    │       ├── fontawesome-webfont.eot
    │       ├── fontawesome-webfont.svg
    │       ├── fontawesome-webfont.ttf
    │       ├── fontawesome-webfont.woff
    │       └── fontawesome-webfont.woff2
    └── jstree
        └── themes
            ├── _base.scss
            ├── _main.scss
            ├── _mixins.scss
            ├── _responsive.scss
            ├── default
            │   ├── 32px.png
            │   ├── 40px.png
            │   ├── style.less
            │   ├── style.scss
            │   └── throbber.gif
            └── default-dark
                ├── 32px.png
                ├── 40px.png
                ├── style.scss
                └── throbber.gif


```