本頁面由 Cloud Translation API 翻譯而成。

Class FilterCriteria

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

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

常見的使用方式

複製條件

以下範例會取得套用至範圍 A1:C20 的篩選器、取得套用至 C 欄的篩選條件，並將篩選條件複製到 B 欄。

const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
// Copies the filter criteria applied to column C.
const filter = range.getFilter();
const 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 值。

const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Gets the filter criteria applied to column B, then gets the hidden values.
const 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()`

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

您可以將這個方法用於任何類型的篩選器。如果您使用工作表篩選器，可以將條件複製到其他欄。

const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Makes a copy of the filter criteria applied to column C.
const 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。

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

回攻員

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

`getCriteriaValues()`

傳回布林條件的引數陣列。某些布林值條件類型沒有引數，且會傳回空陣列，例如 CELL_NOT_EMPTY。

使用者通常會使用這個方法，在篩選器中新增布林值條件，而不取代現有條件。

如要取得布林條件類型，請使用 getCriteriaType()。

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

您可以將此方法用於任何類型的篩選器。

const ss = SpreadsheetApp.getActiveSheet();
const 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.
const criteriaValues = filter.getColumnFilterCriteria(2).getCriteriaValues();
console.log(criteriaValues);

回攻員

Object[]：適合布林值條件類型的引數陣列。引數的數量和類型，必須與 FilterCriteriaBuilder 類別的對應 when...() 方法相符。

`getHiddenValues()`

傳回篩除器隱藏的值。

在 Grid 試算表 (預設試算表類型) 上使用篩選器搭配此條件。如果您針對其他類型的篩選器呼叫此方法，則會傳回 null。

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

回攻員

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

`getVisibleBackgroundColor()`

傳回用於篩選條件的背景顏色。背景顏色為此顏色的儲存格仍會顯示。

在 Grid 試算表 (預設的試算表類型) 上使用篩選器搭配此條件。如果您針對其他類型的篩選器呼叫此方法，則會傳回 null。

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

回攻員

Color：用於篩選條件的背景顏色。

`getVisibleForegroundColor()`

傳回做為篩選條件使用的前景顏色。使用此前景顏色的儲存格仍會顯示。

在 Grid 試算表 (預設的試算表類型) 上使用篩選器搭配此條件。如果您針對其他類型的篩選器呼叫此方法，則會傳回 null。

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

回攻員

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

`getVisibleValues()`

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

這個條件僅適用於未連結至資料庫的資料透視表篩選器。針對其他類型的篩選器，傳回空白陣列。

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

回攻員

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