amazeui学习笔记二（进阶开发5）--Web 组件开发规范Rules
amazeui学习笔记二（进阶开发5）--Web 组件开发规范Rules
一、总结
1、见名知意：见那些class名字知意，见函数名知意，见文件名知意 例如（HISTORY.md Web 组件更新历史记录。）
二、Web 组件开发规范Rules
Web 组件基于 Amaze UI 基础库（CSS / JS）开发，在基础库已有样式、功能的基础上做更多扩展。
Web 组件样式组织
Web 组件的样式有三个层级：
-
Amaze UI 基础样式: 每个网站项目中都会默认引入以下基础样式，组件开发时应在以下样式的基础上进行。
variables.lessmixins.lessbase.lessgrid.lessblock-grid.lessutility.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": {