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:C10Sheet1!D15:E20,則第一個 GridData 會顯示 0startRow//startColumn,而第二個網格的 startRow 14 將有 startRow 14 (從 1 列算起的 15 列) 和 startColumn 3 (從 0 欄開始)。

針對 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 (如果顯示的話)。

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 中的格線,則為 True。

rowGroupControlAfter

boolean

如果資料列分組控制項顯示至群組後,則為 True。

columnGroupControlAfter

boolean

如果資料欄分組控制項在群組後顯示,則為 True。

DataSourceSheetProperties

DATA_SOURCE 工作表的其他屬性。

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

string

工作表連結的 DataSource

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)

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

DimensionsProperties

維度的屬性。

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

boolean

如果這項維度遭到篩除,則為 True。這是唯讀欄位。

hiddenByUser

boolean

如果已明確隱藏這個維度,則為 True。

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)

要套用的格式。條件式格式設定只能套用部分格式:bolditalicstrikethroughforeground colorbackground 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

這個內插點使用的值。可以是公式。如果 typeMINMAX,則未使用。

InterpolationPointType

內插點的種類。

列舉
INTERPOLATION_POINT_TYPE_UNSPECIFIED 預設值,不使用。
MIN 內插點會在條件式範圍的範圍內使用儲存格中的最小值。
MAX 內插點會使用條件式範圍內儲存格中的最大值。
NUMBER 內插點完全使用 InterpolationPoint.value 中的值。
PERCENT

內插點是指條件式範圍內範圍內所有儲存格的指定百分比。這相當於 NUMBER,前提是值為: =(MAX(FLATTEN(range)) * (value / 100)) + (MIN(FLATTEN(range)) * (1 - (value / 100))) (分割時忽略該範圍內的錯誤)。

PERCENTILE 內插點是指條件式範圍內範圍內所有儲存格的指定百分位數。這相當於 NUMBER,前提是值為: =PERCENTILE(FLATTEN(range), value / 100) (分割時忽略該範圍內的錯誤)。

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)

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

寫入時,只能設定 rangenamedRangeId 其中之一。

namedRangeId

string

這個篩選器檢視畫面支援的已命名範圍 (如果有的話)。

寫入時,只能設定 rangenamedRangeId 其中之一。

sortSpecs[]

object (SortSpec)

每一欄的排序順序。如果值採用較舊的規格,系統就會使用後續規格。

criteria
(deprecated)

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

每一欄顯示/隱藏值的條件。地圖的索引鍵是資料欄索引,值則代表該資料欄的條件。

這個欄位已淘汰,並改用 filterSpecs

filterSpecs[]

object (FilterSpec)

顯示/隱藏每一欄值的篩選條件。

在回應中,系統會填入 criteriafilterSpecs。如果在更新要求中同時指定這兩個欄位,系統會優先採用這個欄位。

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)

受保護的範圍。範圍可能會完全不受限制,在這種情況下,系統會將其視為受保護的工作表。

寫入時,只能設定 rangenamedRangeId 其中之一。

namedRangeId

string

這個受保護的範圍使用的備份範圍 (如果有的話)。

寫入時,只能設定 rangenamedRangeId 其中之一。

description

string

這個受保護範圍的說明。

warningOnly

boolean

如果這個受保護的範圍在編輯時顯示警告,則傳回「是」。警告製的保護措施代表所有使用者皆可在受保護的範圍內編輯資料,但編輯提示會要求使用者確認編輯內容。

編寫時:如果這個欄位為「是」,系統會忽略 editors。此外,如果將這個欄位從 true 變更為 false,且未設定 editors 欄位 (未包含在欄位遮罩中),編輯器就會設為文件中的所有編輯者。

requestingUserCanEdit

boolean

如果要求這個保護範圍的使用者可以編輯受保護的範圍,則為 True。這是唯讀欄位。

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)

每個資料欄的篩選條件。

在回應中,系統會填入 criteriafilterSpecs。如果在更新要求中同時指定這兩個欄位,系統會優先採用這個欄位。

BandedRange

工作表中的頻帶 (配色) 範圍。

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

integer

頻帶範圍的 ID。

range

object (GridRange)

這些屬性套用的範圍。

rowProperties

object (BandingProperties)

資料列樂團的屬性。這些屬性會逐列逐列套用。必須指定至少一個 rowPropertiescolumnProperties

columnProperties

object (BandingProperties)

柱狀圖的屬性。範圍中逐資料欄套用這些屬性。必須指定至少一個 rowPropertiescolumnProperties

BandingProperties

參照單一維度 (列或欄) 的資源。如果同時設定了 BandedRange.row_propertiesBandedRange.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)

第一列或欄的顏色。如果設定了這個欄位,第一列或欄會填入這個顏色,並從第二列或欄的 firstBandColorsecondBandColor 之間替代顏色。否則,第一列或欄會填入 firstBandColor,而且顏色會照常運作。已淘汰:使用 headerColorStyle

headerColorStyle

object (ColorStyle)

第一列或欄的顏色。如果設定了這個欄位,第一列或欄會填入這個顏色,並從第二列或欄的 firstBandColorsecondBandColor 之間替代顏色。否則,第一列或欄會填入 firstBandColor,而且顏色會照常運作。如果同時設定了 headerColor,系統會優先採用這個欄位。

firstBandColor
(deprecated)

object (Color)

第一個可變動的顏色。(必要) 已淘汰:使用 firstBandColorStyle

firstBandColorStyle

object (ColorStyle)

第一個可變動的顏色。(必要) 如果同時設定了 firstBandColor,系統會優先採用這個欄位。

secondBandColor
(deprecated)

object (Color)

交替的第二色。(必要) 已淘汰:使用 secondBandColorStyle

secondBandColorStyle

object (ColorStyle)

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

footerColor
(deprecated)

object (Color)

最後一列或欄的顏色。如未設定這個欄位,最後一列或欄的值就會填入 firstBandColorsecondBandColor。已淘汰:使用 footerColorStyle

footerColorStyle

object (ColorStyle)

最後一列或欄的顏色。如未設定這個欄位,最後一列或欄的值就會填入 firstBandColorsecondBandColor。如果同時設定了 footerColor,系統會優先採用這個欄位。

Dimensions Group

工作表上的資料列或資料欄間隔群組,可能包含或納入其他群組。工作表上的群組可收合或展開。

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

object (DimensionRange)

這個群組所屬的範圍。

depth

integer

群組深度,代表包含特定群組範圍的群組數量。

collapsed

boolean

如果收合此群組,則這個欄位為 true。如果收合了淺層深度的重疊群組,已收合的群組仍會保持收合狀態。

實際值不一定會表示群組中的所有維度都會隱藏,因為維度的瀏覽權限可能會與這個群組資源獨立運作。不過,更新這項屬性時,如果這個欄位為 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

要套用篩選器的資料表中以零為基礎的欄索引。

applyToPivotTables

boolean

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

title

string

篩選器控制項的標題。

textFormat

object (TextFormat)

篩選器控制項中的標題格式。不支援連結欄位。

backgroundColor
(deprecated)

object (Color)

篩選器控制項的背景顏色。已淘汰:使用 backgroundColorStyle

backgroundColorStyle

object (ColorStyle)

篩選器控制項的背景顏色。如果同時設定了 backgroundColor,系統會優先採用這個欄位。

horizontalAlignment

enum (HorizontalAlign)

篩選器控制項中的標題水平對齊方式。如未指定,則預設為 LEFT