过滤条件

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

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

  • 按特定列对数据进行排序。例如，按姓氏对用户记录进行排序。
  • 隐藏符合特定条件的数据。例如，隐藏所有超过 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. 按 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")