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 的有效欄位名稱。 如果欄位名稱包含空格，則必須以方括弧括住名稱。

  • 運算子必須是下列其中一項：<><=、>=、<>= 或 LIKE。

  • 值是您將用來與欄位值進行比較的值 (例如 'Smith'、#8/24/95#、12.345 或 $50.00)。 使用單引號括住字串，並使用井字號 (#) 括住日期。 對於數字，您可以使用小數點、貨幣符號和科學記號標記法。 如果運算子為 LIKE，值可以使用萬用字元。 只允許星號 (*) 和百分比符號 (%) 萬用字元，而且這些萬元字元必須是字串中的最後一個字元。 值不可以是 null。

注意

若要在篩選值中包含單引號 (')，請使用兩個單引號來代表一個。 例如，若要篩選 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 方法呼叫期間受影響的記錄。

設定 Filter 屬性本身可能會由於與基礎資料衝突而失敗。 例如，當另一個使用者已刪除記錄時，就會發生此失敗。 在這種情況下，提供者會將警告傳回至 Errors 集合 (ADO) 集合，但不會終止程式執行。 只有在所有要求的記錄上發生衝突時，才會發生執行階段錯誤。 使用 Status 屬性 (ADO Recordset) 屬性來找出發生衝突的記錄。

將 Filter 屬性設定為長度為零的字串 ("") 與使用 adFilterNone 常數的效果相同。

每當設定 Filter 屬性時，目前的記錄位置就會移至 Recordset中已篩選記錄子集內的第一筆記錄。 同樣地，清除 Filter 屬性時，目前的記錄位置會移至 Recordset中的第一筆記錄。

假設 Recordset 是根據某個變體類型的欄位進行篩選，例如類型sql_variant。 當準則字串中使用的欄位和篩選值不符時，就會發生錯誤 (DISP_E_TYPEMISMATCH 或 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 內容。 這些規則適用於透過用戶端或伺服器端資料指標建立的記錄集。

注意

當您在批次更新模式中將 adFilterPendingRecords 旗標套用至已篩選和修改的 Recordset 時，如果篩選是根據單一索引鍵資料表的索引鍵欄位進行，而且修改是在索引鍵欄位值上進行，則產生的 Recordset 是空的。 如果下列其中一個陳述式成立，產生的 Recordset 將不是空的：

  • 篩選是根據單一索引鍵資料表中的非索引鍵欄位進行。

  • 篩選是根據多重索引鍵資料表中的任何欄位進行。

  • 修改是在單一索引鍵資料表中的非索引鍵欄位上進行。

  • 修改是在多重索引鍵資料表中的任何欄位上進行。

下表摘要說明不同篩選和修改組合的 adFilterPendingRecords 效果。 左欄顯示可能的修改。 您可以在任何非索引鍵欄位、單一索引鍵資料表中的索引鍵欄位，或多重索引鍵資料表中的任何索引鍵欄位上進行修改。 頂列顯示篩選準則。 您可以根據任何非索引鍵欄位、單一索引鍵資料表中的索引鍵欄位，或多重索引鍵資料表中的任何索引鍵欄位進行篩選。 交集資料格顯示結果。 + 加號表示套用 adFilterPendingRecords 會產生非空白的 Recordset。 - 減號表示空的 Recordset。

組合 非索引鍵 單一索引鍵 多個索引鍵
非索引鍵 + + +
單一索引鍵 + - N/A
多個索引鍵 + N/A +

套用至

Recordset 物件 (ADO)

另請參閱

Filter 和 RecordCount 屬性範例 (VB)Filter 和 RecordCount 屬性範例 (VC++)Clear 方法 (ADO)Optimize 屬性 - 動態 (ADO)