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 是參照某些 DATA_SOURCE 工作表的公式 (例如 =SUM(DataSheet!Column))，系統就會設定此欄位。
chipRuns[]

object (ChipRun)

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

讀取時，系統會納入所有有標記和無標記的執行階段。未標記的執行階段會顯示空白的 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，這個欄位的優先順序會高於 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，這個欄位的優先順序會高於 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 碼元表示的，此執行作業的起始位置 (以 0 為基底的字元索引)。
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，則「清單」條件會顯示下拉式選單。

DataSourceTable

資料來源資料表，可讓使用者將靜態資料表資料從 DataSource 匯入試算表。這在 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 碼元表示的，此執行作業的起始位置 (以 0 為基底的字元索引)。
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 資源的屬性 (例如 Google 雲端硬碟檔案、YouTube 影片、地圖地址或日曆活動)。只有雲端硬碟檔案可以寫入為方塊。所有其他動態連結類型皆為唯讀。

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

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

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

string

必要欄位。連結的 URI。這個值一律會存在。
mimeType

string

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