amazeui学习笔记二(进阶开发5)--Web 组件开发规范Rules
一、总结
1、见名知意:见那些class名字知意,见函数名知意,见文件名知意 例如(HISTORY.md
Web 组件更新历史记录。)
二、Web 组件开发规范Rules
Web 组件基于 Amaze UI 基础库(CSS / JS)开发,在基础库已有样式、功能的基础上做更多扩展。
Web 组件样式组织
Web 组件的样式有三个层级:
-
Amaze UI 基础样式: 每个网站项目中都会默认引入以下基础样式,组件开发时应在以下样式的基础上进行。
variables.less
mixins.less
base.less
grid.less
block-grid.less
utility.less
-
Amaze UI 其他样式组件:Web 组件编写过程中使用到类似的样式时应当引入相关 CSS 组件,在此上进行微调,比如
button.less
、close.less
。 -
Web 组件自身样式:Web 组件自身样式拆分出骨干样式和主题样式;每个 Web 组件可以有多个不同主题,主题基于骨干样式编写,每个主题相互独立。
- 骨干样式以
{widget}.less
命名; - 默认主题以
{widget}.default.less
命名; - 其他主题以
{widget}.{theme-name}.less
命名。
- 骨干样式以
目录结构及说明
一个组件的目录结构如下:
{widget}
|-- package.json
|-- README.md
|-- HISTORY.md
|-- resources
| `-- screenshots
| |-- 0.jpg
| |-- 1.jpg
| `-- 2.jpg
`-- src
|-- {widget}.hbs
|-- {widget}.js
|-- {widget}.less
|-- {widget}.default.less
|-- {widget}.[theme1].less
|-- {widget}.[themen].less
`-- {widget}.png
package.json
Web 组件核心描述文件,json
格式,下面的注释仅为方便解释各项含义添加。
{
// 组件名称: 使用小写字母,不能和存在的组件重名
"name": "sample",
// 版本号
"version": "0.0.1", // 组件本地化名字,目前有中文、英文两个选项 "localName": { "en": "", "zh-cn": "" }, // 组件类型 [""|"layout"|"social"] "type": "", // 组件 ICON,存放在 src 目录下 "icon": "sample.png", // 作者信息 "author": { "name": "xxx", "email": "xxx@yunshipei.com" }, // 组件描述 "description": "sample 描述", // 组件驱动者 "poweredBy": "AllMobilize", // 基础样式(无需修改) "styleBase": [ "variables.less", "mixins.less", "base.less", "grid.less", "block-grid.less", "utility.less" ], // 组件模板,使用 [handlebarsjs](http://handlebarsjs.com/) "template": "sample.hbs", // 依赖的库样式 "styleDependencies": [ "icon.less" ], // 组件核心样式 "style": "sample.less", // 组件主题(没有主题时将值设置为 null) "themes": [ { // 主题名称 sample.{xxx}.less 中的 {xxx},尽量语义化描述主题 "name": "default", // 主题描述,简要描述主题 "desc": "默认", // 主题使用配置选项 "options": {}, // 主题钩子 "hook": "hook-am-sample-default", // 主题使用的less变量 "variables": [ { // 变量名 "variable": "", // 变量描述名字 "name": "", // 默认值 "default": "", // 使用改变量的 css 样式 "used": [ { "selector": "", "property": "" } ] } ], // 主题演示数据,可以为多个 "demos": [ { // 演示描述 "desc": "", // 演示数据 "data": {} } ] } ], // Amaze UI 核心js(无需修改) "jsBase": [ "core.js" ], // 依赖的 Amaze UI js 插件 "jsDependencies": [], // 组件脚本 "script": "sample.js", // api 用于生成用户 GUI 界面以及保存用户提交的数据 "api": { "id": { "name": "ID", // 表单提示名称 "desc": "组件自定义ID,遵循CSS ID命名规范", "type": "text", // 表单类型 "default": "", // 默认值 "pattern": "", // 表单验证正则表达式 "required": false // 是否为必填 }, "className": { "name": "Class", "desc": "用户自定义组件 class,遵循 CSS class 命名规范", "type": "text", "default": "", "required": false }, // 主题选择(没有主题时将值设置为 null) "theme": { "name": "主题", "desc": "组件主题", "type": "select", // 下拉选框 "default": "default", "required": true, "dataList": "<%= pkg.themes %>" // 从 themes 中读取主题列表 }, // 组件选项(没有选项时将值设置为 null) "options": { "multiple": { "name": "同时展开多个面板", "desc": "是否允许同时展开多个面板", "type": "select", "default": false, "required": false, // 表单类型为 select 时通过 dataList 设置 <option> 数据 "dataList": [ { "value": "false", "title": "不启用", "selected": true }, { "value": true, "title": "启用" } ] } }, // 内容 "content": { // 内容类型 Array 数组、Object(对象) "type": "Array", "item": { "title": { "type": "text", "comment": "面板标题" }, "content": { "type": "html", "comment": "面板内容" } } } // 表单接口 - 测试接口,细节还会做调整 // 提供的表单接口必须支持跨域调用,并返回 JSON 数据 "forms": { "signin": { "url": "http://api.xxx.com/signin", // 提交数据的接口 "type": "POST", "desc": "登录表单,你可以在这里写表单的描述信息", "fields": { // 表单字段,字段名称应该和返回数据里的字段对应 "username": { "name": "用户名", "placeholder": "请使用邮箱", "type": "text", "default": "", "required": true }, "password": { "name": "密码", "placeholder": "设置密码", "type": "text", "default": "", "required": true }, "submit": { "name": "提交信息", "type": "submit", "default": "" } } }, "signup": { "url": "http://api.xxx.com/signup", "type": "POST", "desc": "注册表单,你可以在这里写表单的描述信息", "fields": { "username": { "name": "用户名", "placeholder": "请使用邮箱", "type": "text", "default": "", "required": true }, "password": { "name":