Class FilterCriteria

FilterCriteria

您可以使用這個類別取得相關資訊，或是複製現有篩選器的條件。

• 如要建立新的篩選器，請參閱下列資源：
  • 如果是工作表，請使用 Range.createFilter()。
  • 如果是資料透視表，請使用 PivotTable.addFilter(sourceDataColumn, filterCriteria)。
  • 如果是連結至資料庫的工作表，請使用 DataSourceSheet.addFilter(columnName, filterCriteria)。
  • 如果是連結至資料庫的資料透視表，請使用 DataSourcePivotTable.addFilter(columnName, filterCriteria)。
• 如要為任何類型的篩選器建立條件，請參考 SpreadsheetApp.newFilterCriteria() 和 FilterCriteriaBuilder。

常見的使用方式

複製條件

以下範例會取得套用到 A1:C20 範圍的篩選器，進而取得條件 ，然後將條件複製到 B 欄。

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
// Copies the filter criteria applied to column C.
let filter = range.getFilter();
let criteria = filter.getColumnFilterCriteria(3).copy().build();
// Applies the copied criteria to column B. The copied criteria overwrites any existing
// criteria on column B.
filter.setColumnFilterCriteria(2, criteria);

取得篩選器隱藏的值

以下範例會取得適用於指定範圍的篩選器，並記錄 篩選器隱藏的 B 欄。

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Gets the filter criteria applied to column B, then gets the hidden values.
let filterCriteria = filter.getColumnFilterCriteria(2).getHiddenValues();
// Logs the hidden values.
console.log(filterCriteria);

方法

方法	傳回類型	簡短說明
copy()	FilterCriteriaBuilder	複製這個篩選條件，並建立可套用到其他篩選條件的條件建立工具 篩選。
getCriteriaType()	BooleanCriteria	傳回條件的布林值類型，例如 CELL_EMPTY。
getCriteriaValues()	Object[]	傳回布林條件的引數陣列。
getHiddenValues()	String[]	傳回篩選器隱藏的值。
getVisibleBackgroundColor()	Color	傳回做為篩選條件使用的背景顏色。
getVisibleForegroundColor()	Color	傳回做為篩選條件使用的前景顏色。
getVisibleValues()	String[]	傳回資料透視表篩選器顯示的值。

內容詳盡的說明文件

copy()

複製這個篩選條件，並建立可套用到其他篩選條件的條件建立工具 篩選。

這個方法適用於任何類型的篩選器。使用工作表篩選器時，您可以 將條件複製到另一個資料欄

let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Makes a copy of the filter criteria applied to column C.
let criteria = filter.getColumnFilterCriteria(3).copy().build();
// Applies the copied criteria to column B. The copied criteria overwrites any existing
// criteria on column B.
filter.setColumnFilterCriteria(2, criteria);

回攻員

FilterCriteriaBuilder：根據這個篩選條件建立的篩選條件建構工具。

---

getCriteriaType()

傳回條件的布林值類型，例如 CELL_EMPTY。如要瞭解 布林值條件，請參閱 BooleanCriteria 列舉。

使用者通常會使用這個方法在篩選器中加入布林條件條件，而不會將任何取代 現有的條件

• 如要取得條件的引數，請使用 getCriteriaValues()。
• 如要使用條件類型和條件值建立或修改篩選條件，請參閱 FilterCriteriaBuilder.withCriteria(criteria, args)。

這個方法適用於任何類型的篩選器。如果篩選條件不是布林值 條件，會傳回 null。

let ss = SpreadsheetApp.getActiveSheet();
// Gets the filter on the active sheet.
let filter = ss.getFilter();
// Gets the criteria type and returns a string representing the criteria type object.
let criteriaType = filter.getColumnFilterCriteria(2)
                         .getCriteriaType()
                         .toString();
// Logs the criteria type.
console.log(criteriaType);

回攻員

BooleanCriteria：布林條件的類型；如果條件不是布林值，則傳回 null 值。

---

getCriteriaValues()

傳回布林條件的引數陣列。部分佈林條件類型沒有 並傳回空陣列，例如 CELL_NOT_EMPTY。

使用者通常會使用這個方法在篩選器中加入布林條件條件，而不會將任何取代 現有的條件

• 如要取得布林條件類型，請使用 getCriteriaType()。
• 如要使用條件類型和條件值建立或修改篩選條件，請參閱 FilterCriteriaBuilder.withCriteria(criteria, args)。

  這個方法適用於任何類型的篩選器。

  let ss = SpreadsheetApp.getActiveSheet();
  let filter = ss.getFilter();
  // Gets the values of the boolean criteria and logs them. For example, if the boolean
  // condition is whenNumberGreaterThan(10), then the logged value is 10.
  let criteriaValues = filter.getColumnFilterCriteria(2).getCriteriaValues();
  console.log(criteriaValues);

  回攻員

  Object[]：適合佈林值條件類型的引數陣列。引數的數量 而且類型符合 FilterCriteriaBuilder 類別的對應 when...() 方法。

---

getHiddenValues()

傳回篩選器隱藏的值。

您可以在 Grid 工作表 (預設類型的工作表) 中搭配使用這項條件和篩選器。 如果您呼叫這個方法為其他類型的篩選器，會傳回 null。

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Gets the filter criteria applied to column B, then gets the hidden values.
let filterCriteria = filter.getColumnFilterCriteria(2).getHiddenValues();
// Logs the hidden values.
console.log(filterCriteria);

回攻員

String[]：篩選器隱藏的值陣列。

---

getVisibleBackgroundColor()

傳回做為篩選條件使用的背景顏色。保持套用這個背景顏色的儲存格 顯示。

您可以在 Grid 工作表 (預設類型的工作表) 中搭配使用這項條件和篩選器。 如果您呼叫這個方法為其他類型的篩選器，會傳回 null。

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
// Logs the background color that column B is filtered by as a hexadecimal string.
let filter = range.getFilter();
let color = filter.getColumnFilterCriteria(2)
                  .getVisibleBackgroundColor()
                  .asRgbColor()
                  .asHexString();
console.log(color);

回攻員

Color：當做篩選條件的背景顏色。

---

getVisibleForegroundColor()

傳回做為篩選條件使用的前景顏色。保留這個前景顏色的儲存格 顯示。

您可以在 Grid 工作表 (預設類型的工作表) 中搭配使用這項條件和篩選器。 如果您呼叫這個方法為其他類型的篩選器，會傳回 null。

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
// Logs the foreground color that column B is filtered by as a hexadecimal string.
let filter = range.getFilter();
let color = filter.getColumnFilterCriteria(2)
                  .getVisibleForegroundColor()
                  .asRgbColor()
                  .asHexString();
console.log(color);

回攻員

Color：當做篩選條件的前景顏色。

---

getVisibleValues()

傳回資料透視表篩選器顯示的值。

這項條件僅適用於未連結到資料庫的資料透視表篩選器。 為其他類型的篩選器傳回空白陣列。

let ss = SpreadsheetApp.getActiveSheet();
// Gets the first pivot table on the sheet, then gets the visible values of its first filter.
pivotTable = ss.getPivotTables()[0];
pivotFilterValues = pivotTable.getFilters()[0].getFilterCriteria().getVisibleValues();
// Logs the visible values.
console.log(pivotFilterValues);

回攻員

String[]：資料透視表篩選器顯示的值陣列。