Lista przycisków

Widżet ButtonList wyświetla zestaw przycisków. Przyciski mogą zawierać tekst, ikonę lub zarówno tekst, jak i ikonę.

Każde Button obsługuje OnClick działanie, które następuje, gdy użytkownik kliknie ten przycisk. Na przykład:

  • Otwórz hiperlink z wartością OpenLink, np. z dokumentacją dla deweloperów Google Chat w usłudze https://developers.google.com/chat.
  • Uruchom działanie, które będzie przeprowadzać funkcję niestandardową, np. wywoływać interfejs API.

Aby uniemożliwić użytkownikom kliknięcie przycisku, ustaw "disabled": "true".

W przypadku ułatwień dostępu przyciski obsługują tekst zastępczy.

Przykłady

Poniższa ilustracja przedstawia kartę zawierającą widżet ButtonList składający się z dwóch elementów Button. Jeden przycisk otwiera dokumentację dewelopera Google Chat w nowej karcie. Drugi przycisk uruchamia funkcję niestandardową o nazwie goToView() i przekazuje jeden parametr: viewType="Bird Eye View".

Karta z tekstem karty Google Chat z widżetem akapitu.
Ilustracja 1. Wiadomość w Google Chat z kartą przedstawiająca widżet ButtonList z 2 elementami Button

Oto kod JSON karty:

JSON

{
  "cardsV2": [
    {
      "cardId": "exampleCard",
      "card": {
        "sections": [
          {
            "widgets": [
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Open a hyperlink",
                      "onClick": {
                        "openLink": {
                          "url": "https://developers.google.com/chat",
                        }
                      }
                    },
                    {
                      "text": "Run a custom function",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "BIRD EYE VIEW",
                            }
                          ],
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Przykład 2. Przycisk z niestandardowym kolorem i wyłączonym przyciskiem

Poniższa ilustracja przedstawia kartę zawierającą widżet ButtonList składający się z dwóch elementów Button. Do zmiany koloru tła przycisku służy jeden przycisk w polu Color. Drugi przycisk jest dezaktywowany za pomocą pola Disabled, które uniemożliwia użytkownikowi kliknięcie przycisku i wykonanie funkcji.

Wiadomość na karcie w Google Chat przedstawiająca widżet ButtonList.
Ilustracja 2. Wiadomość w Google Chat na karcie przedstawiająca widżet ButtonList z 2 Button

Oto kod JSON karty:

JSON

{
 "cards_v2":[
    {
       "card_id":"exampleCard",
       "card":{
          "sections":[
             {
                "widgets":[
                   {
                      "buttonList":{
                         "buttons":[
                            {
                               "text":"View documentation hyperlink",
                               "onClick":{
                                  "openLink":{
                                     "url":"https://developers.google.com/chat"
                                  }
                               },
                               "color":{
                                  "red":0,
                                  "green":0,
                                  "blue":1,
                                  "alpha":0.5
                               }
                            },
                            {
                               "text":"Button disabled",
                               "onClick":{
                                  "openLink":{
                                     "url":"https://developers.google.com/chat"
                                  }
                               },
                               "disabled":true
                            }
                         ]
                      }
                   }
                ]
             }
          ]
       }
    }
 ]
}

Przykład 3: przyciski z ikonami

Poniższa ilustracja przedstawia kartę zawierającą widżet ButtonList z 2 ikonami: Button. Jeden przycisk używa pola [knownIcon]((https://developers.google.com/chat/api/guides/message-formats/cards#builtinicons)) do wyświetlania wbudowanej ikony e-maila w Google Chat. Drugi przycisk wyświetla pole niestandardowej widżetu w polu iconUrl.

Wiadomość na karcie w Google Chat przedstawiająca widżet ButtonList.
Ilustracja 3. Wiadomość w Google Chat na karcie przedstawiająca widżet ButtonList z 2 ikonami Button

Oto kod JSON karty:

JSON

{
"cards_v2": [
  {
  "card_id": "exampleCard",
  "card": {
    "sections": [
    {
      "widgets": [
      {
        "buttonList": {
          "buttons": [
                          {
              "icon": {"knownIcon": "EMAIL",},
              "onClick": {
                "action": {
                  "function": "sendEmail",
                  "parameters": [
                    {
                      "key": "emailContent",
                      "value": "Email value",
                    }
                  ],
                }
              }
            },
            {
              "icon": {"iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png",},
              "onClick": {
                "action": {
                  "function": "inviteBot",
                  "parameters": [
                    {
                      "key": "botType",
                      "value": "Bot value",
                    }
                  ],
                }
              }
            },
          ]
        }
      }
    ]
    }
    ]
  }
  }
]
}

Przykład 4: przyciski z ikoną i tekstem

Poniższa ilustracja przedstawia kartę zawierającą widżet ButtonList z prośbą o wysłanie e-maila. Na pierwszym przycisku wyświetla się ikona e-maila, a na drugim – tekst. Użytkownik może kliknąć ikonę lub przycisk tekstowy, aby wykonać funkcję sendEmail.

Wiadomość na karcie w Google Chat przedstawiająca widżet ButtonList.
Ilustracja 1. Wiadomość w Google Chat z kartą przedstawiająca widżet ButtonList z 2 elementami Button

Oto kod JSON karty:

JSON

{
"cards_v2": [
  {
  "card_id": "exampleCard",
  "card": {
    "sections": [
    {
      "widgets": [
      {
        "buttonList": {
          "buttons": [
                          {
              "icon": {"knownIcon": "EMAIL",},
              "onClick": {
                "action": {
                  "function": "sendEmail",
                  "parameters": [
                    {
                      "key": "emailContent",
                      "value": "Email value",
                    }
                  ],
                }
              }
            },
            {
              "text": "Send email",
              "onClick": {
                "action": {
                  "function": "sendEmail",
                  "parameters": [
                    {
                      "key": "sendEmailType",
                      "value": "email value",
                    }
                  ],
                }
              }
            },
          ]
        }
      }
    ]
    }
    ]
  }
  }
]
}

Reprezentacja i pola JSON

Zapis JSON
{
  "buttons": [
    {
      object (Button)
    }
  ]
}
Pola
buttons[]

object (Button)

Tablica przycisków.

Przycisk

Zapis JSON
{
  "text": string,
  "icon": {
    object (Icon)
  },
  "color": {
    object (Color)
  },
  "onClick": {
    object (OnClick)
  },
  "disabled": boolean,
  "altText": string
}
Pola
text

string

Tekst wyświetlany na przycisku.

icon

object (Icon)

Obraz ikony. Jeśli ustawione są icon i text, przed tekstem pojawia się ikona.

color

object (Color)

Po ustawieniu przycisk jest wypełniany jednolitym kolorem tła, a kolor czcionki zmienia się, aby zachować kontrast z kolorem tła. Na przykład ustawienie niebieskiego tła powoduje, że pojawia się biały tekst.

Jeśli zasada jest nieskonfigurowana, tło obrazu jest białe, a czcionka ma kolor niebieski.

W przypadku czerwonych, zielonych i niebieskich wartości każdego pola można podać float wartość, którą możesz wyrazić na 2 sposoby: jako liczbę z zakresu od 0 do 255 podzieloną przez 255 (153/255) lub jako wartość od 0 do 1 (0,6). 0 oznacza brak koloru i 1 lub 255/255 oznacza pełną obecność tego koloru w skali RGB.

Opcjonalnie ustaw alpha, aby ustawić poziom przezroczystości za pomocą tego równania:

pixel color = alpha * (this color) + (1.0 - alpha) * (background color)

W przypadku alpha wartość 1 odpowiada jednolitemu kolorowi, wartość 0 odpowiada całkowicie przezroczystemu kolorowi.

Na przykład ten kolor to półprzezroczysty czerwony:

"color": {
   "red": 1,
   "green": 0,
   "blue": 0,
   "alpha": 0.5
}
onClick

object (OnClick)

Wymagany. Działanie wykonywane, gdy użytkownik kliknie przycisk – na przykład otworzy hiperlink lub uruchomi funkcję niestandardową.

disabled

boolean

Jeśli true jest wyświetlany, przycisk jest nieaktywny i nie reaguje na działania użytkownika.

altText

string

Tekst alternatywny używany przy ułatwieniach dostępu.

Ustaw tekst opisowy informujący użytkowników o przeznaczeniu przycisku. Jeśli na przykład przycisk uruchamia hiperlink, możesz napisać: „Otwiera nową kartę przeglądarki i otwiera dokumentację dla deweloperów Google Chat na stronie https://developers.google.com/chat”.

Ikona

Ikona wyświetlana w widżecie na karcie.

Obsługuje ikony wbudowane i niestandardowe.

Zapis JSON
{
  "altText": string,
  "imageType": enum (ImageType),

  // Union field icons can be only one of the following:
  "knownIcon": string,
  "iconUrl": string
  // End of list of possible types for union field icons.
}
Pola
altText

string

Opcjonalnie. Opis ikony ułatwień dostępu. Jeśli wartość nie jest określona, podawana jest wartość domyślna Button. Dobrze jest utworzyć przydatny opis tego, co wyświetla się ikona (w razie potrzeby). na przykład A user's account portrait lub Opens a new browser tab and navigates to the Google Chat developer documentation at https://developers.google.com/chat.

Jeśli ikonę jest ustawiona w Button, altText pojawi się jako tekst pomocniczy, gdy użytkownik najedzie na przycisk. Jeśli jednak przycisk ustawia też typ text, wartość altText jest ignorowana.

imageType

enum (ImageType)

Styl przycinania zastosowany do obrazu. W niektórych przypadkach zastosowanie przycięcia w formacie CIRCLE powoduje, że obraz jest pobierany jako większy niż wbudowana ikona.

Pole sumy: icons. Ikona wyświetlana w widżecie na karcie. icons może być tylko jedną z tych wartości:
knownIcon

string

Wyświetlaj jedną z wbudowanych ikon Google Workspace.

Aby na przykład wyświetlić ikonę samolotu, podaj AIRPLANE. W przypadku autobusu określ BUS.

Pełną listę obsługiwanych ikon znajdziesz w sekcji Ikony wbudowane.

iconUrl

string

Wyświetlaj ikonę niestandardową hostowaną pod adresem URL HTTPS.

Na przykład:

"iconUrl":
"https://developers.google.com/chat/images/quickstart-app-avatar.png"

Obsługiwane typy plików to .png i .jpg.

Typ obrazu

Kształt używany do przycinania.

Wartości w polu enum
SQUARE Wartość domyślna. Stosuje do maski kwadratową. Na przykład obraz o wymiarach 4 × 3 stanie się obrazem 3 × 3.
CIRCLE Stosuje do maski okrągłą. Na przykład obraz o wymiarach 4 × 3 zmienia się w koło o średnicy 3.

Kolor

Zapis JSON
{
  "red": number,
  "green": number,
  "blue": number,
  "alpha": number
}
Pola
red

number

Czerwony kolor w postaci wartości z przedziału [0, 1].

green

number

Zielony kolor w wartościach z przedziału [0, 1].

blue

number

Niebieski kolor w wartościach z przedziału [0, 1].

alpha

number

Odsetek tego koloru, który należy zastosować w pikselu. Oznacza to, że końcowy kolor piksela jest określany za pomocą równania:

pixel color = alpha * (this color) + (1.0 - alpha) * (background color)

Oznacza to, że wartość 1,0 odpowiada jednolitemu kolorowi, a wartość 0,0 odpowiada całkowicie przezroczystemu kolorowi. Korzysta on z kodu towarzyszącego, a nie z prostego skalarnego skalarnego, dzięki czemu można odróżnić wartość domyślną od ustawionej. Jeśli ten warunek zostanie pominięty, obiekt koloru jest renderowany jako jednolity kolor (tak jakby wartość alfa wynosiła 1,0).

Po kliknięciu

Wskazuje, jak zareagować, gdy użytkownik kliknie interaktywny element na karcie, np. przycisk.

Zapis JSON
{

  // Union field data can be only one of the following:
  "action": {
    object (Action)
  },
  "openLink": {
    object (OpenLink)
  },
  "openDynamicLinkAction": {
    object (Action)
  },
  "card": {
    object (Card)
  }
  // End of list of possible types for union field data.
}
Pola

Pole sumy: data.

data może być tylko jedną z tych wartości:

action

object (Action)

Jeśli zasada jest określona, działanie jest wywoływane przez to zdarzenie onClick.

card

object (Card)

Nowa karta jest przesyłana do stosu kart po kliknięciu, jeśli został określony.

Obsługiwana przez dodatki do Google Workspace, ale nie przez aplikacje Google Chat.