amazeui学习笔记二（进阶开发5）--Web 组件开发规范Rules

2021-07-12 02:32:10

amazeui学习笔记二（进阶开发5）--Web 组件开发规范Rules

一、总结

1、见名知意：见那些class名字知意，见函数名知意，见文件名知意 例如（HISTORY.md Web 组件更新历史记录。）

二、Web 组件开发规范Rules

Web 组件基于 Amaze UI 基础库（CSS / JS）开发，在基础库已有样式、功能的基础上做更多扩展。

Web 组件样式组织

Web 组件的样式有三个层级：

  1. Amaze UI 基础样式: 每个网站项目中都会默认引入以下基础样式，组件开发时应在以下样式的基础上进行。

    • variables.less
    • mixins.less
    • base.less
    • grid.less
    • block-grid.less
    • utility.less

  2. Amaze UI 其他样式组件：Web 组件编写过程中使用到类似的样式时应当引入相关 CSS 组件，在此上进行微调，比如 button.less、close.less。

  3. 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 格式，下面的注释仅为方便解释各项含义添加。

 Copy
{

    // 组件名称: 使用小写字母，不能和存在的组件重名

    "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": "密码",

                        "placeholder": "设置密码",

                        "type": "text",

                        "default": "",

                        "required": true

                    }

                }

            }

        }

    },

    // 是否隐藏组件 - 此选项供云适配 WebIDE 使用

    "hidden": false

}

README.md

Web 组件使用说明，包括 Web 组件 API 介绍、使用技巧、注意事项等。

HISTORY.md

Web 组件更新历史记录。

src 目录

src 目录包含 Web 组件的模板（hbs）、核心样式（less）、交互（js）、图标（png）、主题文件。

src 目录里的文件使用 Web 组件名称作为文件名，主题使用 {Web 组件名}.{主题名}.less 形式命名。

  • {widget}.hbs: 模板，使用 handlebars
  • {widget}.less: 主题核心样式，使用 less 编写
  • {widget}.js: 组件交互
  • {widget}.png: 组件图标，50px * 50px
  • {widget}.default.less: 默认主题
  • {widget}.xxx.less: 其他主题，可以任意多

模板 {widget}.hbs

  • data-am-widget="figure" 为统一标识符；
  • .am-{Web 组件名} 为 Web 组件基础标识符，Web 组件的所有子元素、主题、状态基于此命名； Web 组件基础标识符采用 am-{widget} 方式命名，子元素、主题、状态采用 am-{widget}-{子元素|主题|状态}，如 am-figure-hover 、 am-figure-bd 、 am-figure-active 、 am-figure-ios7。
  • 模板使用 {{#this}}..{{this}} 包裹（Web 组件使用时注册为 Handlebars partial，通过 {{> widget data}} 的形式调用。
 Copy
{{#this}}

  <figure data-am-widget="figure"

      class="am-figure{{#if theme}} am-figure-{{theme}}{{else}} am-figure-default{{/if}}{{#if options.zoomble}} am-figure-zoomable{{/if}}{{#if widgetId}} {{widgetId}}{{/if}}{{#if className}} {{className}}{{/if}}"{{#if id}}

      id="{{id}}"{{/if}}>

    {{#if content.img}}

      <img src="{{content.img}}" alt="{{#if content.imgAlt}}{{content.imgAlt}}{{else}}{{content.figcaption}}{{/if}}"/>

    {{/if}}

    {{#if content.figcaption}}

       <figcaption class="am-figure-capition">

         {{content.figcaption}}

       </figcaption>

    {{/if}}

  </figure>

{{/this}}

注意：

  • Handlebars 模板中不支持 <script> 标签，如需加载外部脚本需在 {widget}.js 中进行。
  • 如果需要保存用户设置的选项，使用 data-am-{widget}-{option} 保存在模板中，然后在 {widget}.js 中通过 attr('data-am-{widget}-{option}') 读取。

核心样式 {widget}.less

Web 组件样式使用 less 编写。

 Copy
.am-{widget} {

  .hook-am-{widget};

}

.hook-am-{widget}() {}

样式添加必要的 hook，方便用户修改。

默认主题 {widget}.defalt.less

 Copy
.am-{widget}-default {

  .hook-am-{widget}-default;

}

.hook-am-{widget}-default() {}

其他主题 {widget}.xxx.less

 Copy
.am-{widget}-xxx {

  .hook-am-{widget}-xxx;

}

.hook-am-{widget}-xxx() {}

Web 组件交互 {widget}.js

Amaze UI 使用 Seajs 、Zepto，Widget 的脚本需按照 Seajs 规范编写。

如果要在 JS 中动态插入外部样式、脚本，必须在 load 事件触发以后再执行相关操作，以免影响网页基本内容载入。

 Copy
define(function(require, exports, module) {

    // 按此方式使用 Zepto

    var $ = window.Zepto;

});

开发脚手架

我们提供一个基于 Slush.js 的开发脚手架，可以快速生成 Web 组件目录及相关文件。

全局安装 Slush:

 Copy
npm install -g slush

全局安装 slush-amuiwidget:

 Copy
npm install -g slush-amuiwidget

在 Amaze UI 项目根目录下面执行:

 Copy
slush amuiwidget

调试预览

按照规范开发完 Web 组件以后，可以在本地调试预览组件。

在 Amaze UI 项目根目录下执行以下命令，安装依赖：

npm install

全局安装 nodemon：

npm install nodemon -g

安装完成以后执行：

gulp preview

然后在浏览器里打开 http://localhost:3008/#{component} 查看组件的效果，{component} 替换为组件名称。

有样式、脚本、配置文件修改时，修改完成以后刷新浏览器即可，nodemon 会自动重启 Node 服务。

上一篇：redis相关笔记(二.集群配置及使用)


下一篇：项目经验之:再来一章：excel导入数据 封装成最棒的不容易！！！