篩選器可讓您排序及篩選查看試算表時看到的資料。篩選器不會變更試算表中的資料值。您可以使用篩選器暫時隱藏或排序資訊。篩選器開啟時,符合指定篩選條件的資料不會顯示。透過篩選器檢視畫面,您也可以儲存不同的已命名篩選器,並隨時視需要切換。
以下是一些篩選器的應用範例:
- 按特定資料欄排序資料。例如,依照姓氏排序使用者記錄。
- 隱藏符合特定條件的資料。例如,隱藏所有 2 年以前的記錄。
- 隱藏符合特定值的資料。例如,隱藏所有狀態為「closed」的問題。
基本篩選器
試算表的 BasicFilter
是預設篩選器,每當有人查看試算表時就會套用。試算表在每個工作表中可以有一個基本篩選器。清除基本篩選器即可關閉。這麼做會從試算表中移除篩選器及其所有設定。
如要重新啟用相同的篩選器,您必須再次設定條件。
管理基本篩選器
如要設定或清除基本篩選器,請搭配適當的要求類型使用 spreadsheets.batchUpdate
方法:
- 如要設定基本篩選器,請使用
SetBasicFilterRequest
方法, - 如要清除基本篩選器,請使用
ClearBasicFilterRequest
方法。
如要列出基本篩選器,請使用 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
方法:
- 如要建立篩選器檢視畫面,請使用
AddFilterViewRequest
方法。 - 如要建立篩選器檢視畫面的副本,請使用
DuplicateFilterViewRequest
方法。 - 如要修改篩選器檢視畫面的屬性,請使用
UpdateFilterViewRequest
方法。 - 如要刪除篩選器檢視畫面,請使用
DeleteFilterViewRequest
方法。
如要列出所有篩選器檢視畫面,請使用 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)
},
...
}
}
Example 資料
本文件的其餘部分參考了下方的銷售資料表範例:
A | B | C | D | E | F | G | |
1 | 項目類別 | 型號 | 費用 | 數量 | 區域 | 銷售專員 | 出貨日期 |
2 | 摩天輪 | W-24 | $20.50 美元 | 4 | 西 | 貝斯 | 2016 年 3 月 1 日 |
3 | 門 | D-01X | $15.00 | 2 | 南 | 阿米爾 | 2016 年 3 月 15 日 |
4 | 頁框 | 法文-0B1 | NT$1,020 元 | 8 | 東 | Hannah | 2016 年 3 月 12 日 |
5 | 面板 | P-034 | $6.00 | 4 | North | Devyn (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 | NT$9,900 元 | 2 | North | 潔西 | 2016 年 7 月 2 日 |
排序規格
一個篩選器可以有多種排序規格。這些規格會決定資料的排序方式,並按指定的順序套用。SortSpec.dimensionIndex
屬性會指定要套用排序的資料欄索引。
以下程式碼範例顯示排序規格:
[
{
"dimensionIndex": 3,
"sortOrder": "ASCENDING"
},
{
"dimensionIndex": 6,
"sortOrder": "ASCENDING"
}
]
套用到範例銷售資料時,這個規格會先依據「數量」排序,如果 2 個資料列具有相同的數量,則依「出貨日期」排序。
A | B | C | D | E | F | G | |
1 | 項目類別 | 型號 | 費用 | 數量 | 區域 | 銷售專員 | 出貨日期 |
2 | 門 | D-01X | $15.00 | 2 | 南 | 阿米爾 | 2016 年 3 月 15 日 |
3 | 引擎 | ENG-0161 | NT$9,900 元 | 2 | North | 潔西 | 2016 年 7 月 2 日 |
4 | 摩天輪 | W-24 | $20.50 美元 | 4 | 西 | 貝斯 | 2016 年 3 月 1 日 |
5 | 面板 | P-034 | $6.00 | 4 | North | Devyn (Devyn) | 2016 年 3 月 15 日 |
6 | 面板 | P-052 | $11.50 美元 | 7 | 東 | Erik | 2016 年 5 月 16 日 |
7 | 頁框 | 法文-0B1 | NT$1,020 元 | 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'
}
}
}
}
套用至銷售範例資料時,這個條件只會顯示「Item Category」不是「Panel」,且「Ship Date」早於 2016 年 4 月 30 日的資料列。
A | B | C | D | E | F | G | |
1 | 項目類別 | 型號 | 費用 | 數量 | 區域 | 銷售專員 | 出貨日期 |
2 | 摩天輪 | W-24 | $20.50 美元 | 4 | 西 | 貝斯 | 2016 年 3 月 1 日 |
3 | 門 | D-01X | $15.00 | 2 | 南 | 阿米爾 | 2016 年 3 月 15 日 |
4 | 頁框 | 法文-0B1 | NT$1,020 元 | 8 | 東 | Hannah | 2016 年 3 月 12 日 |
範例
下列程式碼範例說明如何建立並複製篩選器檢視畫面,然後使用上述的銷售資料範例更新複製的版本。