【Amaple教程】5. 插件

時間 2019-11-10

標籤 Amaple教程插件简体版

原文原文鏈接

Amaple 擁有很是強大插件功能，這也是它的突出功能之一，Amaple插件通常表現爲功能塊（函數）或功能塊（包含一系列函數和屬性的Object對象），它除了支持Amaple規範定義的插件外，還支持全部 AMD (點擊瞭解詳情)和 IIFE (點擊瞭解詳情)規範的插件，在 rollup 、 webpack 、 browserify 等模塊打包工具流行的今天，這也意味着幾乎全部的第三方js庫均可以與Amaple協同運做，同時也支持舊式的iife格式js庫。javascript

定義並安裝Amaple規範的插件

在安裝Amaple規範的插件前，咱們需定義一個特定格式的pluginDefinition（插件定義對象）供Amaple安裝，這個對象必須包含name屬性和build函數，分別表示插件名與構建函數，此構建函數返回的值將做爲插件實體。而後使用am.install(pluginDefinition)並傳入插件安裝對象pluginDefinition進行安裝：java

// 插件定義對象
const pluginDefinition = {
    name : "switch",   // 定義插件名，命名規則與變量名的規則相同

    // 構建函數，它要求返回一個插件實體
    // 無效返回值（undefined、null、0、false等）將會拋出錯誤
    // build函數中的this指向的是am對象，因此你可使用它進行組件定義或am屬性的擴展
    build : function () {
        var state = "OFF";

        return {
            press: function () {
                 return state === "OFF" ? "ON" : "OFF";
            }
        };
    }
};

// 調用後插件將會被安裝，此時就完成了一個名爲switch的插件
// 它是一個含有`press`函數的Object對象。
am.install (pluginDefinition);

在Amaple中，插件也能夠像模塊與組件文件同樣編寫在獨立的js文件中，它也提供了相應的插件載入機制。如咱們可將上面的插件定義代碼單獨放到/plugin/switch.js文件中。webpack

載入插件

不管是 Amaple 規範、 amd 和 iife 規範的插件在Amaple中均可以以單獨文件的形式存在，對於這些插件咱們須要載入它們纔可以使用，咱們可在am.startRouter函數的參數內添加plugin屬性指定項目依賴的插件路徑信息，這樣Amaple將會自動加載這些插件文件，plugin具體配置以下：git

am.startRouter( {
    // ...
    baseURL : {
        // ...

        // 可爲插件文件設置base路徑，全部的插件文件請求路徑都將基於「/plugin」目錄，不設置時默認爲「/」
        plugin: "/plugin"
    },

    // plugin的值爲一個數組，經過它來指定項目中依賴的全部插件
    // 如下分別表示插件載入的4種方式
    plugin: [

        // ①.插件路徑字符串，適用於amaple規範的單獨文件插件
        //   如上面定義的switch插件可以使用此方式載入，加載路徑依賴baseURL
        "siwtch",

        // ②.插件定義對象pluginDefinition，直接傳入此對象後將會安裝此插件
        //    與amaple規範的單獨文件插件相比，不需調用am.install函數。
        //    這對於webpack等模塊化環境下很是有用，你能夠import任意js庫並經過build函數retuen它進行安裝
        { name: "switch", build: function () { ... } },

        // ③.amd規範js庫，支持amd規範的全部js庫均可以這樣載入並做爲amaple的插件使用
        //    url依賴baseURL，且url值爲「http://」、「https://」開頭時可直接載入外網js庫
        { format: "amd", name: "anime", url: "amd/animejs" },

        // ④.iife規範js庫，iife規範下將會使用global的值做爲全局對象名，並在window對象下尋找它，未定義global時會使用name的值代替global值進行尋找
        //    url依賴baseURL，且url值爲「http://」、「https://」開頭時可直接載入外網js庫
        { format: "iife", name: "lodash", global: "_", url: "iife/lodash" }
    ]
} );

【注意】雖然插件的載入是異步執行的，但請沒必要擔憂，它們會根據 plugin數組按順序進行安裝，這對於擁有依賴的插件是頗有用的，你能夠在 plugin屬性中先載入被依賴的插件，這樣，依賴它們的插件就能夠順利獲取到它們了。

使用插件

被載入的插件可在模塊、組件以及其餘插件中使用，你能夠在模塊、組件的全部生命週期函數以及插件的build函數中直接經過插件名接收插件實體對象，這也是極爲簡單的，如在一個模塊中使用 switch 插件：github

new am.Module ( {

    // 使用插件名直接接收，switch插件將會自動注入到init、mounted函數中
    // 其餘生命週期函數中也使用此方法注入對應插件實體
    init : function ( switch ) { ... },
    mounted : function ( switch ) { ... },
    // ...
} );

預約義插件

Amaple框架中有util、http、event、promise四個預約義插件，它們能夠直接在生命週期函數中接收，而不須要在配置對象plugin屬性中顯式引入。web

此小節主要介紹四個預約義插件的使用方法，但插件使用在Amaple中並非必須的，因此若是你想更快看完此教程，可先跳過此小節的學習。

# 工具函數插件util

類型：Object

描述：

js工具函數集合segmentfault

對象屬性：

type(arg: any)

類型：Function
描述：判斷數據類型，與「typeof」關鍵字相比，它還能夠判斷null和Array兩個數據類型
參數：api
- arg|any：需判斷類型的數據
返回值：傳入參數的數據類型

foreach(target: ArrayLike|Object, callback: Function)

類型：Function
描述：循環遍歷一個對象，使用方法與array.forEach相似。但它還能夠遍歷類數組如Node.childNodes、Node.attributes等，且當傳入的參數不可遍歷時將直接返回。參數callback爲循環遍歷時的回調函數，它分別接收遍歷項的值、遍歷下表、遍歷變量自己三個參數，當回調函數返回false時將break結束本次循環，並且此時foreach執行結束後也將會返回一個false，這在結束多層循環遍歷時頗有用，開發者能夠經過「return foreach(...)」再次推出上層循環。
參數：數組
- target|ArrayLike、Object：循環遍歷的目標變量值
- callback|Function：循環遍歷時的回調函數，它分別接收遍歷項的值、遍歷下表、遍歷變量自己三個參數，返回false可結束循環遍歷
返回值：無

isEmpty(object: Array|Object)

類型：Function
描述：判斷一個數組或對象是否爲空，檢查對象時它只會檢查該對象自己的成員屬性
參數：promise
- object|Array、Object：待判斷的數組會對象
返回值：空時爲true，不空時爲false

isPlainObject (object: Object)

類型：Function
描述：判斷一個對象是否爲純粹的Object數據對象
參數：
- object|Object：待判斷對象
返回值：是則返回true，不是則返回false

guid()

類型：Function
描述：獲取惟一標識
參數：無
返回值：惟一標識

# Ajax插件http

類型：Object

描述：

Ajax網絡請求插件，它的對象函數get、post、request都實現了
Promise/A+規範，在定義回調函數上，除了普通的異步回調函數傳參外，還支持使用鏈式調用的方式來實現異步回調函數的調用，例如http.get(...).done(function(result) {...}).fail(function(error){...})或http.get(...).then(function(result){}, function(error){...})，來指定成功與失敗的回調函數，若是在Promise對象上和回調函數傳參上同時指定了回調函數，則會執行傳參回調函數。成功回調函數successHandler將接收的參數爲響應內容response、響應狀態碼status，響應狀態內容statusText及自定義XHR對象amXHR，amXHR對象屬性詳細以下：

setRequestHeader(header: String, value: String)
- 描述：設置請求頭，請求執行前設置有效
- 參數：
  - header|String：請求頭名稱
  - value|String：請求頭值
- 返回值：無
getResponseHeader(header: String)
- 描述：獲取返回頭信息，請求響應後可獲取
- 參數：
  - header|String：返回頭名稱
- 返回值：對應的返回頭信息
getAllResponseHeaders()
- 描述：獲取全部返回頭信息，請求響應後可獲取
- 參數：無
- 返回值：全部返回頭信息
overrideMimeType(mimetype: String)
- 描述：設置mimeType，請求執行前設置有效
- 參數：
  - mimetype|String：mimeType值
- 返回值：無
abort(statusText: String)
- 描述：觸發請求中斷回調，在支持請求中斷且請求響應前有效
- 參數：
  - statusText|String：中斷信息，開發者可在中斷回調中的statusText獲取到
- 返回值：無

http插件對象函數：

get(url: String, args?: String|Object, callback?: Function, dataType?: String)

- 類型：Function
- 描述：執行Ajax GET請求，它將返回一個Promise對象用於以鏈式調用的方式來實現異步回調函數
- 參數：
    - url|String：請求url
    - args?|String、Object：get提交的數據，此參數傳入String時以「k1=v1&k2=v2」的格式傳入，傳入Object時爲一個數據對象
    - callback?|Function：請求成功回調函數，。它
    - dataType?|String：設置響應內容的格式，可選爲「TEXT/JSON/SCRIPT/JSONP」（可忽略大小寫），默認爲「TEXT」
- 返回值：Promise對象

post(url: String, args?: String|Object, callback?: Function, dataType?: String)

- 類型：Function

- 描述：執行Ajax POST請求，它將返回一個Promise對象用於以鏈式調用的方式來實現異步回調函數
- 參數：
    - url|String：請求url
    - args?|String、Object：post提交的數據，此參數傳入String時以「k1=v1&k2=v2」的格式傳入，傳入Object時爲一個數據對象
    - callback?|Function：請求成功回調函數，若是傳入此參數則以它爲回調函數執行。它將接收的參數爲響應內容response、響應狀態碼status，響應狀態內容statusText及自定義XHR對象amXHR
    - dataType?|String：設置響應內容的格式，可選爲「TEXT/JSON/SCRIPT/JSONP」（可忽略大小寫），默認爲「TEXT」
- 返回值：Promise對象

request(options: Object)

- 類型：Function
- 描述：執行Ajax請求，相比於get、post函數，它能夠完成更復雜的請求操做，且此函數可直接在data屬性中傳入帶有上傳文件的form表單元素或FormData對象實現文件上傳操做，當在低版本瀏覽器使用form表單元素上傳時將自動使用隱藏iframe刷新的方式上傳，但在支持FormData對象的瀏覽器中自動使用FormData對象實現文件上傳
- 參數：
    - options|Object：可選屬性詳情以下：
        - method?|String：請求類型，GET或POST，大小寫不敏感，默認爲GET
        - url|String： 請求地址
        - data?|String：提交的額外參數，可選爲格式爲k1=v1&k2=v2的字符串、{k1:v1, k2:v2}的數據對象、FormData對象及form表單元素對象，當data爲form對象時，若是也提供了src參數則優先使用src參數當作url進行提交
        - async?|Boolean：是否異步請求，默認爲true
        - cache?|Boolean：請求緩存，若是爲false，則每次都會發送請求，默認爲true
        - contentType|String：請求參數編碼
        - dataType?|String：返回的數據類型，TEXT/JSON/SCRIPT/JSONP，大小寫不敏感，默認爲TEXT
        - username?|String：服務器認證用戶名
        - password?|String：服務器認證密碼
        - mimeType?|String：設置mimeType
        - headers?|Object：額外的請求頭信息，爲一個對象
        - timeout?|Number：請求超時時間
        - beforeSend?|Function：請求發送前回調，函數參數爲amXHR對象、當前配置對象options
        - success?|Function：請求成功後回調，函數參數爲data、statusText、amXHR對象
        - error?|Function：請求失敗後回調，函數參數爲amXHR對象、statusText
        - complete?|Function：請求完成後回調，函數參數爲amXHR對象、statusText
        - abort?|Function：請求中斷後回調，函數參數爲statusText
- 返回值：Promise對象

# 自定義事件插件event

類型：Object

描述：

自定義事件對象，支持跨模塊觸發事件

對象函數：

on(types: String, listener: Function, once?: Boolean)

類型：Function
描述：綁定自定義事件，參數types以空格分隔開可同時綁定一個回調函數到多個事件類型上
參數：
- types|String：自定義事件名稱，使用空格隔開可同時綁定一個監聽函數到多個事件類型上listener|Function：事件回調函數
- once?|Boolean：是否只能觸發一次，設置爲true時，觸發一次回調後將自動解除綁定
返回值：無