DIV CSS 佈局教程網

封裝自己的 JS 組件:從擴展 jQuery.ajax 到寫一個 combobox
編輯:關於JavaScript     

寫專案寫久了,總會遇到同一段程式碼被複製到第八個檔案裡的時刻。與其繼續複製,不如把它變成組件。本文從兩個層次談這件事:一是擴展既有組件,二是打造自己的組件。

一、擴展已存在的組件

1. 需求場景

ajax 呼叫大概長這樣:

 $.ajax({
    type: "post",
    url: "/User/Edit",
    data: { data: JSON.stringify(postdata) },
    success: function (data, status) {
        if (status == "success") {
            toastr.success('提交數據成功');
            $("#tb_aaa").bootstrapTable('refresh');
        }
    },
    error: function (e) {},
    complete: function () {}
}); 

問題來了:每寫一次就得附上一個空的 error: function(e){},但我其實希望每個請求失敗時都能把錯誤訊息顯示給使用者看。難道要在每個地方都寫一遍錯誤處理?

2. 兩種解法與其取捨

最直覺的做法是把 $.ajax({}) 再包一層,在這個公共方法裡定義 error。可行,但不完美:一是在 jQuery 之上再包一層,多繞一圈;二是改變了呼叫者的習慣,之後都得照我的規則寫,不能直接用原生的 $.ajax({})。

更好的做法是直接擴展原生的 $.ajax,讓呼叫方式完全不变。

3. 用 $.extend 擴展

 (function ($) {
    // 1. 保留原始的 $.ajax
    var _ajax = $.ajax;

    $.ajax = function (options) {
        // 2. 定義預設的處理函式
        var fn = {
            error: function (XMLHttpRequest, textStatus, errorThrown) {
                toastr.error(XMLHttpRequest.responseText, '錯誤消息', {
                    closeButton: true,
                    timeOut: 0,
                    positionClass: 'toast-top-full-width'
                });
            },
            success: function (data, textStatus) {},
            beforeSend: function (XHR) {},
            complete: function (XHR, TS) {}
        };

        // 3. 呼叫者有自訂,就尊重呼叫者的
        if (options.error)     { fn.error = options.error; }
        if (options.success)   { fn.success = options.success; }
        if (options.beforeSend){ fn.beforeSend = options.beforeSend; }
        if (options.complete)  { fn.complete = options.complete; }

        // 4. 用 $.extend 把處理函式併回參數
        var _options = $.extend(options, {
            error: function (XMLHttpRequest, textStatus, errorThrown) {
                fn.error(XMLHttpRequest, textStatus, errorThrown);
            },
            success: function (data, textStatus) {
                fn.success(data, textStatus);
            },
            beforeSend: function (XHR) {
                fn.beforeSend(XHR);
            },
            complete: function (XHR, TS) {
                fn.complete(XHR, TS);
            }
        });

        // 5. 交給原始方法執行
        _ajax(_options);
    };
})(jQuery); 

讀不懂的話,先搞清 $.extend() 在做什麼。

官方文件給的兩個例子最能說明問題。

例一:

 var settings = { validate: false, limit: 5, name: "foo" };
var options  = { validate: true, name: "bar" };
$.extend(settings, options);

結果:

 settings == { validate: true, limit: 5, name: "bar" }

例二:

 var empty    = {};
var defaults = { validate: false, limit: 5, name: "foo" };
var options  = { validate: true, name: "bar" };
var settings = $.extend(empty, defaults, options);

結果:

 settings == { validate: true, limit: 5, name: "bar" }
empty    == { validate: true, limit: 5, name: "bar" }

也就是說:合併多個物件,同名屬性由後者覆蓋,其餘照單全收。第一個參數是接收結果的目標物件,後面依序是被併入的来源。

理解這點,回頭看擴展 ajax 的程式碼就通了,步驟只有三步:

1. 定義一組預設的 error(以及 success、beforeSend、complete)處理函式。

2. 判斷呼叫者是否自訂了同名處理函式,有則覆蓋預設值。

3. 用 $.extend() 把這組函式併進 options,再交給原始的 ajax 執行。

對使用者來說完全無感:一樣寫 $.ajax({}),不特別處理錯誤時就有統一的提示。

4. 擴展的意義

擴展讓你能在既有組件上加入與自家業務相關的行為,而呼叫方式維持原樣,避免了「再包一層」帶來的臃腫。這比 fork 一份原始碼再改要好維護得多。

二、打造自己的組件

接著做一個簡單但具代表性的例子:把「從後端取資料填進 select」這件事封裝成 combobox。

1. 完整程式碼

 (function ($) {
    // 1. 定義 jQuery 擴展方法 combobox
    $.fn.combobox = function (options, param) {
        if (typeof options == 'string') {
            return $.fn.combobox.methods[options](this, param);
        }

        // 2. 合併預設參數與使用者參數
        options = $.extend({}, $.fn.combobox.defaults, options || {});

        // 3. 寫入初始狀態
        var target = $(this);
        target.attr('valuefield', options.valueField);
        target.attr('textfield', options.textField);
        target.empty();

        var option = $('<option></option>');
        option.attr('value', '');
        option.text(options.placeholder);
        target.append(option);

        // 4. 有 data 用 data,否則發 ajax
        if (options.data) {
            init(target, options.data);
        } else {
            options.onBeforeLoad.call(target, options.param);
            if (!options.url) return;
            $.getJSON(options.url, options.param, function (data) {
                init(target, data);
            });
        }

        function init(target, data) {
            $.each(data, function (i, item) {
                var option = $('<option></option>');
                option.attr('value', item[options.valueField]);
                option.text(item[options.textField]);
                target.append(option);
            });
            options.onLoadSuccess.call(target);
        }

        target.unbind("change");
        target.on("change", function (e) {
            if (options.onChange) return options.onChange(target.val());
        });
    };

    // 5. 對外方法
    $.fn.combobox.methods = {
        getValue: function (jq) {
            return jq.val();
        },
        setValue: function (jq, param) {
            jq.val(param);
        },
        load: function (jq, url) {
            $.getJSON(url, function (data) {
                jq.empty();
                var option = $('<option></option>');
                option.attr('value', '');
                option.text('請選擇');
                jq.append(option);
                $.each(data, function (i, item) {
                    var option = $('<option></option>');
                    option.attr('value', item[jq.attr('valuefield')]);
                    option.text(item[jq.attr('textfield')]);
                    jq.append(option);
                });
            });
        }
    };

    // 6. 預設參數
    $.fn.combobox.defaults = {
        url: null,
        param: null,
        data: null,
        valueField: 'value',
        textField: 'text',
        placeholder: '請選擇',
        onBeforeLoad: function (param) {},
        onLoadSuccess: function () {},
        onChange: function (value) {}
    };
})(jQuery); 

2. 使用方式

用法一:遠端取資料並初始化

 <select id="sel_search_plant" class="form-control"></select>
 $(function () {
    $('#sel_search_plant').combobox({
        url: '/apiaction/Plant/Find',
        valueField: 'TM_PLANT_ID',
        textField: 'NAME_C'
    });
}); 

用法二:取值與設值

 var strSelectedValue = $('#sel_search_plant').combobox("getValue");
$('#sel_search_plant').combobox("setValue", "aaa"); 

坦白說,對一個原生 select 而言,getValue / setValue 意義不大——直接 $('#sel_search_plant').val() 就能解決。這裡只是為了示範「字串參數代表呼叫方法」這個模式。如果封裝的是 select2 或 multiselect 這類複合組件,這組 API 就非常必要了。

3. 逐段拆解語法

(1)IIFE 寫法

 (function ($) {
    // 組件邏輯
})(jQuery);

第一次看到這種寫法容易困惑,拆開就懂了:

 var fn = function ($) {
    // 組件邏輯
};
fn(jQuery);

也就是先定義一個函式、立刻呼叫它,並把 jQuery 當實參傳進去。這麼做的好處是函式內部的 $ 保證是 jQuery,不必擔心與其他函式庫的 $ 衝突。

(2)掛到 jQuery 原型上

 $.fn.combobox = function (options, param) {};

這是把自訂方法掛到 jQuery 物件上,之後就能寫成 $("#id").MyJsControl({}) 的形式。$.fn 就是 jQuery.prototype 的別名。

(3)合併參數

 options = $.extend({}, $.fn.combobox.defaults, options || {});

這裡傳入空物件作為目標,意思是「不要污染 defaults 本身」,只把 defaults 與使用者參數合併成一個新物件。options || {} 則是防止使用者完全沒傳參時發生錯誤。

(4)預設參數列表

 $.fn.combobox.defaults = {
    url: null, param: null, data: null,
    valueField: 'value', textField: 'text', placeholder: '請選擇',
    onBeforeLoad: function (param) {},
    onLoadSuccess: function () {},
    onChange: function (value) {}
};

使用者沒傳的項目就落在這裡。如果你翻過其他 Bootstrap 組件的原始碼,會發現幾乎每個都有這麼一個 defaults——這是 jQuery 生態的慣例。

舉兩個例子:

bootstrap 上傳組件

bootstrap table 組件

看出規律了嗎?「IIFE 包裝 + 掛 $.fn + defaults 合併 + 字串分派方法 + 回呼鉤子」,這五件事就是 jQuery 組件的標準骨架。掌握它,自己封一個並不難。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved