Sheets

工作表

試算表中的表單。

JSON 表示法 
{
  "properties": {
    object (SheetProperties)
  },
  "data": [
    {
      object (GridData)
    }
  ],
  "merges": [
    {
      object (GridRange)
    }
  ],
  "conditionalFormats": [
    {
      object (ConditionalFormatRule)
    }
  ],
  "filterViews": [
    {
      object (FilterView)
    }
  ],
  "protectedRanges": [
    {
      object (ProtectedRange)
    }
  ],
  "basicFilter": {
    object (BasicFilter)
  },
  "charts": [
    {
      object (EmbeddedChart)
    }
  ],
  "bandedRanges": [
    {
      object (BandedRange)
    }
  ],
  "developerMetadata": [
    {
      object (DeveloperMetadata)
    }
  ],
  "rowGroups": [
    {
      object (DimensionGroup)
    }
  ],
  "columnGroups": [
    {
      object (DimensionGroup)
    }
  ],
  "slicers": [
    {
      object (Slicer)
    }
  ]
}
欄位
properties

object (SheetProperties)

工作表的屬性。
data[]

object (GridData)

格狀檢視資料 (如果這是格狀工作表)。

系統傳回的 GridData 物件數量取決於這張工作表要求的範圍數量。舉例來說，如果這代表 Sheet1，且試算表是透過範圍 Sheet1!A1:C10 和 Sheet1!D15:E20 要求，則第一個 GridData 會有 0 的 startRow/startColumn，而第二個則會有 startRow 14 (以零為基準的 15 行) 和 startColumn 3 (以零為基準的 D 欄)。

對於 DATA_SOURCE 工作表，您無法要求特定範圍，GridData 包含所有值。
merges[]

object (GridRange)

合併的範圍。

conditionalFormats[]

object (ConditionalFormatRule)

這份工作表中的條件式格式規則。

filterViews[]

object (FilterView)

這份工作表中的篩選器檢視畫面。

protectedRanges[]

object (ProtectedRange)

這份工作表中的受保護範圍。

basicFilter

object (BasicFilter)

這份工作表上的篩選器 (如有)。

charts[]

object (EmbeddedChart)

這個工作表中每張圖表的規格。
bandedRanges[]

object (BandedRange)

這個工作表上的帶狀 (交替顏色) 範圍。

developerMetadata[]

object (DeveloperMetadata)

與工作表相關聯的開發人員中繼資料。
rowGroups[]

object (DimensionGroup)

這個工作表上的所有列群組，依範圍起始索引和群組深度排序。
columnGroups[]

object (DimensionGroup)

這個工作表上的所有欄群組，以範圍起始索引遞增排序，然後依群組深度排序。
slicers[]

object (Slicer)

這個工作表上的切片器。

SheetProperties

工作表的屬性。

JSON 表示法 
{
  "sheetId": integer,
  "title": string,
  "index": integer,
  "sheetType": enum (SheetType),
  "gridProperties": {
    object (GridProperties)
  },
  "hidden": boolean,
  "tabColor": {
    object (Color)
  },
  "tabColorStyle": {
    object (ColorStyle)
  },
  "rightToLeft": boolean,
  "dataSourceSheetProperties": {
    object (DataSourceSheetProperties)
  }
}
欄位
sheetId

integer

工作表的 ID。不得為負數。設定後即無法變更這個欄位。
title

string

工作表名稱。

index

integer

試算表內的工作表索引。新增或更新工作表屬性時，如果排除這個欄位，系統會將工作表新增或移至工作表清單的結尾。更新工作表索引或插入工作表時，系統會將移動視為「移動前」的索引。舉例來說，如果有三個工作表 (S1、S2、S3)，為了將 S1 移到 S2 之前，索引必須設為 2。如果要求的索引與試算表目前的索引相同，或要求的新索引等於目前的工作表索引 + 1，系統會忽略工作表索引更新要求。

sheetType

enum (SheetType)

工作表類型。預設值為 GRID。設定後即無法變更這個欄位。
gridProperties

object (GridProperties)

如果工作表是格狀，則為工作表的其他屬性。(如果工作表是物件工作表，包含圖表或圖片，則不會有這個欄位)。在編寫時，如果在非格線工作表上設定任何格線屬性，就會發生錯誤。

如果這張工作表是 DATA_SOURCE 工作表，則系統只會輸出這個欄位，但會包含反映資料來源工作表在 UI 中算繪方式的屬性，例如 rowCount。
hidden

boolean

如果工作表未顯示在 UI 中，則為「true」，如果顯示的話，則為「false」。
tabColor
(deprecated)

object (Color)

UI 中的分頁顏色。已淘汰：請改用 tabColorStyle。
tabColorStyle

object (ColorStyle)

UI 中分頁的顏色。如果同時設定了 tabColor，這個欄位的優先順序會優先採用。
rightToLeft

boolean

如果工作表是 RTL 工作表而非 LTR 工作表，則為 True。
dataSourceSheetProperties

object (DataSourceSheetProperties)

僅供輸出。如果有這個欄位，則會包含 DATA_SOURCE 工作表專屬的屬性。

SheetType

工作表類型。

列舉
SHEET_TYPE_UNSPECIFIED 預設值，請勿使用。
GRID 工作表是格狀檢視畫面。
OBJECT 試算表沒有格線，而是包含圖表或圖片等物件。
DATA_SOURCE 工作表會連結至外部 DataSource，並顯示資料的預覽畫面。

GridProperties

格線的屬性。

JSON 表示法 
{
  "rowCount": integer,
  "columnCount": integer,
  "frozenRowCount": integer,
  "frozenColumnCount": integer,
  "hideGridlines": boolean,
  "rowGroupControlAfter": boolean,
  "columnGroupControlAfter": boolean
}
欄位
rowCount

integer

格狀檢視畫面中的列數。

columnCount

integer

格狀檢視畫面中的欄數。
frozenRowCount

integer

格狀檢視畫面中凍結的資料列數。

frozenColumnCount

integer

在格狀檢視畫面中凍結的欄數。
hideGridlines

boolean

如果格線未在 UI 中顯示格線，則為「是」。
rowGroupControlAfter

boolean

如果列分組控制項切換鈕顯示在群組之後，則為「是」。

columnGroupControlAfter

boolean

如果在群組後方顯示欄組控制項切換鈕，則為「是」。

DataSourceSheetProperties

DATA_SOURCE 工作表的其他屬性。

JSON 表示法 
{
  "dataSourceId": string,
  "columns": [
    {
      object (DataSourceColumn)
    }
  ],
  "dataExecutionStatus": {
    object (DataExecutionStatus)
  }
}
欄位
dataSourceId

string

工作表連結的 DataSource ID。
columns[]

object (DataSourceColumn)

工作表上顯示的資料欄，對應至 RowData 中的值。
dataExecutionStatus

object (DataExecutionStatus)

資料執行狀態。

GridData

格線中的資料，以及維度的中繼資料。

JSON 表示法 
{
  "startRow": integer,
  "startColumn": integer,
  "rowData": [
    {
      object (RowData)
    }
  ],
  "rowMetadata": [
    {
      object (DimensionProperties)
    }
  ],
  "columnMetadata": [
    {
      object (DimensionProperties)
    }
  ]
}
欄位
startRow

integer

這個 GridData 參照的第一列，以零為起點。
startColumn

integer

GridData 參照的第一欄，以零為起點。
rowData[]

object (RowData)

格狀檢視畫面中的資料，每列一個項目，從 startRow 中的列開始。RowData 中的值會對應至從 startColumn 開始的資料欄。
rowMetadata[]

object (DimensionProperties)

格狀檢視畫面中要求資料列的中繼資料 (從 startRow 中的資料列開始)。
columnMetadata[]

object (DimensionProperties)

關於格狀檢視畫面中要求欄位的中繼資料，從 startColumn 中的欄位開始。

RowData

資料列中每個儲存格中的資料。

JSON 表示法 
{
  "values": [
    {
      object (CellData)
    }
  ]
}
欄位
values[]

object (CellData)

資料列中的值，每個資料欄一個。

DimensionProperties

維度的屬性。

JSON 表示法 
{
  "hiddenByFilter": boolean,
  "hiddenByUser": boolean,
  "pixelSize": integer,
  "developerMetadata": [
    {
      object (DeveloperMetadata)
    }
  ],
  "dataSourceColumnReference": {
    object (DataSourceColumnReference)
  }
}
欄位
hiddenByFilter

boolean

如果這個維度正在篩除，則為 True。此欄位為唯讀欄位。

hiddenByUser

boolean

如果這個維度明確隱藏，則為「是」。

pixelSize

integer

維度的高度 (如果是資料列) 或寬度 (如果是資料欄)，以像素為單位。

developerMetadata[]

object (DeveloperMetadata)

與單一資料列或資料欄相關聯的開發人員中繼資料。

dataSourceColumnReference

object (DataSourceColumnReference)

僅供輸出。如果已設值，則是資料來源試算表中的資料欄。

ConditionalFormatRule

描述條件式格式的規則。

JSON 表示法 
{
  "ranges": [
    {
      object (GridRange)
    }
  ],

  // Union field rule can be only one of the following:
  "booleanRule": {
    object (BooleanRule)
  },
  "gradientRule": {
    object (GradientRule)
  }
  // End of list of possible types for union field rule.
}
欄位
ranges[]

object (GridRange)

條件為 true 時格式化的範圍。所有範圍都必須位於同一個格線。
聯集欄位 rule。控制此條件式格式的規則，必須設定一個。 rule 只能是下列其中一個：
booleanRule

object (BooleanRule)

格式化功能會根據規則設為「開啟」或「關閉」。

gradientRule

object (GradientRule)

格式會因規則中的漸層而有所不同。

BooleanRule

視條件而定，規則可能會或不會相符。

JSON 表示法 
{
  "condition": {
    object (BooleanCondition)
  },
  "format": {
    object (CellFormat)
  }
}
欄位
condition

object (BooleanCondition)

規則的條件。如果條件評估為 true，系統就會套用格式。

format

object (CellFormat)

要套用的格式。條件式格式只能套用部分格式：bold、italic、strikethrough、foreground color 和 background color。

GradientRule

根據所列插補點，套用漸層色彩階調格式的規則。相較於內插點的值，儲存格的格式會有所不同。

JSON 表示法 
{
  "minpoint": {
    object (InterpolationPoint)
  },
  "midpoint": {
    object (InterpolationPoint)
  },
  "maxpoint": {
    object (InterpolationPoint)
  }
}
欄位
minpoint

object (InterpolationPoint)

起始內插點。

midpoint

object (InterpolationPoint)

選用的中間插補點。
maxpoint

object (InterpolationPoint)

最終插補點。

InterpolationPoint

漸層條件式格式中的單一插補點。這類元素會根據所選的顏色、類型和值，固定漸層色彩比例。

JSON 表示法 
{
  "color": {
    object (Color)
  },
  "colorStyle": {
    object (ColorStyle)
  },
  "type": enum (InterpolationPointType),
  "value": string
}
欄位
color
(deprecated)

object (Color)

這個內插點應使用的顏色。已淘汰：請改用 colorStyle。
colorStyle

object (ColorStyle)

這個內插點應使用的顏色。如果同時設定了 color，系統會優先採用這個欄位。

type

enum (InterpolationPointType)

應如何解譯值。

value

string

這個插補點使用的值。可以是公式。如果 type 是 MIN 或 MAX，則未使用。

InterpolationPointType

內插點的種類。

列舉
INTERPOLATION_POINT_TYPE_UNSPECIFIED 預設值，請勿使用。
MIN 插補點會使用條件格式範圍內儲存格中的最小值。
MAX 插補點會使用條件式格式範圍內儲存格中的最大值。
NUMBER 插補點會使用 InterpolationPoint.value 中的值。
PERCENT

插補點是指條件式格式範圍內所有儲存格中指定的百分比。如果值是：=(MAX(FLATTEN(range)) * (value / 100)) + (MIN(FLATTEN(range)) * (1 - (value / 100))) (執行扁平時，系統會忽略範圍中的錯誤)，則等同於 NUMBER。
PERCENTILE 插補點是指條件格式範圍內所有儲存格中指定百分比的值。如果值是：=PERCENTILE(FLATTEN(range), value / 100) (執行扁平時，系統會忽略範圍中的錯誤)，則等同於 NUMBER。

FilterView

篩選器檢視畫面。

JSON 表示法 
{
  "filterViewId": integer,
  "title": string,
  "range": {
    object (GridRange)
  },
  "namedRangeId": string,
  "sortSpecs": [
    {
      object (SortSpec)
    }
  ],
  "criteria": {
    integer: {
      object (FilterCriteria)
    },
    ...
  },
  "filterSpecs": [
    {
      object (FilterSpec)
    }
  ]
}
欄位
filterViewId

integer

篩選器檢視畫面的 ID。
title

string

篩選器檢視畫面的名稱。
range

object (GridRange)

這個篩選器檢視畫面涵蓋的範圍。

寫入時，只能設定 range 或 namedRangeId 其中之一。
namedRangeId

string

這個篩選器檢視畫面所依據的命名範圍 (如果有的話)。

寫入時，只能設定 range 或 namedRangeId 的其中一個。
sortSpecs[]

object (SortSpec)

每個資料欄的排序順序。如果較早的規格中值相等，則會使用較新的規格。
criteria
(deprecated)

map (key: integer, value: object ( FilterCriteria))

每個資料欄顯示/隱藏值的條件。地圖的鍵是資料欄索引，而值是該資料欄的條件。

這個欄位已淘汰，並改用 filterSpecs。

filterSpecs[]

object (FilterSpec)

用來顯示/隱藏各欄值的篩選條件。

回應中會填入 criteria 和 filterSpecs。如果更新要求中同時指定了這兩個欄位，則以這個欄位為優先。

ProtectedRange

受保護的範圍。

JSON 表示法 
{
  "protectedRangeId": integer,
  "range": {
    object (GridRange)
  },
  "namedRangeId": string,
  "description": string,
  "warningOnly": boolean,
  "requestingUserCanEdit": boolean,
  "unprotectedRanges": [
    {
      object (GridRange)
    }
  ],
  "editors": {
    object (Editors)
  }
}
欄位
protectedRangeId

integer

受保護的範圍 ID。此欄位為唯讀欄位。

range

object (GridRange)

受保護的範圍。範圍可能沒有限制，在這種情況下，系統會將其視為受保護工作表。

寫入時，只能設定 range 或 namedRangeId 其中之一。
namedRangeId

string

這個受保護範圍的命名範圍 (如果有的話)。

寫入時，只能設定 range 或 namedRangeId 的其中一個。
description

string

這個受保護範圍的說明。

warningOnly

boolean

如果這個保護範圍在編輯時顯示警告，則為「是」。警告式保護功能可讓所有使用者編輯受保護範圍內的資料，但編輯時會顯示警告，要求使用者確認編輯內容。

寫入時：如果這個欄位為 true，系統會忽略 editors。此外，如果這個欄位從 true 變更為 false，且未設定 editors 欄位 (也不包含在欄位遮罩中)，編輯者會設為文件中的所有編輯者。
requestingUserCanEdit

boolean

如果要求這個保護範圍的使用者可以編輯受保護的區域，則為「是」。此欄位為唯讀欄位。

unprotectedRanges[]

object (GridRange)

受保護工作表中未受保護的範圍清單。只有受保護的工作表支援未受保護的範圍。

editors

object (Editors)

有權編輯受保護範圍的使用者和群組。只有具備受保護範圍和文件編輯權限的使用者，才能看到這個欄位。warningOnly 保護機制不支援編輯器。

編輯者

受保護範圍的編輯者。

JSON 表示法 
{
  "users": [
    string
  ],
  "groups": [
    string
  ],
  "domainUsersCanEdit": boolean
}
欄位
users[]

string

擁有受保護範圍的編輯存取權使用者的電子郵件地址。

groups[]

string

具有保護範圍編輯權限的群組電子郵件地址。
domainUsersCanEdit

boolean

如果文件網域中的任何使用者都有權編輯受保護的範圍，則為 true。網域保護功能僅支援網域內的文件。

BasicFilter

與工作表相關聯的預設篩選器。

JSON 表示法 
{
  "range": {
    object (GridRange)
  },
  "sortSpecs": [
    {
      object (SortSpec)
    }
  ],
  "criteria": {
    integer: {
      object (FilterCriteria)
    },
    ...
  },
  "filterSpecs": [
    {
      object (FilterSpec)
    }
  ]
}
欄位
range

object (GridRange)

篩選器涵蓋的範圍。
sortSpecs[]

object (SortSpec)

每個資料欄的排序順序。如果較早的規格中值相等，則會使用較新的規格。
criteria
(deprecated)

map (key: integer, value: object ( FilterCriteria))

每個資料欄顯示/隱藏值的條件。地圖的鍵是資料欄索引，而值是該資料欄的條件。

這個欄位已淘汰，請改用 filterSpecs。
filterSpecs[]

object (FilterSpec)

每個資料欄的篩選條件。

回應中會填入 criteria 和 filterSpecs。如果更新要求中同時指定了這兩個欄位，則以此欄位為優先。

BandedRange

工作表中的帶狀 (交替顏色) 範圍。

JSON 表示法 
{
  "bandedRangeId": integer,
  "range": {
    object (GridRange)
  },
  "rowProperties": {
    object (BandingProperties)
  },
  "columnProperties": {
    object (BandingProperties)
  }
}
欄位
bandedRangeId

integer

帶狀範圍的 ID。
range

object (GridRange)

套用這些屬性的範圍。
rowProperties

object (BandingProperties)

列帶的屬性。這些屬性會在範圍內的所有資料列中逐一套用。至少須指定 rowProperties 或 columnProperties。
columnProperties

object (BandingProperties)

資料欄區塊的屬性。這類屬性會在範圍內的所有資料欄依個別資料欄套用。必須指定至少一個 rowProperties 或 columnProperties。

BandingProperties

屬性參照單一維度 (資料列或資料欄)。如果同時設定 BandedRange.row_properties 和 BandedRange.column_properties，系統會根據下列規則將填滿顏色套用至儲存格：

舉例來說，第一列顏色優先於第一欄顏色，但第一欄顏色優先於第二列顏色。同樣地，列標頭的優先度會高於左上方儲存格的欄標題，但如果沒有設定列標題，則欄標題優先於第一列顏色。

JSON 表示法 
{
  "headerColor": {
    object (Color)
  },
  "headerColorStyle": {
    object (ColorStyle)
  },
  "firstBandColor": {
    object (Color)
  },
  "firstBandColorStyle": {
    object (ColorStyle)
  },
  "secondBandColor": {
    object (Color)
  },
  "secondBandColorStyle": {
    object (ColorStyle)
  },
  "footerColor": {
    object (Color)
  },
  "footerColorStyle": {
    object (ColorStyle)
  }
}
欄位
headerColor
(deprecated)

object (Color)

第一列或第一欄的顏色。如果設定了這個欄位，第一列或第一欄就會填入這個顏色，而 firstBandColor 和 secondBandColor 之間的顏色會從第二列或第二欄開始交替使用。否則，第一列或第一欄會填入 firstBandColor，顏色會照常交替。已淘汰：請改用 headerColorStyle。
headerColorStyle

object (ColorStyle)

第一列或第一欄的顏色。如果設有這個欄位，系統會以這個顏色填入第一列或第一欄，並從第二列或第二欄開始，交替使用 firstBandColor 和 secondBandColor 的顏色。否則，第一列或第一欄會填入 firstBandColor，顏色會照常交替。如果同時設定了 headerColor，這個欄位的優先順序會優先採用。
firstBandColor
(deprecated)

object (Color)

第一個交替顏色。(必要) 已淘汰：請改用 firstBandColorStyle。
firstBandColorStyle

object (ColorStyle)

第一個交替顏色。(必要) 如果同時設定 firstBandColor，則這個欄位的優先順序較高。
secondBandColor
(deprecated)

object (Color)

交替的第二個顏色。(必要) 已淘汰：請改用 secondBandColorStyle。
secondBandColorStyle

object (ColorStyle)

交替的第二個顏色。(必要) 如果一併設定了 secondBandColor，系統會優先採用這個欄位。

footerColor
(deprecated)

object (Color)

最後一列或欄的顏色。如未設定這個欄位，則最後一列或欄會填入 firstBandColor 或 secondBandColor (視前一個資料列或資料欄的顏色而定)。已淘汰：請改用 footerColorStyle。
footerColorStyle

object (ColorStyle)

最後一列或欄的顏色。如果未設定這個欄位，系統會根據前一列或一欄的顏色，將最後一列或一欄填入 firstBandColor 或 secondBandColor。如果同時設定了 footerColor，這個欄位的優先順序會優先採用。

DimensionGroup

試算表中一組相鄰的資料列或資料欄，可包含或包含在其他群組內。群組可在工作表中以單位形式展開或收合。

JSON 表示法 
{
  "range": {
    object (DimensionRange)
  },
  "depth": integer,
  "collapsed": boolean
}
欄位
range

object (DimensionRange)

這個群組存在的範圍。

depth

integer

群組的深度，代表有多少個群組的範圍完全包含這個群組的範圍。
collapsed

boolean

如果這個群組已摺疊，則為「是」。如果展開較淺層級的重疊群組，已收合的群組仍會保持收合狀態。

值為「是」並不表示群組中的所有維度都會隱藏，因為維度的顯示設定可以獨立於這個群組屬性變更。不過，如果這個屬性更新，當欄位設為 true 時，其中的所有維度都會設為隱藏，如果設為 false 則會設為可見。

篩選器控制項

工作表中的切片器。

JSON 表示法 
{
  "slicerId": integer,
  "spec": {
    object (SlicerSpec)
  },
  "position": {
    object (EmbeddedObjectPosition)
  }
}
欄位
slicerId

integer

切片器的 ID。
spec

object (SlicerSpec)

篩選器控制項的規格。

position

object (EmbeddedObjectPosition)

切片器的位置。請注意，切片器只能放在現有工作表中。此外，切片器的寬度和高度也可以自動調整，以便維持在允許範圍內。

SlicerSpec

切片器的規格。

JSON 表示法 
{
  "dataRange": {
    object (GridRange)
  },
  "filterCriteria": {
    object (FilterCriteria)
  },
  "columnIndex": integer,
  "applyToPivotTables": boolean,
  "title": string,
  "textFormat": {
    object (TextFormat)
  },
  "backgroundColor": {
    object (Color)
  },
  "backgroundColorStyle": {
    object (ColorStyle)
  },
  "horizontalAlignment": enum (HorizontalAlign)
}
欄位
dataRange

object (GridRange)

篩選器控制項的資料範圍。

filterCriteria

object (FilterCriteria)

切片器的篩選條件。
columnIndex

integer

資料表中要套用篩選器的資料欄，以 0 為索引。
applyToPivotTables

boolean

如果篩選器應套用至資料透視表，則為 True。如果未設定，預設為 True。
title

string

篩選器控制項的名稱。

textFormat

object (TextFormat)

切片器中標題的文字格式。不支援連結欄位。
backgroundColor
(deprecated)

object (Color)

切片器的背景顏色。已淘汰：請改用 backgroundColorStyle。
backgroundColorStyle

object (ColorStyle)

切片器的背景顏色。如果同時設定了 backgroundColor，這個欄位的優先順序會優先採用。
horizontalAlignment

enum (HorizontalAlign)

切片器中標題的水平對齊方式。如果未指定，則預設為 LEFT