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 的 startRow/startColumn 为 0，而第二个 GridData 的 startRow 14（从零开始编号的行 15）和 startColumn 3（从零开始编号的列 D）的值为 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），则必须将索引设置为 2，才能将 S1 移到 S2 前面。如果请求的索引与工作表的当前索引相同，或者请求的新索引等于当前工作表索引 + 1，系统会忽略工作表索引更新请求。

sheetType

enum (SheetType)

工作表的类型。默认值为 GRID。此字段一经设置便无法更改。

gridProperties

object (GridProperties)

如果此工作表是网格，则为其提供其他属性。（如果工作表是包含图表或图片的对象工作表，则此字段将不存在。）在编写时，如果在非网格工作表上设置任何网格属性，则会出错。

如果此工作表是 DATA_SOURCE 工作表，则此字段仅用于输出，但包含反映数据源工作表在界面中呈现方式的属性，例如 rowCount。

hidden

boolean

如果工作表在界面中处于隐藏状态，则为 true；如果处于可见状态，则为 false。

tabColor
(deprecated)

object (Color)

界面中标签页的颜色。已废弃：请使用 tabColorStyle。
tabColorStyle

object (ColorStyle)

界面中标签页的颜色。如果同时设置了 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

如果界面中的网格未显示网格线，则为 true。
rowGroupControlAfter

boolean

如果行分组控件切换开关显示在组后面，则为 true。

columnGroupControlAfter

boolean

如果列分组控件切换开关显示在组后面，则为 true。

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

如果此维度已明确隐藏，则为 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)

要应用的格式。条件格式只能应用部分格式：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。基于警告的保护意味着，每位用户都可以修改受保护范围内的数据，但修改时系统会显示警告，要求用户确认修改。

写入时：如果此字段为 true，则系统会忽略 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)

每列的过滤条件。

系统会在响应中填充 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。如果展开了深度较浅的叠加组，则收起的组仍会保持收起状态。

值为 true 并不意味着组中的所有维度都处于隐藏状态，因为维度的可见性可以独立于此组属性而发生变化。不过，更新此属性时，如果此字段设为 true，则其中的所有维度都会设为“隐藏”；如果此字段设为 false，则其中的所有维度都会设为“可见”。

切片器

工作表中的切片器。

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

integer

切片器的 ID。

spec

object (SlicerSpec)

截剪器的规范。

position

object (EmbeddedObjectPosition)

切片器的位置。请注意，只有在现有工作表中才能放置切片器。此外，系统还可以自动调整 Slicer 的宽度和高度，使其保持在允许的限制范围内。

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