Amaze UI Web 組件開(kāi)發(fā)規(guī)范

2018-10-30 20:11 更新
Web 組件是基于 Amaze UI 基礎(chǔ)庫(kù)（CSS / JS）開(kāi)發(fā)的，在基礎(chǔ)庫(kù)已有樣式、功能的基礎(chǔ)上做了更多擴(kuò)展。

1.Web 組件樣式組織

Web 組件的樣式有三個(gè)層級(jí)：
a). Amaze UI 基礎(chǔ)樣式: 每個(gè)網(wǎng)站項(xiàng)目中都會(huì)默認(rèn)引入以下基礎(chǔ)樣式，組件開(kāi)發(fā)時(shí)應(yīng)在以下樣式的基礎(chǔ)上進(jìn)行。
  • variables.less
  • mixins.less
  • base.less
  • grid.less
  • block-grid.less
  • utility.less
b).Amaze UI 其他樣式組件：Web 組件編寫過(guò)程中使用到類似的樣式時(shí)應(yīng)當(dāng)引入相關(guān) CSS 組件，在此上進(jìn)行微調(diào)，比如 button.less、close.less。
c).Web 組件自身樣式：Web 組件自身樣式拆分出骨干樣式和主題樣式；每個(gè) Web 組件可以有多個(gè)不同主題，主題基于骨干樣式編寫，每個(gè)主題相互獨(dú)立。
  • 骨干樣式以 {widget}.less 命名；
  • 默認(rèn)主題以 {widget}.default.less 命名；
  • 其他主題以 {widget}.{theme-name}.less 命名。

2.目錄結(jié)構(gòu)及說(shuō)明

一個(gè)組件的目錄結(jié)構(gòu)如下：
{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
2.1 package.json
Web 組件核心描述文件，json 格式，下面的注釋僅為方便解釋各項(xiàng)含義添加。
{
    // 組件名稱: 使用小寫字母，不能和存在的組件重名
    "name": "sample",

    // 版本號(hào)
    "version": "0.0.1",

    // 組件本地化名字，目前有中文、英文兩個(gè)選項(xiàng)
    "localName": {
        "en": "",
        "zh-cn": ""
    },

    // 組件類型 [""|"layout"|"social"]
    "type": "",

    // 組件 ICON，存放在 src 目錄下
    "icon": "sample.png",

    // 作者信息
    "author": {
        "name": "xxx",
        "email": "xxx@yunshipei.com"
    },

    // 組件描述
    "description": "sample 描述",

    // 組件驅(qū)動(dòng)者
    "poweredBy": "AllMobilize",

    // 基礎(chǔ)樣式（無(wú)需修改）
    "styleBase": [
        "variables.less",
        "mixins.less",
        "base.less",
        "grid.less",
        "block-grid.less",
        "utility.less"
    ],

    // 組件模板，使用 [handlebarsjs](http://handlebarsjs.com/)
    "template": "sample.hbs",

    // 依賴的庫(kù)樣式
    "styleDependencies": [
        "icon.less"
    ],

    // 組件核心樣式
    "style": "sample.less",

    // 組件主題（沒(méi)有主題時(shí)將值設(shè)置為 null）
    "themes": [
        {
            // 主題名稱 sample.{xxx}.less 中的 {xxx}，盡量語(yǔ)義化描述主題
            "name": "default",
            // 主題描述，簡(jiǎn)要描述主題
            "desc": "默認(rèn)",
            // 主題使用配置選項(xiàng)
            "options": {},
            // 主題鉤子
            "hook": "hook-am-sample-default",
            // 主題使用的less變量
            "variables": [
                {
                    // 變量名
                    "variable": "",
                    // 變量描述名字
                    "name": "",
                    // 默認(rèn)值
                    "default": "",
                    // 使用改變量的 css 樣式
                    "used": [
                        {
                            "selector": "",
                            "property": ""
                        }
                    ]
                }
            ],
            // 主題演示數(shù)據(jù)，可以為多個(gè)
            "demos": [
                {
                    // 演示描述
                    "desc": "",
                    // 演示數(shù)據(jù)
                    "data": {}
                }
            ]
        }
    ],

    // Amaze UI 核心js（無(wú)需修改）
    "jsBase": [
        "core.js"
    ],

    // 依賴的 Amaze UI js 插件
    "jsDependencies": [],

    // 組件腳本
    "script": "sample.js",

    // api 用于生成用戶 GUI 界面以及保存用戶提交的數(shù)據(jù)
    "api": {
        "id": {
            "name": "ID", // 表單提示名稱
            "desc": "組件自定義ID，遵循CSS ID命名規(guī)范",
            "type": "text", // 表單類型
            "default": "", // 默認(rèn)值
            "pattern": "", // 表單驗(yàn)證正則表達(dá)式
            "required": false // 是否為必填
        },
        "className": {
            "name": "Class",
            "desc": "用戶自定義組件 class，遵循 CSS class 命名規(guī)范",
            "type": "text",
            "default": "",
            "required": false
        },
        // 主題選擇（沒(méi)有主題時(shí)將值設(shè)置為 null）
        "theme": {
            "name": "主題",
            "desc": "組件主題",
            "type": "select", // 下拉選框
            "default": "default",
            "required": true,
            "dataList": "<%= pkg.themes %>" // 從 themes 中讀取主題列表
        },
        // 組件選項(xiàng)（沒(méi)有選項(xiàng)時(shí)將值設(shè)置為 null）
        "options": {
            "multiple": {
                "name": "同時(shí)展開(kāi)多個(gè)面板",
                "desc": "是否允許同時(shí)展開(kāi)多個(gè)面板",
                "type": "select",
                "default": false,
                "required": false,
                // 表單類型為 select 時(shí)通過(guò) dataList 設(shè)置 <option> 數(shù)據(jù)
                "dataList": [
                    {
                        "value": "false",
                        "title": "不啟用",
                        "selected": true
                    },
                    {
                        "value": true,
                        "title": "啟用"
                    }
                ]
            }
        },

        // 內(nèi)容
        "content": {
              // 內(nèi)容類型 Array 數(shù)組、Object（對(duì)象）
            "type": "Array",
            "item": {
                "title": {
                    "type": "text",
                    "comment": "面板標(biāo)題"
                },
                "content": {
                    "type": "html",
                    "comment": "面板內(nèi)容"
                }
            }
        }

        // 表單接口 - 測(cè)試接口，細(xì)節(jié)還會(huì)做調(diào)整
        // 提供的表單接口必須支持跨域調(diào)用，并返回 JSON 數(shù)據(jù)
        "forms": {
            "signin": {
                "url": "http://api.xxx.com/signin", // 提交數(shù)據(jù)的接口
                "type": "POST",
                "desc": "登錄表單，你可以在這里寫表單的描述信息",
                "fields": { // 表單字段，字段名稱應(yīng)該和返回?cái)?shù)據(jù)里的字段對(duì)應(yīng)
                    "username": {
                        "name": "用戶名",
                        "placeholder": "請(qǐng)使用郵箱",
                        "type": "text",
                        "default": "",
                        "required": true
                    },
                    "password": {
                        "name": "密碼",
                        "placeholder": "設(shè)置密碼",
                        "type": "text",
                        "default": "",
                        "required": true
                    },
                    "submit": {
                        "name": "提交信息",
                        "type": "submit",
                        "default": ""
                    }
                }
            },

            "signup": {
                "url": "http://api.xxx.com/signup",
                "type": "POST",
                "desc": "注冊(cè)表單，你可以在這里寫表單的描述信息",
                "fields": {
                    "username": {
                        "name": "用戶名",
                        "placeholder": "請(qǐng)使用郵箱",
                        "type": "text",
                        "default": "",
                        "required": true
                    },
                    "password": {
                        "name": "密碼",
                        "placeholder": "設(shè)置密碼",
                        "type": "text",
                        "default": "",
                        "required": true
                    }
                }
            }
        }
    },

    // 是否隱藏組件 - 此選項(xiàng)供云適配 WebIDE 使用
    "hidden": false
}
2.2 README.md

Web 組件使用說(shuō)明，包括 Web 組件 API 介紹、使用技巧、注意事項(xiàng)等。

2.3 HISTORY.md

Web 組件更新歷史記錄。

2.4 src 目錄

src 目錄包含 Web 組件的模板（hbs）、核心樣式（less）、交互（js）、圖標(biāo)（png）、主題文件。

src 目錄里的文件使用 Web 組件名稱作為文件名，主題使用 {Web 組件名}.{主題名}.less 形式命名。
  • {widget}.hbs: 模板，使用 handlebars
  • {widget}.less: 主題核心樣式，使用 less 編寫
  • {widget}.js: 組件交互
  • {widget}.png: 組件圖標(biāo)，50px * 50px
  • {widget}.default.less: 默認(rèn)主題
  • {widget}.xxx.less: 其他主題，可以任意多
2.4.1 模板 {widget}.hbs
  • data-am-widget="figure" 為統(tǒng)一標(biāo)識(shí)符；
  • .am-{Web 組件名} 為 Web 組件基礎(chǔ)標(biāo)識(shí)符，Web 組件的所有子元素、主題、狀態(tài)基于此命名； Web 組件基礎(chǔ)標(biāo)識(shí)符采用 am-{widget} 方式命名，子元素、主題、狀態(tài)采用 am-{widget}-{子元素|主題|狀態(tài)}，如 am-figure-hover 、 am-figure-bd 、 am-figure-active 、 am-figure-ios7。
  • 模板使用 {{#this}}..{{this}} 包裹（Web 組件使用時(shí)注冊(cè)為 Handlebars partial，通過(guò) {{> widget data}} 的形式調(diào)用。
{{#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> 標(biāo)簽，如需加載外部腳本需在 {widget}.js 中進(jìn)行。
如果需要保存用戶設(shè)置的選項(xiàng)，使用 data-am-{widget}-{option} 保存在模板中，然后在 {widget}.js 中通過(guò) attr('data-am-{widget}-{option}') 讀取。

2.4.2 核心樣式 {widget}.less
Web 組件樣式使用 less 編寫。
.am-{widget} {

  .hook-am-{widget};
}

.hook-am-{widget}() {}
樣式添加必要的 hook，方便用戶修改。

2.4.3 默認(rèn)主題 {widget}.defalt.less
.am-{widget}-default {

  .hook-am-{widget}-default;
}

.hook-am-{widget}-default() {}
2.4.4 其他主題 {widget}.xxx.less
.am-{widget}-xxx {

  .hook-am-{widget}-xxx;
}

.hook-am-{widget}-xxx() {}
2.4.5 Web 組件交互 {widget}.js

Amaze UI 使用 Seajs 、Zepto，Widget 的腳本需按照 Seajs 規(guī)范編寫。
如果要在 JS 中動(dòng)態(tài)插入外部樣式、腳本，必須在 load 事件觸發(fā)以后再執(zhí)行相關(guān)操作，以免影響網(wǎng)頁(yè)基本內(nèi)容載入。
define(function(require, exports, module) {
    // 按此方式使用 Zepto
    var $ = window.Zepto;

});

3.開(kāi)發(fā)腳手架

我們提供一個(gè)基于 Slush.js 的開(kāi)發(fā)腳手架，可以快速生成 Web 組件目錄及相關(guān)文件。
全局安裝 Slush:
npm install -g slush
全局安裝 slush-amuiwidget:
npm install -g slush-amuiwidget
在 Amaze UI 項(xiàng)目根目錄下面執(zhí)行:
slush amuiwidget

4.調(diào)試預(yù)覽

按照規(guī)范開(kāi)發(fā)完 Web 組件以后，可以在本地調(diào)試預(yù)覽組件。

在 Amaze UI 項(xiàng)目根目錄下執(zhí)行以下命令，安裝依賴：
npm install
全局安裝 nodemon：
npm install nodemon -g
安裝完成以后執(zhí)行：
gulp preview
然后在瀏覽器里打開(kāi) http://localhost:3008/#{component} 查看組件的效果，{component} 替換為組件名稱。

有樣式、腳本、配置文件修改時(shí)，修改完成以后刷新瀏覽器即可，nodemon 會(huì)自動(dòng)重啟 Node 服務(wù)。
以上內(nèi)容是否對(duì)您有幫助：
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號(hào)
微信公眾號(hào)

編程獅公眾號(hào)