自訂條件

SearchBuilder 可讓您建立自訂搜尋輸入，如外掛程式文件中所述。您也可以使用 searchBuilder.conditions 選項以及外掛程式 API，來自訂 SearchBuilder 內建的預設搜尋作業。本文檔討論執行此操作的技術，並定義您可以使用的內建搜尋作業。

SearchBuilder 使用一系列物件以清晰且結構化的方式儲存其條件。條件物件的第一層 (searchBuilder.conditions 或 $.fn.dataTable.SearchBuilder.conditions) 是一系列鍵，代表 DataTables 自動偵測到的欄類型。您可以在 columns.type 中找到更多詳細資訊。內建類型如下

• string
• date
• num
• num-fmt
• html
• html-num
• html-num-fmt

除了上述類型之外，當透過 datetime-moment 排序外掛程式使用 Moment.js 時，SearchBuilder 還有自己的 moment 屬性。還有一個非常相似的屬性，透過 datetime-luxon 排序外掛程式提供 Luxon 支援。還有一個 array 屬性，提供針對類似陣列的資料最佳化的條件。SearchBuilder 會自動偵測和處理這些欄中的資料，除了 array 條件，columns.type 必須設定為 array。也可以將您自己的欄類型新增至此物件，再次查看 columns.type，以取得有關如何執行此操作的更多資訊。

每個類型都是一個物件，定義可套用至該類型資料的條件。條件物件的實際名稱根本不會呈現給使用者，但命名它可能很有用，它可以幫助開發人員了解條件將會執行的操作 (例如，= 表示直接比較條件)。

考慮到所有這些，表示無論您想要如何變更條件，都會使用以下基本結構。此處使用 num 欄類型。

$('#example').DataTable({
    searchBuilder: {
        conditions: {
            num: {
                ...
            }
        }
    }
})

在本頁的其餘部分，將使用 num 條件來示範如何移除、編輯和建立條件。num 條件的標準如下

• = - 等於
• != - 不等於
• !null - 非 Null
• < - 小於
• <= - 小於或等於
• > - 大於
• >= - 大於或等於
• null - 空/null
• between - 介於
• !between - 不介於

注意：當 serverSide 選項設定為 true 時，不支援自訂條件。

移除條件

移除條件是編輯條件最直接的方法。如果您想要移除 !between 條件，例如，您只需在 searchBuilder.conditions.num 物件中將該條件設定為 null 即可

$('#example').DataTable({
    searchBuilder: {
        conditions: {
            num: {
                '!between': null
            }
        }
    }
})

或從所有表格中移除，請使用

delete $.fn.dataTable.SearchBuilder.conditions.num['!between'];

當選擇 num 類型的欄時，這會從呈現給使用者的條件清單中移除「不介於」條件。

編輯條件

每個條件內都有五個屬性可以編輯以影響行為。

conditionName

searchBuilder.conditions[type].conditionName 是在每個條件的條件選擇元素中顯示給使用者的 string 值。有關如何編輯選擇元素預留位置的文件，請參閱 language.searchBuilder.condition。若要將 > 條件的顯示字串從 Greater Than 編輯為 Above，您可以執行以下操作。

$('#example').DataTable({
    searchBuilder: {
        conditions: {
            num: {
                '>': {
                    conditionName: 'Above'
                }
            }
        }
    }
})

或針對所有表格

$.fn.dataTable.SearchBuilder.conditions.num['>'].conditionName = 'Above';

init

searchBuilder.condition[type].init 函式用於初始化任何需要從使用者擷取此條件值的 jQuery 元素。輸入元素的標準 searchBuilder.condition[type].init 函式如下所示。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                '>': {
                    init: function(that, fn, preDefined = null) {
                        // Declare the input element
                        let el = $('<input/>')
                            .addClass(that.classes.value)
                            .addClass(that.classes.input)
                            .on('input', function() { fn(that, this); });

                        // If there is a preDefined value then add it
                        if (preDefined !== null) {
                            $(el).val(preDefined[0]);
                        }

                        return el;
                    }
                }
            }
        }
    }
})

searchBuilder.condition[type].init 函式接受三個參數。

• that - 這是正在設定條件的準則實例。傳入此值可讓您存取可用的類別和內部屬性。請注意，在此處變更準則實例的內部屬性可能會導致未定義的行為。
• fn - 這是一個回呼函式，只要您想要進行搜尋，就必須呼叫此函式。對於輸入元素，搜尋應在每次輸入輸入元素時觸發。因此，該函式在輸入元素的 input 的偵聽器內呼叫。
• preDefined - 這是傳遞要設定或先前存在於值中的任何值的位置。SearchBuilder 會使用此值，因此即使您沒有設定預先定義的值，也必須到位。如果您不新增此值，則輸入元素可能會在每次按鍵時重設為空白。

searchBuilder.condition[type].init 函式會傳回 jQuery 元素，這些元素將用於從使用者擷取值。如果這樣，可以建立多個元素，那麼應該傳回元素陣列，而不是單個元素。在這裡也可以透過將元素附加到 div 來建立更複雜的結構。可能性真的非常廣泛。

以下範例顯示在套用一些自訂類別的 span 內傳回的輸入元素。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                '>': {
                    init: function(that, fn, preDefined = null) {
                        // Declare span wrapper for input
                        var span = $('<span/>')
                            .addClass('mySpan');

                        // Declare the input element
                        var el = $('<input/>')
                            .addClass(that.classes.value)
                            .addClass(that.classes.input)
                            .addClass('myInput')
                            .on('input', function() { fn(that, this); });

                        // If there is a preDefined value then add it
                        if (preDefined !== null) {
                            $(el).val(preDefined[0]);
                        }

                        // Append input element to span
                        $(span).append(el);

                        return span;
                    }
                }
            }
        }
    }
})

inputValue

searchBuilder.conditions[type].inputValue 函式用於從 searchBuilder.conditions[type].init 函式中建立的元素擷取值，如上所述。如果您已變更 searchBuilder.conditions[type].init 函式中涉及的元素，那麼您也必須對 searchBuilder.conditions[type].inputValue 函式進行一些變更，這是最有可能的。

以下是基於上述 searchBuilder.conditions[type].init 函式下列出的 jQuery 結構的範例。它接受兩個引數。

• el - 從 init 函式傳回的 jQuery 元素陣列。
• that - 目前正在考慮的準則實例。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                '>': {
                    inputValue: function(el, that) {
                        return [$(el[0]).children()[0].val()];
                    }
                }
            }
        }
    }
})

在這裡，我們只是存取 span 的唯一子項，也就是輸入元素。然後可以讀取並傳回其值。

isInputValid

searchBuilder.conditions[type].inputValue 函式用於判斷是否應將準則納入最終搜尋結果中。這是因為我們不想包含不完整或空白的準則，這可能會導致不想要的結果。searchBuilder.conditions[type].inputValue 函式接受 2 個參數

• el - 從 init 函式傳回的 jQuery 元素陣列。
• that - 目前正在考慮的準則實例。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                '>': {
                    isInputValid: function(el, that) {
                        return $(el[0]).children()[0].val().length > 0; // Check that the input element has some content
                    }
                }
            }
        }
    }
})

這裡正在檢查輸入元素，以查看輸入元素中是否有任何內容，然後才在搜尋過程中考慮該準則。如果您一直都想考慮該準則，而不論已收集的值如何，只需從此函式傳回 true 即可。

search

在搜尋表格以決定包含哪些結果時，會使用 searchBuilder.conditions[type].search 函式。它接受兩個參數。

• value - 這是要比較的表格中的值。SearchBuilder 會透過使用準則中的資料選擇元素自動選取正確的資料點。
• comparison - 這是從 searchBuilder.conditions[type].inputValue 函式傳回的值陣列。

讓我們以 between 條件為例。此條件透過兩個輸入元素接收兩個值。標準形式為

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                'between': {
                    search: function(value, comparison) {
                        // Depending on which input element is bigger will change the comparisons that need to be made
                        if (+comparison[0] < +comparison[1]) {
                            return +comparison[0] <= +value && +value <= +comparison[1];
                        }
                        else {
                            return +comparison[1] <= +value && +value <= +comparison[0];
                        }
                    }
                }
            }
        }
    }
})

此處表格中介於或位於比較值之間的任何值都會顯示在表格中。假設要編輯條件，以便只包含介於比較值之間而不是介於比較值上的值，則會進行以下小變更以編輯條件。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                'between': {
                    search: function(value, comparison) {
                        // Depending on which input element is bigger will change the comparisons that need to be made
                        if (+comparison[0] < +comparison[1]) {
                            return +comparison[0] < +value && +value < +comparison[1];
                        }
                        else {
                            return +comparison[1] < +value && +value < +comparison[0];
                        }
                    }
                }
            }
        }
    }
})

建立條件

建立條件非常簡單，只需將「編輯條件」章節中討論的所有屬性匯集在一起即可。以下將詳細說明如何建立「倍數」篩選器。要建立篩選器，我們必須將物件新增至 num 型別的物件中。這會像是以下這樣。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                'multiple': {
                    ...
                }
            }
        }
    }
})

conditionName

如先前所討論的，searchBuilder.conditions[type].conditionName 只是會在條件選擇元素中顯示的字串。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                'multiple': {
                    conditionName: 'Multiple Of'
                }
            }
        }
    }
})

init

對於 searchBuilder.conditions[type].init 函式，我們不需要使用太複雜的東西。一個簡單的輸入元素就可以很好地完成此目的。除了宣告 jQuery 輸入元素外，還需要為回呼函式設定監聽器，該回呼函式會引入搜尋功能，並建立重新載入 preDefined 值的方法。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                'multiple': {
                    conditionName: 'Multiple Of',
                    init: function (that, fn, preDefined = null) {
                        // Create input element and add the classes to match the SearchBuilder styles
                        var el = $('<input/>')
                            .addClass(that.classes.input)
                            .addClass(that.classes.value)

                        // Add the listener for the callback search function
                        $(el).on('input', function () {
                            fn(that, this);
                        });

                        // Set any preDefined values
                        if (preDefined !== null) {
                            el.val(preDefined[0]);
                        }

                        return el;
                    }
                }
            }
        }
    }
})

inputValue

同樣地，searchBuilder.conditions[type].inputValue 函式也可以相當簡單，我們只需要從輸入元素中提取值即可。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                'multiple': {
                    conditionName: 'Multiple Of',
                    init: function (that, fn, preDefined = null) {
                        // Create input element and add the classes to match the SearchBuilder styles
                        var el = $('<input/>')
                            .addClass(that.classes.input)
                            .addClass(that.classes.value)

                        // Add the listener for the callback search function
                        $(el).on('input', function () {
                            fn(that, this);
                        });

                        // Set any preDefined values
                        if (preDefined !== null) {
                            el.val(preDefined[0]);
                        }

                        return el;
                    },
                    inputValue: function (el, that) {
                        // return the value in the input element
                        return [$(el[0]).val()];
                    }
                }
            }
        }
    }
})

isInputValid

同樣地，searchBuilder.conditions[type].isInputValid 函式也可以相當簡單。只需要檢查輸入元素內是否有文字即可。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                'multiple': {
                    conditionName: 'Multiple Of',
                    init: function (that, fn, preDefined = null) {
                        // Create input element and add the classes to match the SearchBuilder styles
                        var el = $('<input/>')
                            .addClass(that.classes.input)
                            .addClass(that.classes.value)

                        // Add the listener for the callback search function
                        $(el).on('input', function () {
                            fn(that, this);
                        });

                        // Set any preDefined values
                        if (preDefined !== null) {
                            el.val(preDefined[0]);
                        }

                        return el;
                    },
                    inputValue: function (el, that) {
                        // return the value in the input element
                        return [$(el[0]).val()];
                    },
                    isInputValid: function (el, that) {
                        return $(el).val().length > 0;
                    }
                }
            }
        }
    }
})

search

searchBuilder.conditions[type].search 函式是條件需要最多「新」程式碼的地方。雖然這麼說，但它仍然會相當簡單。要找出一個數字是否為另一個數字的倍數，我們可以使用模數 (%) 運算子來檢查餘數是否為 0。

$('#example').DataTable({
    searchBuilder:{
        conditions:{
            num:{
                'multiple': {
                    conditionName: 'Multiple Of',
                    init: function (that, fn, preDefined = null) {
                        // Create input element and add the classes to match the SearchBuilder styles
                        var el = $('<input/>')
                            .addClass(that.classes.input)
                            .addClass(that.classes.value)

                        // Add the listener for the callback search function
                        $(el).on('input', function () {
                            fn(that, this);
                        });

                        // Set any preDefined values
                        if (preDefined !== null) {
                            el.val(preDefined[0]);
                        }

                        return el;
                    },
                    inputValue: function (el, that) {
                        // return the value in the input element
                        return [$(el[0]).val()];
                    },
                    isInputValid: function (el, that) {
                        return $(el).val().length > 0;
                    },
                    search: function (value, comparison) {
                        return value % comparison[0] === 0;
                    }
                }
            }
        }
    }
})

可以在這裡找到這個自訂條件的範例。

另一個可能感興趣的頁面是 SearchBuilder 的外掛程式頁面