amazeui學習筆記二（進階開發5）--Web 組件開發規範Rules

amazeui學習筆記二（進階開發5）--Web 組件開發規範Rules

1、總結

一、見名知意：見那些class名字知意，見函數名知意，見文件名知意 例如（HISTORY.md Web 組件更新歷史記錄。）

 

 

2、Web 組件開發規範Rules

目錄

• Web 組件樣式組織
• 目錄結構及說明
  • package.json
  • README.md
  • HISTORY.md
  • src 目錄
• 開發腳手架
• 調試預覽

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 服務。