Elementy inteligentne

Z tego przewodnika dowiesz się, jak i dlaczego używać interfejsu Google Sheets API do dodawania elementów inteligentnych w arkuszach kalkulacyjnych i zarządzania nimi.

Co to jest element inteligentny?

Dzięki inteligentnym elementom możesz przenosić do Arkuszy bogate, interaktywne dane z innych aplikacji Google Workspace. Inteligentne tagi zapewniają użytkownikom szybki dostęp do informacji i działań, przekształcając link do komórki w dynamiczny obiekt. Więcej informacji znajdziesz w artykule Wstawianie elementów inteligentnych w Arkuszach Google.

Dodawanie elementu inteligentnego

Elementy są reprezentowane jako serie elementów, które są częścią CellData, więc możesz wstawić element za pomocą istniejącej metody spreadsheets.batchUpdate, podając UpdateCellsRequest lub AppendCellsRequest.

Żądanie musi zawierać pole chipRuns. Opis elementu zawiera informacje o jego właściwościach i miejscu w tekście komórki.

Podczas pisania chipRuns musisz też podać userEnteredValue, który zawiera symbole zastępcze (@) dla każdego elementu, który chcesz dodać. Każdy przebieg w tablicy chipRuns będzie odpowiadać jednemu z symboli zastępczych. Podczas zapisu można pominąć przebiegi bez chipa.

W tym przykładzie pokazujemy, jak zapisać w jednej komórce (A1) element z plikiem, element z osobami i zwykły tekst. * {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
            }
          }
        }

Konfigurowanie właściwości elementu

Obiekt chipa może mieć jeden z tych typów właściwości:

personProperties

Użyj tej opcji, aby utworzyć element z osobą.

  • email: (Wymagany) Adres e-mail osoby, z którą chcesz połączyć konto.
  • displayFormat: (Opcjonalnie) preferowany format wyświetlania imienia i nazwiska. Może przyjmować jedną z tych wartości:
    • DEFAULT: standardowy format „Imię Nazwisko”.
    • LAST_NAME_COMMA_FIRST_NAME: format „Nazwisko, Imię”.
    • EMAIL: adres e-mail osoby.

Użyj tej metody, aby utworzyć element z linkiem z podglądem. Interfejs API może odczytywać linki do różnych usług Google (takich jak YouTube czy Kalendarz), ale tylko linki do plików na Dysku Google można zapisywać jako elementy.

  • uri: (Wymagany) Identyfikator URI zasobu. W przypadku pisania musi to być link do pliku na Dysku Google. Identyfikatory URI nie mogą przekraczać 2000 bajtów.

Odczytywanie elementu inteligentnego

Aby odczytać dane elementu inteligentnego, użyj metody spreadsheets.get i uwzględnij sheets.data.rowData.values(chipRuns) w parametrze fields.

Tablica chipRuns w odpowiedzi będzie zawierać obiekty dla wszystkich podsekcji tekstu komórki.

  • Biegi z chipem: w tych sekcjach będzie wypełniony obiekt chip zawierający wartość personProperties lub richLinkProperties.
  • Biegi bez chipa: sekcje w formacie zwykłego tekstu również będą miały obiekt biegu, ale jego pole chip będzie puste.

Aby uzyskać tekst wyświetlany w karcie, dodaj formattedValue jako pole.

Aktualizowanie elementu inteligentnego

Aby zaktualizować lub zastąpić element inteligentny, musisz zastąpić zawartość komórki. Użyj tego samego znaku UpdateCellsRequest lub AppendCellsRequest, co w przypadku dodawania elementu, podając nowe wartości userEnteredValue i chipRun. Zastąpi on istniejący element w komórce.

Używanie elementów inteligentnych z innymi funkcjami Arkuszy

Tabele: elementy inteligentne mogą być używane jako typ kolumny tabeli do śledzenia właścicieli projektów (element dotyczący osób) lub powiązanych dokumentów (element dotyczący pliku).

Filtry: możesz filtrować zakresy na podstawie wartości tekstowej inteligentnych elementów w tych zakresach.