预定义搜索

SearchBuilder 使您可以使用 searchBuilder.preDefined 选项设置预定义搜索，以便页面加载时应用搜索。这是通过声明条件和子组来完成的。

创建简单的预定义搜索

若要创建一个仅有一个条件的预定义搜索，请采用如下所示的常规 SearchBuilder 初始化，然后添加 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，这意味着如果不设置此属性，SearchBuilder 将默认为组的 AND 逻辑。此属性可以采用的唯一其他值为如上所示的 OR。为了简单起见，我们不设置逻辑属性并使用默认值。

SearchBuilder.Criteria 的 criteria 参数采用两种不同类型的对象。这些对象既可以用于子组（在这种情况下，结构与顶层相同）也可以用于条件。本页下方对此有更详细的说明，现在让我们只添加一个单一条件对象。以下配置将声明一个预定义搜索，其中 Age 列必须等于 50。

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

criteria.data 属性用于指定应将筛选应用到其上的列。如果您此处未定义任何内容，则条件将显示为空。同样，如果提供的字符串与列标题不匹配，则不会选择该字符串，并且条件将保持空白。

criteria.condition 属性用于指定在筛选数据集时应选择并使用的条件。如果未设置该属性，则不应用任何条件或值，但如果提供了数据属性，则该数据仍将在数据选择中预设。如果提供的字符串与该列类型可用于的任何条件不匹配，这也适用。

criteria.value 属性用于指定在过滤数据集时应使用的值。这是一个数组，因为某些条件（例如“介于”）可能需要两个输入。值将按其在数组中的顺序应用于输入。即使此属性未定义，数据和条件选择元素仍可能进行选择。

自 SearchBuilder 版本 1.2.0 起，支持 serverSide 处理。在这种情况下，criteria.value 属性将以几种不同的方式发生变化。首先，如果列是数字类型，则此处返回的值将去除非数字字符，以便仅保留数字和小数位。这是为了允许服务器端集成轻松实现其条件。此处发生的第二个突变是删除 criteria.value 属性，将其替换为 2 个新属性 searchBuilder.preDefined.criteria.value1 和 searchBuilder.preDefined.criteria.value2。这些是 criteria.value 数组中的第一个和第二个值。这样做是为了使与 .NET 库的界面更加顺畅。SearchBuilder 在实施预定义搜索时会自动执行此操作。

版本 1.2.0 的另一个更改是添加了 criteria.type 属性。使用服务器端处理时，仅在 searchBuilder.preDefined 对象中才需要此属性。这意味着服务器可以知道应用搜索的字段类型。在某些情况下，这是必需的，因为不同列类型之间某些条件的行为略有不同。

为支持服务器端处理而进行的最后更改是添加 criteria.origData 属性。这应该设置为原始字段名的值，以便服务器端脚本知道将条件应用于哪个字段。此属性和 criteria.data 都是必需的，因为在显示 DataTable 时，这两个属性不一定相等。

考虑到所有这些因素，预定义的条件看起来应该更像这样。

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

使用多个条件的预定义搜索

可以通过向组中添加更多条件来创建更复杂的搜索，方法是按照上面讨论的方式将条件添加到 criteria 数组中。以下配置将导致一个预定义搜索，其中年龄必须大于 50 且 办公室 必须等于 Edinburgh。

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

更改组的逻辑运算符

应用于组的初始逻辑运算符可以通过设置 SearchBuilder.Criteria 对象的 logic 属性轻松更改。先前的示例已进行编辑，使得预定义搜索现在意味着仅包含 年龄 大于 50 或 办公室 等于 Edinburgh 的记录。

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

声明子组

还可以声明子组，它们可以包含自己的条件并设置自己的逻辑。可以通过将与 SearchBuilder.Criteria 结构相同的对象（如 searchBuilder.preDefined）添加到 alongside 任何其他条件的 criteria 数组中来完成此操作。以下示例是先前示例的修改版本。现在，爱丁堡筛选器将出现在一个子组中。

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

SearchBuilder 有 2 个与预定义搜索相关的 API 方法。

searchBuilder.getDetails() - 返回与用于 searchBuilder.preDefined 的结构相同的对象
searchBuilder.rebuild() - 获取的参数与 searchBuilder.preDefined 的结构相同，并将其应用到 SearchBuilder。

这两个方法非常匹配，因为它们允许你保存特定点并稍后重新加载它。你还可以利用这两个方法在后台实现 SearchBuilder，而不用实际向最终用户显示它。这样，开发者在不显示 SearchBuilder UI 的情况下也能实现他们自己的高级搜索。你可能已经考虑好自己的 UI，也可以使用按钮实现设置搜索。

searchBuilder.getDetails() 返回与上面讨论的结构相同的对象，该对象表示当前显示的 SearchBuilder 结构。如果你计划构建大型预定义搜索，那么生成它的一个好方法是在 SearchBuilder 中手动创建它，然后运行此方法。

searchBuilder.rebuild() 获取的参数与 searchBuilder.getDetails() 的输出相同，因此这两个方法是相辅相成的。此方法可以在任何时候将搜索应用于 SearchBuilder。在使用预定义搜索并向其传递相同对象时，创建一个复位按钮可能是个不错的用法。如果没有提供任何参数，则 SearchBuilder 将被完全清除。