过滤条件

借助过滤条件，您可以对查看电子表格时看到的数据进行排序和过滤。过滤条件不会更改电子表格中的数据值。您可以使用过滤条件来暂时隐藏或排序信息。当过滤条件处于开启状态时，与指定的过滤条件匹配的数据不会显示。借助过滤视图，您还可以保存不同的命名过滤条件，并随时在它们之间切换。

以下是一些过滤条件的示例用例：

  • 按特定列对数据进行排序。例如，按用户记录中的姓氏进行排序。
  • 隐藏符合特定条件的数据。例如，隐藏所有超过 2 年的记录。
  • 隐藏与特定值匹配的数据。例如，隐藏所有状态为“已关闭”的问题。

基本过滤条件

电子表格的BasicFilter是默认过滤条件，每当有人查看电子表格时，系统都会应用该过滤条件。每个工作表最多可以有一个基本过滤条件。您可以清除基本过滤条件来将其关闭。此操作会从电子表格中移除过滤条件及其所有设置。 如果您想重新开启同一过滤条件，必须再次设置相应条件。

管理基本过滤条件

如需设置或清除基本过滤条件，请使用 spreadsheets.batchUpdate 方法并指定相应的请求类型：

如需列出基本过滤条件，请使用 spreadsheets.get 方法并将 fields 网址参数设置为 sheets/basicFilter。以下 spreadsheets.get 代码示例展示了一个带有字段掩码的 Google 表格网址：

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/basicFilter)

过滤视图

FilterView是一种命名过滤条件，您可以随时开启和关闭。一个电子表格可以有多个过滤视图，但一次只能应用一个。

以下是过滤视图的一些示例用例：

  • 您有多个不同的过滤条件，希望在查看数据时在这些过滤条件之间切换。
  • 您没有电子表格的修改权限，但仍想应用过滤条件。在这种情况下，您可以创建只有您能看到的临时过滤视图。

  • 您希望与您共享电子表格的每个人以不同的方式查看数据。您可以在电子表格网址中提供 spreadsheetId 和 filterViewId，以指定要应用的过滤视图。为此，请使用创建过滤视图时在响应中返回的 filterViewId。

    以下代码示例展示了带有过滤视图的 Google 表格网址：

    https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0&fvid=FILTER_VIEW_ID

管理过滤视图

如需创建、复制、修改或删除过滤视图，请使用 spreadsheets.batchUpdate 方法并指定相应的请求类型：

如需列出所有过滤视图，请使用 spreadsheets.get 方法并将 fields 网址参数设置为 sheets/filterViews。以下 spreadsheets.get 代码示例展示了一个带有字段掩码的 Google 表格网址：

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/filterViews)

过滤条件表示法

以下代码示例展示了 FilterView 对象的 JSON 表示法。BasicFilter 对象相同，只是缺少 filterViewId 和 title 字段，并且无法使用已命名的范围。

{
  "filterViewId": number,
  "title": string,
  "range": {
    object(GridRange)
  },
  "namedRangeId": string,
  "sortSpecs": [
    {
      object(SortSpec)
    }
  ],
  "criteria": {
    string: {
      object(FilterCriteria)
    },
    ...
  }
}

示例数据

本文档的其余部分将参考以下示例销售数据表：

表 1. 示例销售数据
A B C D E F G
1 商品类别 型号 费用 数量 区域 销售人员 发货日期
2 车轮 W-24 20.50 美元 4 西 Beth 2016 年 3 月 1 日
3 门 D-01X 15.00 美元 2 南 Amir 2016 年 3 月 15 日
4 Frame FR-0B1 34.00 美元 8 东 Hannah 2016 年 3 月 12 日
5 面板 P-034 6.00 美元 4 北 Devyn 2016 年 3 月 15 日
6 面板 P-052 11.50 美元 7 东 Erik 2016 年 5 月 16 日
7 车轮 W-24 20.50 美元 11 南 Sheldon 2016 年 4 月 30 日
8 引擎 ENG-0161 $330.00 2 北 Jessie 2016 年 7 月 2 日

排序规范

一个过滤条件可以有多个排序规范。这些规范决定了数据的排序方式，并按指定顺序应用。SortSpec.dimensionIndex 属性用于指定应应用排序的列索引。

以下代码示例展示了排序规范：

[
  {
    "dimensionIndex": 3,
    "sortOrder": "ASCENDING"
  },
  {
    "dimensionIndex": 6,
    "sortOrder": "ASCENDING"
  }
]

如果将此规范应用于示例销售数据，则会先按“数量”排序，然后，如果两行的数量相同，则按“发货日期”排序。

表格 2. 按 2 列排序的销售数据
A B C D E F G
1 商品类别 型号 费用 数量 区域 销售人员 发货日期
2 门 D-01X 15.00 美元 2 南 Amir 2016 年 3 月 15 日
3 引擎 ENG-0161 $330.00 2 北 Jessie 2016 年 7 月 2 日
4 车轮 W-24 20.50 美元 4 西 Beth 2016 年 3 月 1 日
5 面板 P-034 6.00 美元 4 北 Devyn 2016 年 3 月 15 日
6 面板 P-052 11.50 美元 7 东 Erik 2016 年 5 月 16 日
7 Frame FR-0B1 34.00 美元 8 东 Hannah 2016 年 3 月 12 日
8 车轮 W-24 20.50 美元 11 南 Sheldon 2016 年 4 月 30 日

过滤条件

FilterCriteria 方法用于确定在基本过滤条件或过滤视图中显示或隐藏哪些电子表格数据。每个条件都取决于特定列中的值。您需要以映射的形式提供过滤条件，其中键是列索引，值是条件。

对于使用布尔值 condition 指定的条件，必须满足 True 条件才能显示值。相应条件不会替换 hiddenValues。如果某个值列在 hiddenValues 下，则系统仍会隐藏该值的所有匹配项。

以下代码示例展示了过滤条件映射：

{
  0: {
    'hiddenValues': ['Panel']
  },
  6: {
    'condition': {
      'type': 'DATE_BEFORE',
      'values': {
        'userEnteredValue': '4/30/2016'
      }
    }
  }
}

如果将此条件应用于示例销售数据，则只会显示“商品类别”不是“平板电脑”且“发货日期”在 2016 年 4 月 30 日之前的行。

表格 3. 使用过滤条件的销售数据
A B C D E F G
1 商品类别 型号 费用 数量 区域 销售人员 发货日期
2 车轮 W-24 20.50 美元 4 西 Beth 2016 年 3 月 1 日
3 门 D-01X 15.00 美元 2 南 Amir 2016 年 3 月 15 日
4 Frame FR-0B1 34.00 美元 8 东 Hannah 2016 年 3 月 12 日

示例

以下代码示例展示了如何创建过滤视图、复制该视图，然后使用上文中的示例销售数据更新复制的版本。

Python

sheets/snippets/sheets_filter_views.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def filter_views(spreadsheet_id):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)

    my_range = {
        "sheetId": 0,
        "startRowIndex": 0,
        "startColumnIndex": 0,
    }
    addfilterviewrequest = {
        "addFilterView": {
            "filter": {
                "title": "Sample Filter",
                "range": my_range,
                "sortSpecs": [{
                    "dimensionIndex": 3,
                    "sortOrder": "DESCENDING",
                }],
                "criteria": {
                    0: {"hiddenValues": ["Panel"]},
                    6: {
                        "condition": {
                            "type": "DATE_BEFORE",
                            "values": {"userEnteredValue": "4/30/2016"},
                        }
                    },
                },
            }
        }
    }

    body = {"requests": [addfilterviewrequest]}
    addfilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )

    duplicatefilterviewrequest = {
        "duplicateFilterView": {
            "filterId": addfilterviewresponse["replies"][0]["addFilterView"][
                "filter"
            ]["filterViewId"]
        }
    }

    body = {"requests": [duplicatefilterviewrequest]}
    duplicatefilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )

    updatefilterviewrequest = {
        "updateFilterView": {
            "filter": {
                "filterViewId": duplicatefilterviewresponse["replies"][0][
                    "duplicateFilterView"
                ]["filter"]["filterViewId"],
                "title": "Updated Filter",
                "criteria": {
                    0: {},
                    3: {
                        "condition": {
                            "type": "NUMBER_GREATER",
                            "values": {"userEnteredValue": "5"},
                        }
                    },
                },
            },
            "fields": {"paths": ["criteria", "title"]},
        }
    }

    body = {"requests": [updatefilterviewrequest]}
    updatefilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )
    print(str(updatefilterviewresponse))
  except HttpError as error:
    print(f"An error occurred: {error}")


if __name__ == "__main__":
  # Pass: spreadsheet_id
  filter_views("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k")