預定義搜尋

搜尋建構器讓您可以使用 searchBuilder.preDefined 選項設定預定義搜尋，讓頁面載入時即套用搜尋。這可以透過宣告條件和子群組來完成。

建立簡單的預定義搜尋

若要建立只有一個條件的預定義搜尋，請採用下方所示的標準搜尋建構器初始化，並新增 searchBuilder.preDefined 物件，該物件以 SearchBuilder.Criteria 給定的物件格式定義搜尋條件。

new DataTable('#myTable', {
    layout: {
        top: {
            searchBuilder: {
                preDefined: {
                    // We are going to be working here
                }
            }
        }
    }
});

然後可以透過新增 SearchBuilder.Criteria 的屬性來定義初始搜尋條件，以建立頂層群組。

new DataTable('#myTable', {
    layout: {
        top: {
            searchBuilder: {
                preDefined: {
                    criteria: [
                        // Criteria or sub-group objects go here
                    ],
                    logic: 'OR' // Use `OR` logic for the group
                }
            }
        }
    }
});

logic 屬性的預設值為 AND，這表示如果未設定此屬性，則搜尋建構器會將群組的邏輯預設為 AND。此屬性唯一可以採用的其他值為如上所示的 OR。為了簡單起見，我們不會設定邏輯屬性並使用預設值。

SearchBuilder.Criteria 的 criteria 參數採用兩種不同的物件類型。它們可以是子群組，在這種情況下，結構與頂層相同，或者可以是條件。頁面下方有更多詳細資訊，現在讓我們只新增一個條件物件。下列設定會宣告一個預定義搜尋，其中 Age 欄位必須等於 50。

searchBuilder: {
    preDefined: {
        criteria: [
            {
                data: 'Age',
                condition: '=',
                value: [50]
            }
        ]
    }
}

criteria.data 屬性用於指定應套用篩選的欄位。如果您未在此處定義任何內容，條件將顯示為空白。同樣地，如果提供的字串與欄位標題不符，則不會選取該字串，條件將保持空白。

criteria.condition 屬性用於指定在篩選資料集時應選取和使用的條件。如果未設定，則不會套用任何條件或值，但是如果提供了資料屬性，則它仍會預設在資料選取中。如果提供的字串與該欄位類型可用的任何條件不符，也會適用這種情況。

criteria.value 屬性用於指定在篩選資料集時應使用的值。這是一個陣列，因為某些條件（例如「介於」）可能需要兩個輸入。這些值將按照它們在陣列中的順序套用至輸入。即使此屬性未定義，資料和條件選取元素仍然可以進行選取。

自從搜尋建構器 1.2.0 版起，支援 serverSide 處理。在這種情況下，criteria.value 屬性會以幾種不同的方式變更。首先，如果欄位是數字類型，則此處傳回的值會去除非數字字元，因此只會留下數字和小數位數。這是為了讓伺服器端整合能夠輕鬆實作其條件。此處發生的第二個變更是移除 criteria.value 屬性，並以 2 個新屬性 searchBuilder.preDefined.criteria.value1 和 searchBuilder.preDefined.criteria.value2 取代。這些是 criteria.value 陣列中的第一個和第二個值。這樣做的目的是讓與 .NET 函式庫的介面更順暢。在實作預定義搜尋時，搜尋建構器會自動執行此操作。

1.2.0 版的另一個變更是新增了 criteria.type 屬性。僅在使用伺服器端處理時，才需要在 searchBuilder.preDefined 物件中使用此屬性。這表示伺服器可以判斷正在套用搜尋的欄位類型。在某些情況下，這是必需的，因為某些條件的行為在欄位類型之間略有不同。

為支援伺服器端處理而進行的最後一項變更是新增了 criteria.origData 屬性。應將此屬性設定為原始欄位名稱的值，以便伺服器端指令碼知道要將條件套用至哪個欄位。這是因為當顯示 DataTable 時，兩者不一定相等，所以同時需要此屬性和 criteria.data。

考慮到所有這些，預定義條件應如下所示。

searchBuilder: {
    preDefined: {
        criteria: [
            {
                condition: '=',
                data: 'Age',
                origData: 'age',
                type: 'num',
                value: [50]
            }
        ]
    }
}

具有多個條件的預定義搜尋

可以透過在群組中新增更多條件（以與上述相同的方式新增至 criteria 陣列）來建立更複雜的搜尋。下列設定會產生預定義搜尋，其中 Age 必須大於 50，而 Office 必須等於 Edinburgh。

searchBuilder: {
    preDefined: {
        criteria: [
            {
                data: 'Age',
                condition: '>',
                value: [50]
            },
            {
                data: 'Office',
                condition: '=',
                value: ['Edinburgh']
            }
        ]
    }
}

變更群組的邏輯運算子

可以透過設定 SearchBuilder.Criteria 物件的 logic 屬性來輕鬆變更套用至群組的初始邏輯運算子。先前範例已編輯，因此預定義搜尋現在將僅包含 Age 大於 50 或 Office 等於 Edinburgh 的記錄。

searchBuilder: {
    preDefined: {
        criteria: [
            {
                data: 'Age',
                condition: '>',
                value: [50]
            },
            {
                data: 'Office',
                condition: '=',
                value: ['Edinburgh']
            }
        ],
        logic: 'OR'
    }
}

宣告子群組

也可以宣告子群組，這些子群組能夠保留自己的條件並設定自己的邏輯。這可以透過將具有與 searchBuilder.preDefined 相同的 SearchBuilder.Criteria 結構的物件新增至 criteria 陣列（與任何其他條件一起）來完成。以下範例是先前範例的編輯。現在，Edinburgh 篩選條件將顯示在子群組中。

searchBuilder: {
    preDefined: {
        criteria: [
            {
                data: 'Age',
                condition: '>',
                value: [50]
            },
            {
                criteria:[
                    {
                        data: 'Office',
                        condition: '=',
                        value: ['Edinburgh']
                    }   
                ],
                logic: 'AND'
            }
        ],
        logic: 'OR'
    }
}

儘管這與之前的行為完全相同，但現在我們可以向子群組新增另一個條件。新的預定義搜尋將傳回 Age 大於 50 的記錄，或 Office 欄位等於 Edinburgh 且 'Name' 等於 Dai Rios 的記錄。

searchBuilder: {
    preDefined: {
        criteria: [
            {
                data: 'Age',
                condition: '>',
                value: [50]
            },
            {
                criteria:[
                    {
                        data: 'Office',
                        condition: '=',
                        value: ['Edinburgh']
                    },
                    {
                        data: 'Name',
                        condition: '=',
                        value: ['Dai Rios']
                    }     
                ],
                logic: 'AND'
            }
        ],
        logic: 'OR'
    }
}

criteria 陣列的遞迴結構表示可以建立所需深度的子群組。

API

搜尋建構器具有 2 個與預定義搜尋相關的 API 方法。

searchBuilder.getDetails() - 傳回與 searchBuilder.preDefined 使用的結構相同的物件
searchBuilder.rebuild() - 採用與 searchBuilder.preDefined 相同結構的物件作為引數，並將其套用至搜尋建構器。

這兩者非常適合搭配使用，因為它們讓您可以儲存特定點，然後稍後重新載入。您也可以利用這些來在背景中實作搜尋建構器，而實際上不將其顯示給最終使用者。這讓開發人員能夠實作自己的進階搜尋，而無需顯示搜尋建構器 UI。您可能會有自己的 UI，或者可以使用按鈕來實作設定的搜尋。

searchBuilder.getDetails() 傳回與上述討論的結構相同的物件，該物件代表目前顯示的搜尋建構器結構。如果您計畫建構大型預定義搜尋，則自動產生它的好方法是手動在搜尋建構器中建立它，然後執行此方法。

searchBuilder.rebuild() 採用與 searchBuilder.getDetails() 的輸出相同的引數，這就是為什麼這兩者很適合搭配使用的原因。此方法可以在任何時候將搜尋套用至搜尋建構器。一個很好的用法是在使用預定義搜尋時建立重設按鈕，並將相同的物件傳遞給它。如果未提供引數，則會完全清除搜尋建構器。