更新

QMUI Web 目前以 Github Release 管理版本，使用快速开始安装 QMUI Web 的用户只需进入项目 UI_dev/qmui 目录执行 git pull 即可更新至最新版本。通过其他方式安装的用户可以直接在 Github 中下载最新版本来进行更新。

QMUI 框架目前推出 3.0.0 版本，基于 Gulp 4 进行开发，重新梳理了框架的依赖包，能提供更稳定以及高效的工作流，并且集成了一套完整的 SVG Sprite 解决方案，可以方便地处理 SVG Sprite 的场景，同时对组件和工具方法也作出了一些优化。另外由于新版作出了大量的结构上的修改，因此与旧版本并不兼容，从旧版本升级到新版请浏览这里。

概况

QMUI Web 主要分为 project 和 qmui 两个文件夹，project 是我们实际编写项目内容的文件夹，分为 logic（业务代码） 和 widget（公共组件），为了保持 QMUI 的独立性，project 文件夹会被基于 Gulp 的工具复制一份到外层目录中使用，而不是直接修改 QMUI 目录中的版本。这个工具实际上也是 QMUI 提供的脚手架，会提供如雪碧图处理、include 模板功能、清理文件、压缩功能等便捷功能。

QMUI Web 遵循 QMUI 编码规范，因此框架中提供的样式除 Reset 外都以 qui_ 作开头，以充当框架的命名空间。业务上的样式也应该有自己的命名空间，例如本 Demo 中的样式的公共部分都以 dm_ 开头，各细致的业务就以业务的功能作开头（例如组件页面的非公共代码都以 widget_ 开头），从而以不同的命名空间划分不同的样式，避免样式的互相干扰。

除此以外，QMUI 封装了大量 Sass 方法供使用，另外还在 Demo 中以参考组件的形式收录了一些结构较复杂的扩展组件，供使用者参考。

环境配置

QMUI Web 基于 Gulp 和 Node.js，请确保安装 Node.js（建议 8.0 或以上版本），并用以下命令全局安装 Gulp：

#全局安装 Gulp
npm install -g gulp-cli

项目结构

QMUI Web 对项目文件结构（UI 层相关文件）有一定的依赖，不同的项目中如果能有相似的文件结构，也能便于开发。推荐的文件结构如下：

项目根目录
├─public          // 静态资源目录，由 Gulp 生成
│  ├─js           // 静态资源 js 文件
│  ├─style        // 静态资源 UI 文件
│  │  ├─css       // 静态资源 css 文件
│  │  └─images    // 静态资源 images 文件
│  └─template     // 最终的模板目录，区别于静态模板基于原生 HTML，最终模板通常是用功能完备的模板引擎驱动
├─UI_dev          // 实际进行开发的样式目录
│  ├─project      // 项目相关 Sass 与 images 文件，由 Gulp 生成，请参考“创建新项目”
│  │  ├─images    // 项目相关图片文件
│  │  ├─logic     // 项目相关逻辑样式
│  │  └─widget    // 项目相关公共组件样式
│  └─qmui_web     // QMUI Web 主源码应放置在这一层目录
├─UI_html         // 静态模板目录
└─UI_html_result  // 静态模板经 Gulp 处理后的版本，用于前端拼接最终的模板

这些目录 QMUI 会提供工具帮助完成创建，开发者并不需要手工创建这些目录。

另外这些目录结构只是层次上要求如此，即不建议修改目录的层级，但目录名如果与其他模块或组件冲突，可以自行修改目录名，并同步修改 qmui.config.js 的相关设置（qmui.qmui.config.js 需要复制到 UI_dev 中修改，如果直接修改 QMUI 源码中的配置文件，会影响框架的独立性，详细请参考“使用配置文件”）

快速开始

如果需要的环境已经配置好，那么就可以正式创建一个新项目了。

推荐使用 Yeoman 脚手架 generator-qmui 安装和配置 QMUI Web。该工具可以帮助你完成 QMUI Web 的所有安装和配置。

#安装 Yeoman，如果本地已安装可以忽略
npm install -g yo
#安装 QMUI 的模板
npm install -g generator-qmui
#在项目根目录执行以下命令
yo qmui

对于需要有更强定制性的开发者，请参考创建新项目（高级）

框架的使用

作为一个框架，QMUI Web 主要提供了四种能力来提升 UI 开发的效率与质量。分别用于快速实现项目 UI，快速解决重复劳动力工作，CSS 的预处理和复杂的组件参考四个方面，这也是 QMUI Web 的使用目标。

基础配置与组件

框架中会有一份配置表，是各种 Sass 的变量，这些变量控制了一个网页基本的字体样式，链接颜色，以及6个通用组件的样式配置，在创建一个新项目时，应该先根据设计稿配置好这些信息，当这些信息配置完成，那么一个项目的基本样式就可以快速实现了。例如下图中这些配置属于 QMUI 通用配置，通过修改这些配置则可以快速修改项目的字体策略、正文字体大小，链接颜色等 UI 常用的 CSS 属性。

内置工作流

QMUI 中的内置工作流由 Gulp 驱动，用于快速解决大量重复劳动力的工作，从而提升效率。QMUI 的 Gulp 中预先实现了监控 Sass 文件并自动编译，样式优化（浏览器兼容自动处理等），雪碧图处理，模板 include 能力（可以传参和使用条件判断），浏览器自动刷新，图片压缩，文件清理，文件合并以及自动变更路径的能力。各个命令都是在 qmui_web 文件夹中调用对应的 gulp 命令即可，部分命令依赖于 qmui.config.js 的配置。具体命令列表及功能可以参考内置工作流页面。

兼容性策略

QMUI 提供的几个能力里面，内置工作流基于 Node.js，因此与浏览器兼容无关。而 QMUI 提供的 Sass 方法、公共组件支持 IE9+。扩展组件由于是从不同的业务中抽取，因此对浏览器的支持并没有统一的标准，请参考每个扩展组件的标注。

完善框架

如果有意见反馈或者功能建议，欢迎创建 Issue 或发送 Pull Request，感谢你的支持和贡献。

#在 qmui_web 目录中执行以下命令可以开启 Debug 模式工作流
gulp --debug

// 示例
common.log('Tag', '普通消息')
common.warn('Tag', '警告消息')
common.error('Tag', '错误消息')

创建新项目（高级）

对于需要有更强定制性的开发者，可以采取自行配置的方式引入 QMUI Web。自行配置的方式适用于需要修改项目目录名等定制性较强的情况。如果使用这种开发方式，那么项目中的目录结构需要手工创建，但目录名可以自行取名，只需要修改配置表即可（下面会介绍如何使用配置表）。

#使用 npm 安装依赖包，待安装完毕后才可继续进行下一步
npm install

gulp init

创建自定义任务（高级）

QMUI Web 支持在内置工作流原有任务的基础上增加自定义的任务，通过特定的格式建立任务文件，可以调用 QMUI Web 工作流中的公共配置和组件来编写自定义任务，适用于需要针对项目添加额外的流程。

UI_dev
├── qmui.config.js
├── project
├── qmui_web
└── testTask.js
            

// qmui.config.js
module.exports = {
    /**
     * 模板 include 引擎
     *
     */
    'template': {
        'openIncludeFunction': true,
        'includePrefix': '@@'
    },

    /**
     * 增加自定义任务
     */
    'customTasks': {
        'testTask': '../testTask.js'
    }
};

// testTask.js
module.exports = (gulp, mix) => {

    const taskName = 'testTask';

    gulp.task(taskName, done => {

        // Custom task logic code
        mix.util.log('testTask execute succeed');

        done();
    });

    // Task Description (For gulp list)
    mix.addTaskDescription(taskName, 'Custom Task testTask');
};

#安装 Yeoman，如果本地已安装可以忽略
npm install -g yo
#安装 QMUI 的模板，如果本地已安装可以忽略
npm install -g generator-qmui
#在需要创建自定义任务文件的目录执行以下命令
yo qmui:task fileName;