Class Filter

过滤

使用此类可修改 Grid 工作表（默认的工作表类型）上的现有过滤条件。网格工作表是指数据未与数据库关联的常规工作表。

如果工作表中尚无过滤器，请使用 Range.createFilter() 创建一个过滤器。

如需使用此类，您必须先使用 Range.getFilter() 或 Sheet.getFilter() 访问网格工作表过滤器。

常见用途

移除过滤条件

以下示例会获取活动工作表上的过滤器并将其移除。 
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Removes the filter from the active sheet.
filter.remove();

获取过滤条件的应用范围

以下示例会获取活动工作表上的过滤条件，然后使用此类中的 getRange() 方法记录过滤条件应用到的范围。 
const ss = SpreadsheetApp.getActiveSheet();
// Gets the existing filter on the active sheet.
const filter = ss.getFilter();
// Logs the range that the filter applies to in A1 notation.
console.log(filter.getRange().getA1Notation());

方法

方法返回类型简介
getColumnFilterCriteria(columnPosition)FilterCriteria获取指定列的过滤条件，如果未对该列应用过滤条件，则返回 null。
getRange()Range获取此过滤条件适用的范围。
remove()void移除此过滤条件。
removeColumnFilterCriteria(columnPosition)Filter从指定列中移除过滤条件。
setColumnFilterCriteria(columnPosition, filterCriteria)Filter针对指定列设置过滤条件。
sort(columnPosition, ascending)Filter按指定列对过滤后的范围进行排序，不包括此过滤器应用到的范围中的第一行（标题行）。

详细文档

getColumnFilterCriteria(columnPosition)

获取指定列的过滤条件，如果未对该列应用过滤条件，则返回 null。

如需详细了解过滤条件，请将此方法与 FilterCriteria 类中的方法串联起来。 

const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Gets the filter criteria applied to column B of the active sheet
// and logs the hidden values.
const filterCriteria = filter.getColumnFilterCriteria(2).getHiddenValues();
console.log(filterCriteria);

参数

名称类型说明
columnPositionInteger列的编号为 1 的位置。例如，列 B 的编号为 2。

返回

FilterCriteria - 过滤条件。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getRange()

获取此过滤条件适用的范围。 

// Gets the existing filter on the active sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Logs the range that the filter applies to in A1 notation.
console.log(filter.getRange().getA1Notation());

返回

Range - 过滤器的范围。如需以 A1 表示法获取范围，请将此方法与 Range.getA1Notation() 串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

remove()

移除此过滤条件。 

// Removes the filter from the active sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
filter.remove();

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeColumnFilterCriteria(columnPosition)

从指定列中移除过滤条件。 

// Removes the filter criteria from column B.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
filter.removeColumnFilterCriteria(2);

参数

名称类型说明
columnPositionInteger列的编号为 1 的位置。例如，列 B 的编号为 2。

返回

Filter - 过滤器，用于链接。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setColumnFilterCriteria(columnPosition, filterCriteria)

针对指定列设置过滤条件。首先，使用 SpreadsheetApp.newFilterCriteria() 创建过滤条件构建器。然后，使用 FilterCriteriaBuilder 类向构建器添加条件。构建条件后，将其设置为此方法的 filterCriteria 参数。 

const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Builds the filter criteria to use as a parameter for setColumnFilterCriteria.
const criteria = SpreadsheetApp.newFilterCriteria()
                     .setHiddenValues(['Hello', 'World'])
                     .build();
// Sets the filter criteria for column C.
filter.setColumnFilterCriteria(3, criteria);

参数

名称类型说明
columnPositionInteger列的编号为 1 的位置。例如，列 B 的编号为 2。
filterCriteriaFilterCriteria要设置的过滤条件。如果您将条件设置为 null，系统会从指定列中移除过滤条件。您也可以使用 removeColumnFilterCriteria(columnPosition)。

返回

Filter - 过滤器，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

sort(columnPosition, ascending)

按指定列对过滤后的范围进行排序，不包括此过滤器应用范围的第一行（标题行）。 

// Gets the existing filter and sorts it by column B in ascending order.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
filter.sort(2, true);

参数

名称类型说明
columnPositionInteger列的编号为 1 的位置。例如，列 B 的编号为 2。
ascendingBoolean如果为 true，则按升序对过滤范围进行排序；如果为 false，则按降序对过滤范围进行排序。

返回

Filter - 过滤器，用于串联。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets