智慧型方塊

本指南說明如何使用 Google 試算表 API 新增及管理試算表中的智慧型方塊，以及相關原因。

什麼是智慧型方塊？

有了智慧方塊，您就能直接將其他 Google Workspace 應用程式的互動式資料匯入 Google 試算表。智慧方塊可讓使用者快速存取資訊和動作，將儲存格連結轉換為動態物件。詳情請參閱「在 Google 試算表中插入智慧型方塊」。

新增智慧型方塊

方塊會以方塊行表示，而方塊行是 CellData 的一部分，因此您可以透過提供 UpdateCellsRequest 或 AppendCellsRequest，使用現有的 spreadsheets.batchUpdate 方法插入方塊。

要求必須包含 chipRuns 欄位。晶片執行描述晶片的屬性，以及晶片在單元格文字中的位置。

撰寫 chipRuns 時，您也必須為每個要新增的方塊提供包含預留位置字元 (@) 的 userEnteredValue。chipRuns 陣列中的每個執行作業都會對應至其中一個預留位置。寫入時可省略未標記的執行階段。

以下範例說明如何將檔案方塊、人物方塊和純文字寫入單一儲存格 A1。* {JSON}

        {
          "updateCells": {
            "rows": [
              {
                "values": [
                  {
                    "userEnteredValue": {
                      "stringValue": "@ is the owner of @."
                    },
                    "chipRuns": [
                      {
                        "chip": {
                          "personProperties": {
                            "email": "johndoe@gmail.com",
                            "displayFormat": "DEFAULT"
                          }
                        }
                      },
                      {
                        "startIndex": 18,
                        "chip": {
                          "richLinkProperties": {
                            "uri": "https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit"
                          }
                        }
                      }
                    ]
                  }
                ]
              }
            ],
            "fields": "userEnteredValue,chipRuns",
            "range": {
              "startRowIndex": 0,
              "startColumnIndex": 0
            }
          }
        }

設定方塊屬性

方塊物件可具有下列其中一種屬性類型：

personProperties

可用於建立人物方塊。

  • email：(必要) 要建立連結的對象電子郵件地址。
  • displayFormat：(選用) 人物名稱的偏好顯示格式。可以是下列其中一個值：
    • DEFAULT：標準的「姓名」格式。
    • LAST_NAME_COMMA_FIRST_NAME：使用「姓氏, 名字」格式。
    • EMAIL：使用者的電子郵件地址。

可用於建立互動式連結方塊。雖然 API 可以讀取各種 Google 服務的連結 (例如 YouTube 或日曆)，但只有 Google 雲端硬碟檔案的連結可以寫入為方塊。

  • uri：(必要) 資源的 URI。如為寫作，則必須是 Google 雲端硬碟檔案連結。URI 不得超過 2000 個位元組。

讀取智慧型方塊

如要讀取智慧型方塊的資料，請使用 spreadsheets.get 方法，並在欄位參數中加入 sheets.data.rowData.values(chipRuns)。

回應中的 chipRuns 陣列會包含儲存格文字的所有子區段的物件。

  • 分割執行作業：這些部分會包含已填入的 chip 物件，其中包含 personProperties 或 richLinkProperties。
  • 未分割的行：純文字區段也會有行物件，但其 chip 欄位為空白。

如要取得方塊的顯示文字，請將 formattedValue 新增為欄位。

更新智慧型方塊

如要更新或取代智慧型方塊，你必須覆寫儲存格內容。使用與新增方塊相同的 UpdateCellsRequest 或 AppendCellsRequest，提供新的 userEnteredValue 和 chipRun。這會取代儲存格中的現有方塊。

搭配其他 Google 試算表功能使用智慧型方塊

表格：智慧型方塊可用做表格欄類型，用於追蹤專案擁有者 (使用者智慧型方塊) 或相關文件 (檔案智慧型方塊)。

篩選器：您可以根據其中智慧方塊的文字值篩選範圍。