智慧型方塊

本指南說明如何使用 Google Sheets API 在試算表中新增及管理智慧型方塊，以及使用這項功能的理由。

什麼是智慧型方塊？

有了智慧方塊，您就能直接在 Google 試算表中匯入其他 Google Workspace 應用程式的豐富互動式資料。智慧晶片可讓使用者快速存取資訊和動作，將儲存格連結轉換為動態物件。詳情請參閱「在 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 方法，並在 fields 參數中加入 sheets.data.rowData.values(chipRuns)。

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

  • 已晶片感應的跑步活動：這些區段會包含已填入的 chip 物件，其中包含 personProperties 或 richLinkProperties。
  • 非切片執行：純文字區段也會有執行物件，但其 chip 欄位會是空白。

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

更新智慧型方塊

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

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

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

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