Filter 属性

  • 项目

指示 Recordset 中数据的筛选器。

设置和返回值

设置或返回 Variant 值，该值可以包含以下项之一：

  • 条件字符串：由使用 AND 或 OR 运算符连接的一个或多个单个子句组成的字符串。

  • 书签数组：指向 Recordset 对象中的记录的唯一书签值的数组。

  • FilterGroupEnum 值。

备注

使用 Filter 属性选择性地筛选 Recordset 对象中的记录。 筛选的 Recordset 将成为当前游标。 基于当前游标返回值的其他属性会受到影响，例如 AbsolutePosition 属性 (ADO)、AbsolutePage 属性 (ADO)、RecordCount 属性 (ADO) 和 PageCount 属性 (ADO)。 将 Filter 属性设置为特定值会将当前记录移动到满足新值的第一条记录。

条件字符串由 FieldName-Operator-Value 形式的子句组成（例如 "LastName = 'Smith'"）。 可以通过使用 AND（例如 "LastName = 'Smith' AND FirstName = 'John'"）或 OR（例如 "LastName = 'Smith' OR LastName = 'Jones'"）连接单个子句来创建复合子句。 条件字符串应遵循以下准则：

  • FieldName 必须是 Recordset 中的有效字段名称。 如果字段名称包含空格，则必须用方括号将该名称括起来。

  • Operator 必须是下列其中一项：<、>、<=、>=、<>、= 或 LIKE。

  • Value 是用于比较字段值的值（例如“Smith”、#8/24/95#、12.345 或 $50.00）。 字符串使用单引号，日期使用井号 (#)。 对于数字，可以使用小数点、美元符号和科学记数法。 如果 Operator 为 LIKE，则 Value 可以使用通配符。 只允许使用星号 (*) 和百分号 (%) 通配符，并且它们必须是字符串中的最后一个字符。 值不能为空。

注意

若要在筛选器 Value 中包含单引号 (')，请使用两个单引号来表示一个单引号。 例如，若要筛选 O'Malley，则条件字符串应为 "col1 = 'O''Malley'"。 若要在筛选器值的开头和末尾包含单引号，请使用井号 (#) 将该字符串括起来。 例如，若要筛选 '1'，则条件字符串应为 "col1 = #'1'#"。

  • AND 和 OR 之间没有优先级。 可以使用圆括号将子句分组。 但是，不能对 OR 联接的子句进行分组，然后使用 AND 将该组联接到另一个子句，如以下代码片段所示：：
    (LastName = 'Smith' OR LastName = 'Jones') AND FirstName = 'John'

  • 可以按如下所示构造此筛选器
    (LastName = 'Smith' AND FirstName = 'John') OR (LastName = 'Jones' AND FirstName = 'John')

  • 在 LIKE 子句中，可以在模式的开头和末尾使用通配符。 例如，可以使用 LastName Like '*mit*'。 或者使用 LIKE，只能在模式的末尾使用通配符。 例如，LastName Like 'Smit*'。

例如，通过筛选器常量你可以仅查看在上次 UpdateBatch Method 方法调用期间受影响的记录，从而更轻松地解决批量更新模式期间的单个记录冲突。

由于与基础数据发生冲突，设置 Filter 属性本身可能会失败。 例如，当其他用户已删除记录时，可能会发生此失败。 在这种情况下，提供程序会向 Errors 集合 (ADO) 集合返回警告，但不会停止程序执行。 仅当所有请求的记录发生冲突时，才会发生运行时错误。 使用 Status 属性 (ADO Recordset) 属性查找具有冲突的记录。

将 Filter 属性设置为零长度字符串 ("") 的效果与使用 adFilterNone 常量的效果相同。

只要设置了 Filter 属性，当前记录位置就会移动到 Recordset 中筛选的记录子集中的第一条记录。 同样，清除 Filter 属性后，当前记录位置将移动到 Recordset 中的第一条记录。

假设根据某些变体类型（例如，类型 sql_variant）的字段筛选 Recordset。 当字段的子类型与条件字符串中使用的筛选器值不匹配时，会发生错误 (DISP_E_TYPEMISMATCH or 80020005)。 例如，假设：

  • Recordset 对象 (rs) 包含 sql_variant 类型的列 (C)。
  • 此列的字段已分配了 I4 类型的值 1。 条件字符串在字段上设置为 rs.Filter = "C='A'"。

此配置在运行时生成错误。 但是，在同一字段中应用的 rs.Filter = "C=2" 不会生成任何错误。 从当前记录集中筛选出了字段。

有关可从中生成数组以与 Filter 属性一起使用的书签值的说明，请参阅 Bookmark 属性 (ADO)。

只有条件字符串形式的筛选器才会影响持久化 Recordset 的内容。 条件字符串的示例为 OrderDate > '12/31/1999'。 使用书签数组创建的筛选器或使用 FilterGroupEnum 中的值不会影响持久化 Recordset 的内容。 这些规则适用于使用客户端游标或服务器端游标创建的 Recordset。

注意

在批量更新模式下将 adFilterPendingRecords 标志应用于经过筛选和修改的 Recordset 时，如果根据单键表的键字段进行了筛选，并且对键字段值进行了修改，则生成的 Recordset 为空。 如果以下语句之一为 true，则生成的 Recordset 将为非空：

  • 根据单键表中的非键字段进行了筛选。

  • 根据基于多键表中的任何字段进行了筛选。

  • 对单键表中的非键字段进行了修改。

  • 对多键表中的任何字段进行了修改。

下表总结了不同筛选和修改组合中的 adFilterPendingRecords 的效果。 左列显示可能的修改。 可以对任何非键字段、单键表中的键字段或多键表中的任何键字段进行修改。 首行显示筛选条件。 可以根据任何非键字段、单键表中的键字段或多键表中的任何键字段进行筛选。 相交单元格显示结果。 + 加号表示应用 adFilterPendingRecords 会导致非空 Recordset。 - 减号表示空 Recordset。

组合 非键 单键 多键
非键 + + +
单键 + - 空值
多键 + 空值 +

应用于

记录集对象 (ADO)

另请参阅

Filter 和 RecordCount 属性示例 (VB)Filter 和 RecordCount 属性示例 (VC++)Clear 方法 (ADO)Optimize 属性 - 动态 (ADO)