• amazeui学习笔记二(进阶开发5)--Web 组件开发规范Rules


    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.lessclose.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 服务。

  • 相关阅读:
    第一次玩github,第一个开源小项目——xxoo
    从Cortex-M3的MSP 和PSP谈Linux能否在中断中使用Sleep
    MSP与PSP
    Keil综合(03)_map文件全解析[转]
    Android 格式化分区命令
    强化学习(二)马尔科夫决策过程(MDP)
    强化学习(一)模型基础[转]
    在博客中使用MathJax写数学公式
    循环神经网络(RNN)模型与前向反向传播算法
    Git missing Change-Id in commit message footer解决方法
  • 原文地址:https://www.cnblogs.com/Renyi-Fan/p/9005820.html
Copyright © 2020-2023  润新知