Cells

CellData

特定儲存格的資料。

JSON 表示法 
{
  "userEnteredValue": {
    object (ExtendedValue)
  },
  "effectiveValue": {
    object (ExtendedValue)
  },
  "formattedValue": string,
  "userEnteredFormat": {
    object (CellFormat)
  },
  "effectiveFormat": {
    object (CellFormat)
  },
  "hyperlink": string,
  "note": string,
  "textFormatRuns": [
    {
      object (TextFormatRun)
    }
  ],
  "dataValidation": {
    object (DataValidationRule)
  },
  "pivotTable": {
    object (PivotTable)
  },
  "dataSourceTable": {
    object (DataSourceTable)
  },
  "dataSourceFormula": {
    object (DataSourceFormula)
  },
  "chipRuns": [
    {
      object (ChipRun)
    }
  ]
}
欄位
userEnteredValue

object (ExtendedValue)

使用者在儲存格中輸入的值。例如： 1234、 'Hello' 或 =NOW() 注意：日期、時間和日期時間會以 serial number 格式表示為雙精度浮點數。

effectiveValue

object (ExtendedValue)

儲存格的有效值。如果是內含公式的儲存格，這個值就是計算結果。如果是含有常值的儲存格，這與 userEnteredValue 相同。這是唯讀欄位。

formattedValue

string

儲存格的格式化值。這是向使用者顯示的值。這是唯讀欄位。

userEnteredFormat

object (CellFormat)

使用者為儲存格輸入的格式。

撰寫時，新格式會與現有格式合併。

effectiveFormat

object (CellFormat)

儲存格使用的有效格式。包括套用任何條件式格式設定的結果，以及儲存格含有公式時計算出的數字格式。如果有效格式為預設格式，系統就不會寫入有效格式。這是唯讀欄位。

note

string

儲存格的任何附註。

textFormatRuns[]

object (TextFormatRun)

套用至儲存格子區段的 RTF 格式執行。執行項目僅適用於使用者輸入的字串，不適用於公式、布林值或數字。執行項目的屬性會從文字中的特定索引開始，並持續到下一個執行項目。除非明確變更，否則執行會繼承儲存格的屬性。

撰寫時，新的執行作業會覆寫先前的執行作業。撰寫新指令時，系統會清除先前的執行記錄。userEnteredValue
dataValidation

object (DataValidationRule)

儲存格的資料驗證規則 (如有)。

寫入時，新的資料驗證規則會覆寫任何先前的規則。

pivotTable

object (PivotTable)

錨定在這個儲存格的資料透視表。資料透視表本身的大小是根據資料、分組、篩選條件、值等動態計算。只有資料透視表的左上角儲存格包含資料透視表定義。其他儲存格則會包含資料透視表結果的計算值，並顯示在各自的effectiveValue欄位中。
dataSourceTable

object (DataSourceTable)

錨定在這個儲存格的資料來源表格。資料來源資料表本身的大小會根據其設定動態計算。資料來源表格只有第一個儲存格包含資料來源表格定義。其他儲存格則會包含資料來源表格結果的顯示值，並顯示在各自的effectiveValue欄位中。
dataSourceFormula

object (DataSourceFormula)

僅供輸出。儲存格中資料來源公式的相關資訊。如果 userEnteredValue 是參照某個工作表的公式，例如 =SUM(DataSheet!Column)，系統就會設定這個欄位。DATA_SOURCE
chipRuns[]

object (ChipRun)

(選用步驟) 已將方塊執行套用至儲存格的子區段。執行個體的屬性會從文字中的特定索引開始，並持續到下一個執行個體。

讀取時，系統會一併納入有晶片和沒有晶片的跑步活動。未配戴晶片的跑步活動會顯示空白的 Chip。

撰寫時只會顯示跑步次數。含有晶片的執行個體長度為 1，並以「@」預留位置符號表示使用者輸入的文字。新執行作業會覆寫先前的執行作業。寫入新資料userEnteredValue會清除先前的執行作業。

CellFormat

儲存格的格式。

JSON 表示法 
{
  "numberFormat": {
    object (NumberFormat)
  },
  "backgroundColor": {
    object (Color)
  },
  "backgroundColorStyle": {
    object (ColorStyle)
  },
  "borders": {
    object (Borders)
  },
  "padding": {
    object (Padding)
  },
  "horizontalAlignment": enum (HorizontalAlign),
  "verticalAlignment": enum (VerticalAlign),
  "wrapStrategy": enum (WrapStrategy),
  "textDirection": enum (TextDirection),
  "textFormat": {
    object (TextFormat)
  },
  "hyperlinkDisplayType": enum (HyperlinkDisplayType),
  "textRotation": {
    object (TextRotation)
  }
}
欄位
numberFormat

object (NumberFormat)

說明如何向使用者呈現數字值的格式。

backgroundColor
(deprecated)

object (Color)

儲存格的背景顏色。已淘汰：請改用 backgroundColorStyle。
backgroundColorStyle

object (ColorStyle)

儲存格的背景顏色。如果同時設定了 backgroundColor，系統會優先採用這個欄位。
borders

object (Borders)

儲存格的邊界。

padding

object (Padding)

儲存格的邊框間距。

horizontalAlignment

enum (HorizontalAlign)

儲存格中值的水平對齊方式。

verticalAlignment

enum (VerticalAlign)

儲存格中值的垂直對齊方式。

wrapStrategy

enum (WrapStrategy)

儲存格中值的換行策略。

textDirection

enum (TextDirection)

儲存格中文字的方向。

textFormat

object (TextFormat)

儲存格中的文字格式 (除非格式執行階段已覆寫)。在此設定儲存格層級的連結會清除儲存格的現有連結。在 TextFormatRun 中設定連結欄位，優先於儲存格層級的連結。
textRotation

object (TextRotation)

套用至儲存格文字的旋轉角度。

NumberFormat

儲存格的數字格式。

JSON 表示法 
{
  "type": enum (NumberFormatType),
  "pattern": string
}
欄位
type

enum (NumberFormatType)

數字格式類型。寫入時，必須設定這個欄位。

pattern

string

用於格式設定的模式字串。如未設定，系統會視需要根據試算表的語言代碼，為指定類型套用預設格式。如要進一步瞭解支援的模式，請參閱日期和數字格式指南。

NumberFormatType

儲存格的數字格式。本文件假設語言代碼為 en_US，但實際格式取決於試算表的語言代碼。

列舉
NUMBER_FORMAT_TYPE_UNSPECIFIED 未指定數字格式，系統會根據儲存格內容判斷格式。請勿明確使用此項目。
TEXT 文字格式，例如： 1000.12
NUMBER 數字格式，例如： 1,000.12
PERCENT 百分比格式，例如： 10.12%
CURRENCY 貨幣格式，例如 $1,000.12
DATE 日期格式，例如： 9/26/2008
TIME 時間格式，例如： 3:59:00 PM
DATE_TIME 日期 + 時間格式，例如： 9/26/08 15:59:00
SCIENTIFIC 科學數字格式，例如： 1.01E+03

框線

儲存格的邊界。

JSON 表示法 
{
  "top": {
    object (Border)
  },
  "bottom": {
    object (Border)
  },
  "left": {
    object (Border)
  },
  "right": {
    object (Border)
  }
}
欄位
top

object (Border)

儲存格的上框線。

bottom

object (Border)

儲存格的下框線。

left

object (Border)

儲存格的左框線。

right

object (Border)

儲存格的右框線。

邊框

儲存格的邊框。

JSON 表示法 
{
  "style": enum (Style),
  "width": integer,
  "color": {
    object (Color)
  },
  "colorStyle": {
    object (ColorStyle)
  }
}
欄位
style

enum (Style)

邊框樣式。

width
(deprecated)

integer

邊框寬度 (以像素為單位)。已淘汰；寬度由「style」欄位決定。

color
(deprecated)

object (Color)

邊框顏色。已淘汰：請改用 colorStyle。
colorStyle

object (ColorStyle)

邊框顏色。如果同時設定了 color，系統會優先採用這個欄位。

樣式

邊框樣式。

列舉
STYLE_UNSPECIFIED 未指定樣式。請勿使用此屬性。
DOTTED 框線為虛線。
DASHED 框線為虛線。
SOLID 邊框為細實線。
SOLID_MEDIUM 邊框為中型實線。
SOLID_THICK 框線為粗實線。
NONE 無框線。僅用於更新邊框，以便清除邊框。
DOUBLE 邊框為兩條實線。

邊框間距

儲存格周圍的邊框間距量 (以像素為單位)。更新邊框間距時，必須指定每個欄位。

JSON 表示法 
{
  "top": integer,
  "right": integer,
  "bottom": integer,
  "left": integer
}
欄位
top

integer

儲存格的頂部邊框間距。

right

integer

儲存格的右側邊框間距。

bottom

integer

儲存格的下邊框間距。

left

integer

儲存格的左邊框間距。

VerticalAlign

儲存格中文字的垂直對齊方式。

列舉
VERTICAL_ALIGN_UNSPECIFIED 未指定垂直對齊方式。請勿使用此屬性。
TOP 文字會明確對齊儲存格頂端。
MIDDLE 文字會明確對齊儲存格中間。
BOTTOM 文字會明確對齊儲存格底部。

WrapStrategy

如何讓儲存格中的文字自動換行。

列舉
WRAP_STRATEGY_UNSPECIFIED 預設值，請勿使用。
OVERFLOW_CELL

如果文字長度超過儲存格寬度，系統會將文字寫入下一個儲存格 (前提是該儲存格為空白)。如果下一個儲存格不為空白，這項行為與 CLIP 相同。除非使用者手動插入新行，否則文字一律不會換行。範例：

| First sentence. |
| Manual newline that is very long. <- Text continues into next cell
| Next newline.   |
LEGACY_WRAP

這項換行策略代表舊版 Google 試算表換行策略，也就是說，如果文字長度超過一行，系統會剪除而非換行。並非所有平台都支援這項策略，且這項策略即將淘汰。範例：

| Cell has a |
| loooooooooo| <- Word is clipped.
| word.      |
CLIP

如果文字行長度超過儲存格寬度，系統會裁剪文字。除非使用者手動插入新行，否則文字一律不會換行。範例：

| First sentence. |
| Manual newline t| <- Text is clipped
| Next newline.   |
WRAP

如果單字長度超過一行，系統會以字元為單位換行，而非剪裁。範例：

| Cell has a |
| loooooooooo| <- Word is broken.
| ong word.  |

TextDirection

儲存格中文字的方向。

列舉
TEXT_DIRECTION_UNSPECIFIED 未指定文字方向。請勿使用此屬性。
LEFT_TO_RIGHT 使用者已將文字方向設為從左到右。
RIGHT_TO_LEFT 使用者已將文字方向設為從右到左。

HyperlinkDisplayType

是否要明確算繪超連結。如未指定，系統會連結超連結。

列舉
LINKED 超連結應明確顯示。
PLAIN_TEXT 超連結不應顯示。

TextRotation

套用至儲存格文字的旋轉角度。

JSON 表示法 
{

  // Union field type can be only one of the following:
  "angle": integer,
  "vertical": boolean
  // End of list of possible types for union field type.
}
欄位
聯集欄位 type。旋轉類型，垂直或傾斜。 type 只能是下列其中一項：
angle

integer

標準方向與所需方向之間的角度。以度為單位。有效值介於 -90 至 90 之間。正角度會向上傾斜，負角度則會向下傾斜。

注意：如果是從左到右的文字方向，正向角度為逆時針方向；如果是從右到左，則為順時針方向

vertical

boolean

如為 true，文字會從上到下排列，但個別字元的方向不變。例如： 

| V |
| e |
| r |
| t |
| i |
| c |
| a |
| l |

TextFormatRun

文字格式的執行。這個執行作業的格式會持續到下一個執行作業的開始索引為止。更新時，必須設定所有欄位。

JSON 表示法 
{
  "startIndex": integer,
  "format": {
    object (TextFormat)
  }
}
欄位
startIndex

integer

這個執行個體開始的字元索引 (從零算起)，以 UTF-16 程式碼單元表示。

format

object (TextFormat)

這個執行作業的格式。缺席值會沿用儲存格的格式。

DataValidationRule

資料驗證規則。

JSON 表示法 
{
  "condition": {
    object (BooleanCondition)
  },
  "inputMessage": string,
  "strict": boolean,
  "showCustomUi": boolean
}
欄位
condition

object (BooleanCondition)

儲存格中的資料必須符合的條件。

inputMessage

string

在儲存格中新增資料時，向使用者顯示的訊息。

strict

boolean

如果應拒絕無效資料，則為 True。

showCustomUi

boolean

如果應根據條件類型自訂 UI，則為 True。如果是 true，「清單」條件會顯示下拉式選單。

DataSourceTable

資料來源表格：使用者可從 DataSource 將靜態資料表匯入 Google 試算表。這在 Google 試算表編輯器中也稱為「擷取」。

JSON 表示法 
{
  "dataSourceId": string,
  "columnSelectionType": enum (DataSourceTableColumnSelectionType),
  "columns": [
    {
      object (DataSourceColumnReference)
    }
  ],
  "filterSpecs": [
    {
      object (FilterSpec)
    }
  ],
  "sortSpecs": [
    {
      object (SortSpec)
    }
  ],
  "rowLimit": integer,
  "dataExecutionStatus": {
    object (DataExecutionStatus)
  }
}
欄位
dataSourceId

string

資料來源資料表所關聯的資料來源 ID。

columnSelectionType

enum (DataSourceTableColumnSelectionType)

選取資料來源資料表資料欄的類型。預設值為 SELECTED。

columns[]

object (DataSourceColumnReference)

為資料來源表格選取的資料欄。columnSelectionType 必須為 SELECTED。
filterSpecs[]

object (FilterSpec)

篩選資料來源表格中的規格。

sortSpecs[]

object (SortSpec)

在資料來源表格中排序規格。資料來源表格的結果會依序根據排序規格排序。

rowLimit

integer

要傳回的資料列數量上限。如未設定，系統會套用預設限制。如需預設和上限，請參閱 Google 試算表編輯器。

dataExecutionStatus

object (DataExecutionStatus)

僅供輸出。資料執行狀態。

DataSourceTableColumnSelectionType

資料來源表格資料欄選取類型。

列舉
DATA_SOURCE_TABLE_COLUMN_SELECTION_TYPE_UNSPECIFIED 預設的欄選取類型，請勿使用。
SELECTED 選取由 columns 欄位指定的資料欄。
SYNC_ALL

同步處理資料來源中所有現有和日後的資料欄。

如果已設定，資料來源表格會在重新整理時擷取資料來源中的所有資料欄。

DataSourceFormula

資料來源公式。

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

string

公式相關聯的資料來源 ID。

dataExecutionStatus

object (DataExecutionStatus)

僅供輸出。資料執行狀態。

ChipRun

晶片的執行作業。直到下一次執行的開始索引為止。

JSON 表示法 
{
  "startIndex": integer,
  "chip": {
    object (Chip)
  }
}
欄位
startIndex

integer

必填。這個執行個體開始的字元索引 (從零算起)，以 UTF-16 程式碼單元表示。

chip

object (Chip)

(選用步驟) 這項執行的晶片。

晶片

智慧型方塊。

JSON 表示法 
{

  // Union field properties can be only one of the following:
  "personProperties": {
    object (PersonProperties)
  },
  "richLinkProperties": {
    object (RichLinkProperties)
  }
  // End of list of possible types for union field properties.
}
欄位
聯集欄位 properties。晶片的屬性。 properties 只能是下列其中一項：
personProperties

object (PersonProperties)

連結對象的屬性。

PersonProperties

與連結對象相關的屬性。

JSON 表示法 
{
  "email": string,
  "displayFormat": enum (DisplayFormat)
}
欄位
email

string

必填。與這個人連結的電子郵件地址。這個欄位一律會顯示。

displayFormat

enum (DisplayFormat)

(選用步驟) 人員資訊方塊的顯示格式。如未設定，系統會使用預設顯示格式。

DisplayFormat

如果有的話，偏好的顯示格式。

列舉
DISPLAY_FORMAT_UNSPECIFIED 預設值，請勿使用。
DEFAULT 預設顯示格式。
LAST_NAME_COMMA_FIRST_NAME 姓氏、名字顯示格式。
EMAIL 電子郵件顯示格式。

RichLinkProperties

Google 資源連結的屬性 (例如雲端硬碟中的檔案、YouTube 影片、地圖地址或日曆活動)。只有雲端硬碟檔案可以寫入晶片。所有其他類型的豐富連結都只能讀取。

寫入時，URI 不得超過 2000 個位元組。

注意：如要寫入雲端硬碟檔案資訊方塊，至少需要 drive.file、drive.readonly 或 drive OAuth 範圍。

JSON 表示法 
{
  "uri": string,
  "mimeType": string
}
欄位
uri

string

必填。連結的 URI。這項資訊一律會顯示。

mimeType

string

僅供輸出。連結的 MIME 類型 (如有)，例如 Google 雲端硬碟中的檔案。