---
{
  "id": "platform.sheet.ranges-and-cell-values",
  "topic": "sheet",
  "title": "Sheet range 與 cell value",
  "locale": "zh-TW",
  "version": "2026-07-29",
  "summary": "Sheet 讀取會回傳有限範圍內的值、公式本文、快取結果與明確完整性資訊。",
  "content": "Sheet range 只接受 `A1`、`A1:D20`、`AA1:AZ100` 這類 A1 notation；`D20:A1` 反向範圍無效。不支援 `Sheet1!A1`、整欄 `A:A`、整列 `1:1` 或 R1C1。分頁用 `sheetId` 或 `sheetName` 選，兩者都有時 ID 優先；name 必須精確符合，重名會回 ambiguous，此時用 `list_sheets` 取得 ID。兩者都省略時取第一個分頁。\n\n`update_cells.cells` 的每個 key 必須是 `\"A1\"` 這類單一 cell；`\"A1:B2\"` 會被拒。矩形資料需展開成多個單格 key，或用 `append_rows`。JSON null 會寫入 blank 並清除該格值；boolean、number、string 保留公開 scalar 型別，其他 JSON 會字串化。以 `=` 開頭的字串會存成 formula cell。\n\nAgent 寫入或 append 後，伺服器會立即計算有限的 `SUM(A1:B2)` 公式；其他公式仍保留本文交由瀏覽器公式引擎處理，其結果可能為空或是先前快取。`read_range.valueMode` 預設 `display`，有快取時回格式化顯示字串；`raw` 回底層 scalar。每次讀取也會回相同形狀的 `formulas` 矩陣（本文以 `=` 開頭）與 `formulaResults` 矩陣，以及 `empty`、`usedRange`、`complete`、`truncated` 和目前 workbook `version`。\n\n大表先用 `get_workbook_summary`，preview 最多 20 列。必須檢查 `previewComplete` 與 `previewTruncated`；若被截斷，`readRangeRequired` 指出做整本結論前必須讀取的範圍。只有要求範圍涵蓋 `usedRange` 時，`read_range.complete` 才為 true；超過 action 上限時用 A1 視窗分段讀取。\n",
  "aliases": [
    "A1 notation",
    "range",
    "cell value",
    "formula",
    "display",
    "raw",
    "儲存格範圍",
    "公式",
    "顯示值",
    "原始值"
  ],
  "tags": [
    "sheet",
    "ranges",
    "cells",
    "formulas"
  ],
  "relatedActions": [
    "arinova.sheet.list_sheets",
    "arinova.sheet.get_workbook_summary",
    "arinova.sheet.read_range",
    "arinova.sheet.update_cells",
    "arinova.sheet.append_rows"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/sheet/ranges-and-cell-values/"
}
---

Sheet range 只接受 `A1`、`A1:D20`、`AA1:AZ100` 這類 A1 notation；`D20:A1` 反向範圍無效。不支援 `Sheet1!A1`、整欄 `A:A`、整列 `1:1` 或 R1C1。分頁用 `sheetId` 或 `sheetName` 選，兩者都有時 ID 優先；name 必須精確符合，重名會回 ambiguous，此時用 `list_sheets` 取得 ID。兩者都省略時取第一個分頁。

`update_cells.cells` 的每個 key 必須是 `"A1"` 這類單一 cell；`"A1:B2"` 會被拒。矩形資料需展開成多個單格 key，或用 `append_rows`。JSON null 會寫入 blank 並清除該格值；boolean、number、string 保留公開 scalar 型別，其他 JSON 會字串化。以 `=` 開頭的字串會存成 formula cell。

Agent 寫入或 append 後，伺服器會立即計算有限的 `SUM(A1:B2)` 公式；其他公式仍保留本文交由瀏覽器公式引擎處理，其結果可能為空或是先前快取。`read_range.valueMode` 預設 `display`，有快取時回格式化顯示字串；`raw` 回底層 scalar。每次讀取也會回相同形狀的 `formulas` 矩陣（本文以 `=` 開頭）與 `formulaResults` 矩陣，以及 `empty`、`usedRange`、`complete`、`truncated` 和目前 workbook `version`。

大表先用 `get_workbook_summary`，preview 最多 20 列。必須檢查 `previewComplete` 與 `previewTruncated`；若被截斷，`readRangeRequired` 指出做整本結論前必須讀取的範圍。只有要求範圍涵蓋 `usedRange` 時，`read_range.complete` 才為 true；超過 action 上限時用 A1 視窗分段讀取。