qd-design v0.2.51
项目介绍
QDUI
是轻量、可靠、易用的起点移动端 UI
业务组件库,目前的Vue
版本,它已经在起点读书 App
中的内嵌页 H5
页面中被广泛使用。
一、项目仓库
项目名称 | 仓库 |
---|---|
qd-design | https://gitlab.inner.yuewen.local/yux-pages/QDUI |
二、项目目录指引
一级目录
├── README.md // 安装、启动、打包命令
├── babel.config.js // vuecli-plugin-babel 配置
├── build // 一些打包时自动化脚本
├── dist // 打包生成的最终源码
├── examples // 官网开发的 demo 页面
├── jest.config.js // 单元测试配置
├── node_modules
├── package-lock.json
├── package.json
├── packages // QDUI 组件 & 功能模块
├── public // 项目入口文件
├── tests // 单元测试页面
├── vue.config.js // 项目配置文件
二级目录(开发相关)
examples(官网文档 + 右侧 demo)
├── assets // 官网的通用资源
├── layout // 官网拆分的模块模板 html
├── views // 官网文档的说明页
├── app.vue // 官网首页入口
├── main.js // 官网全局配置项
├── nav.config.json // 左侧边栏路由配置
├── router.js // 动态路由配置
packages (独立组件开发目录)
├── Button (以 Button 为例,新增组件目录结构相同)
├── ├── demo/index.vue // 组件右侧 demo
├── ├── readme.md // markdown文档转 html
├── style // QDUI 组件通用样式
├── index.js // 注册组件和公共入口
三、开发注意事项 (以 Button
为例)
右侧 demo
开发规范:需按照组件形态或者类型进行排版,一种类型形态独占一行,需要把所有类型示例各展示一个在页面中。
左侧 Markdown
文档需和右侧 demo
对应,方便使用者对应查询。文档底部需附上 Api
表格,变量类型、默认值,如果有未开发完毕的,请加上 todo
标签,具体写法可以参考 Button
组件中 readme.md
四、组件和样式命名规范
组件命名规范:qd + 下划线 + 模块名,例如:qd-button,qd-dialog。 CSS 类命名必须使用 BEM 的规范 参考文章: Get Bem 腾讯 github CSS BEM 书写规范
Bem
是块 block
、元素 element
、修饰符modifier
的简写,由 Yandex
团队提出的一种前端 CSS
命名方法论。
-
中划线 :仅作为连字符使用,表示某个块或者某个子元素的多单词之间的连接记号。例如:qd-btn
。__
双下划线:双下划线用来连接块和块的子元素。例如:qd-btn__label
。--
双中划线:用来描述一个块或者块的子元素的一种状态、修饰符。例如:qd-btn--loading
。
多种组合示例:qd-dialog__sub-title
表示的是对话框副标题
连接符 qd-btn
qd-switch
子模块 qd-btn__label
qd-switch__node
修饰符、状态 qd-btn--loading
qd-switch--disabled
sass变量命名规范 1. 与颜色主题相关的,颜色统一使用 $-- 开头。 2.其他变量使用驼峰命名。
五、深色模式的颜色变量规范
qd-design
中有一套与设计约定的基础颜色映射关系表,是用来切换至深色模式和其他皮肤模式时会自动映射改变颜色的变量系统。颜色映射表:石墨链接
qd-design
项目目录中的 packages/style/_variables.scss
中有完整的映射变量,所有的组件颜色需按照组件 设计稿 中的颜色标签查找到 QDUI
中对应的 SASS
变量编写;
例如:color: $--Primary_500
基础色就为 #E5353E
,在深色模式下就会自动映射成为相应的颜色。
六、注释规范
- 函数注释使用多行注释,写明方法名、入参类型和作用,推荐使用 IDE 的 /**+回车 自动填补,然后填上函数作用。
/**
* 背景颜色转换
* @param color
* @returns {string}
*/
bgTransform(color) {
if (color) {
color = this.border ? 'none' : color
return color
}
},
七、点击态规范
QDUI
使用了默认全局样式 -webkit-tap-highlight-color: rgba(0,0,0,.05);
定义了点击反馈样式,该 CSS
属性方案成本较低,但并不能运用在所有场景中,需要按照规范去设置才能生效
以下几点请注意:
1、使用 <a href="javascript:"></a>
包裹元素时,点击态会默认使用 -webkit-tap-highlight-color: rgba(0,0,0,.05);使点击态背景生效
2、若是在 li
、div
等非 a
的其他标签上需要触发点击态时,需加上 class="qd-clickable"
3、点击态边界溢出的情况,视情况需要在父元素加上 overflow:hidden
原理请参考乐享文档:《H5 点击态的 CSS 简单方案》
八、提交规范
代码提交规范采用 Angular 的 commit 规范,commit 信息需要包括:分为三部分:header、body 和 footer。header 是必须的,body 和 footer 可以省略, 项目已经添加了 commit message 的校验,不符合标准的将无法提交。
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
其中 header 包含三个字段: type(必须): 用于说明本次提交的类型,包括 feat、build、fix、docs、test 等 scope(可选): 用于说明 commit 影响的范围 subject(必须): 此次 commit 的简短描述。建议不超过 50 个字符
<type>(<scope>): <subject>
// e.g. "feat(loading): add loading component"
// e.g. "docs(README.md): 更新提交规范"
具体可参考乐享文档:《commit 提交规范》
九、分支合并规范
我们基于 gitlab 的 merge request 的功能进行分支合并,一个正常功能的开发流程包括以下几步:
- 新建开发分支
- 开发完成,提交分支代码
- 在 gitlab 中发起一个 Merge request
- Merge request 发送给别人进行 code review
- 修改代码直至所有 code review 提出的问题都被解决
- 合并进目标分支
其中分支命名规则:组件分支:feature/xxx; 构建相关分支: build/xxx。
并作以下强调:
- 不允许私自提交代码至 master 分支,必须通过发起 Merge request 来申请合并
- Merge request 必须通过 code review 并且审核人留下”同意合并“的留言后才能合并
- review 代码的人和写代码的人是这个功能的共同负责人
其他关于如果创建一个 Merge request 和 code review 的注意点可参考乐享文档《代码合并流程与规范》
十、代码规范
为保证代码风格一致性,我们使用了eslint和stylelint来进行规范,并且每次提交前都会执行npm run lint
对相应代码进行检查。
其中js部分采用的是eslint的 standard 标准
vue部分采用的是eslint-plugin-vue的 strongly-recommended 标准
sass部分采用的是stylelint的 stylelint-config-standard 标准
具体参见.eslintrc.js
和 .stylelintrc.yml
两个文件
十一、关于 qd-icon 图标的维护
在项目的 packages/assets/fonts
中有4种类型的 qd-icon
原始文件,qd-icon-v1.0.json
可以用来前往Icomoon,导入后可以用来增删改查。Icomoon
网站的使用教程可以参考乐享文档
PS:由于 iconfont
可能随时有增加需求,所以在目前开发过程中,用的是 base64 的字体地址,后续项目完工时考虑改成 cdn
服务器的字体文件,然后把本地文件配置开放给用户。
十二、单元测试
具体的规范可以在 tests/README.md 文件中查看
QDUI 的单元测试采用 Jest 测试组件。Vue
官方提供了 Vue Test Utils,可以在此网站查看具体的配置以及一些方法的使用。
规范:
- 模块的命名:
xxx 组件 - 要测试的功能
。比如:Loading 组件 - 样式
- 断言命名:
要测试的功能
。比如:颜色
- 每个断言应该只测试一个功能
- 单元测试代码统一写在
packages/xxx/__tests__
文件夹下,命名为:index.spec.js
命令:
npm run test:unit // 执行单元测试
npm run test:watch // 执行单元测试 - 监听模式
npm run test:com Loading // 执行单元测试 - 单个组件
十三、无障碍访问规范 todo
后续补齐
十四、组件功能与进度计划
石墨表格 以上是第一版常用组件列表,后续迭代再继续增加。
在开发时需要按照表格中的组件进行分类,并按照功能开发组件所提供的 API 。开发者需填写好周期,完成时间、组件状态,开发者姓名。
本文档乐享地址
https://yuewen.lexiangla.com/teams/k100042/docs/0324129ec5a811ea9e4c0a58ac136560?company_from=yuewen
开发指令
安装依赖
npm install
启动
npm run dev
build
npm run build
lint检查
npm run lint // 检查eslint和stylelint
npm run lint:fix // 检查并修复lint
快速新建一个空组件
npm run component:init [组件名称] [组件组别]
e.g. npm run component:init Button 基础组件
Customize configuration
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago