Etkileşimli kart veya iletişim kutusu tasarlama

Bu sayfada, kart veya iletişim kutusu mesajlarına widget'ların ve kullanıcı arayüzü öğelerinin nasıl ekleneceği açıklanmaktadır. Böylece kullanıcılar Google Chat uygulamanızla etkileşim kurabilir. Örneğin: veya bilgi göndererek.

Chat uygulamaları için JSON kart mesajları tasarlayıp önizlemek üzere Kart Oluşturucu'yu kullanın:

Kart Oluşturucu'yu açın

Ön koşullar

  • Google Workspace hesabı şunlara erişimi olan: Google Chat.
  • Yayınlanmış bir Chat uygulaması. Bir Chat uygulaması için bunu takip edin hızlı başlangıç kılavuzunu ziyaret edin.

    • Düğme ekle

    İlgili içeriği oluşturmak için kullanılan ButtonList widget'ı bir dizi düğme görüntüler. Düğmeler metin, bir ya da hem metin hem de simge kullanabilirsiniz. Her biri Button bir OnClick işlem Kullanıcılar düğmeyi tıkladığında gerçekleşen etkinlikler. Örneğin:

    • Şununla bir köprü açın: OpenLink, .
    • Bir action API çağırmak gibi özel bir işlev çalıştıran.

    Erişilebilirlik için düğmeler alternatif metni destekler.

    Özel işlev çalıştıran bir düğme ekleme

    Aşağıda, iki düğmeli bir ButtonList widget'ından oluşan bir kart gösterilmektedir. Bir düğme, Google Chat geliştirici belgelerini yeni bir sekmede açar. İlgili içeriği oluşturmak için kullanılan diğer düğme, goToView() adlı özel bir işlev çalıştırır ve viewType="BIRD EYE VIEW" parametresinden yararlanın.

    Özel renk ve devre dışı bırakılmış düğme içeren bir düğme ekleyin

    "disabled": "true" ayarlayarak kullanıcıların bir düğmeyi tıklamalarını engelleyebilirsiniz.

    Aşağıda, iki adet ButtonList widget'ından oluşan bir kart görüntülenir. düğmelerini kullanın. Düğmelerden biri Color alan düğmenin arka planını özelleştirmek için rengi. Diğer düğme, Disabled alanıyla devre dışıdır. Bu alanın Kullanıcının düğmeyi tıklamasını ve işlevi yürütmesini engeller.

    Simge içeren bir düğme ekleyin

    Aşağıda, iki simgeli ButtonList widget'ından oluşan bir kart görüntülenir. Button widget. Düğmelerden biri knownIcon alanında Google Chat'in yerleşik e-posta simgesini görebilirsiniz. Diğer düğme Gösterilecek iconUrl alanı özel simge widget'ını tıklayın.

    Simge ve metin içeren bir düğme ekleyin

    Aşağıda, komut istemi içeren ButtonList widget'ından oluşan bir kart görüntülenir. kullanıcının e-posta göndermesini sağlayın. İlk düğmede bir e-posta simgesi ve ikinci düğmede metin görüntülenir. Kullanıcı, simgeyi veya metni tıklayabilir sendEmail işlevini çalıştırmak için düğme.

    Seçilebilir kullanıcı arayüzü öğeleri ekleyin

    SelectionInput widget'ı onay kutuları, radyo düğmeleri, anahtarlar ve menü gibi veya açılır menü. Bu widget'ı kullanabilirsiniz belirli ve standartlaştırılmış verileri toplayıp toplamaya yardımcı olur. Tanımlanmamış verileri toplamak için TextInput widget'ını kullanın.

    SelectionInput widget'ı, kullanıcıların tek tip giriş yapmasına yardımcı olan önerileri destekler değişime ayak uydurmak amacıyla Actions kullanıcı gibi seçim giriş alanında bir değişiklik gerçekleştiğinde çalıştırılan bir öğeyi seçerek veya seçimini kaldırarak

    Chat uygulamaları, seçilen öğelerin değerini alıp işleyebilir. Form girişleriyle çalışma hakkında ayrıntılar için bkz. Kullanıcıların girdiği bilgileri işlem.

    Bu bölümde, SelectionInput widget'ını kullanan kartlara örnekler verilmiştir. Örneklerde farklı bölüm girişleri kullanılmaktadır:

    Onay kutusu ekle

    Aşağıdaki iletişim, kullanıcıdan bir SelectionInput widget'ı ile hem profesyonel hem de özel birini onay kutuları kullanır:

    Radyo düğmesi ekle

    Aşağıdaki iletişim, kullanıcıdan bir bir SelectionInput widget'ı kullanan bir kişinin profesyonel veya kişisel olması radyo düğmeleri:

    Anahtar ekleme

    Aşağıdaki iletişim, kullanıcıdan bir ya da her ikisini birden yapabileceğiniz bir SelectionInput widget'ı ile kullanır:

    Aşağıdaki iletişim, kullanıcıdan bir bir SelectionInput widget'ı kullanan bir kişinin profesyonel veya kişisel olması bir açılır menü:

    Çoklu seçim menüsü ekle

    Aşağıda, kullanıcıdan kişileri seçmesini isteyen bir iletişim kutusu görüntüleniyor Çoklu seçim menüsünden:

    Çoklu seçim menüleri için veri kaynaklarını kullanma

    Aşağıdaki bölümde, verileri doldurmak için çoklu seçim menülerinin nasıl kullanılacağı açıklanmaktadır Google Workspace uygulaması veya harici veriler gibi dinamik kaynaklardan kaynak.

    Google Workspace'teki veri kaynakları

    Aşağıdaki veri kaynaklarından bir çoklu seçim menüsünün öğelerini doldurabilirsiniz: Google Workspace:

    • Google Workspace kullanıcıları: Yalnızca aynı Google Workspace kuruluşuyla çalışır.
    • Chat alanları: Çoklu seçime öğe giren kullanıcı yalnızca kendi içinde ait oldukları alanları görüntüleyip seçebiliyor. Google Workspace kuruluşu.

    Google Workspace veri kaynaklarını kullanmak için platformDataSource girin. Diğer seçim giriş türlerinin aksine, SectionItem seçilebilir. Bunun nedeni, bu seçim öğelerinin dinamik olarak Google Workspace

    Aşağıdaki kodda, Google Workspace kullanıcılarından oluşan bir çoklu seçim menüsü gösterilmektedir. Seçim girişi, kullanıcıları doldurmak için commonDataSource değerini USER olarak ayarlar:

    JSON

    {
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

    Aşağıdaki kodda Chat için çoklu seçim menüsü gösterilmektedir alanlar'a dokunun. Boşlukları doldurmak için seçim girişi hostAppDataSource alanı boş bırakılamaz. Çoklu seçim menüsü ayrıca, defaultToCurrentSpace olan true değeri, mevcut alan varsayılan olarak ayarlanır menüden seçim:

    JSON

    {
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}
    Google Workspace dışındaki veri kaynakları

    Çoklu seçim menüleri, bir üçüncü taraf verilerinden veya harici verilerden de öğeler doldurabilir kaynak. Örneğin, bir kullanıcının bir listeden seçim yapmasına yardımcı olmak için Bir müşteri ilişkileri yönetimi (CRM) sistemindeki potansiyel müşterilerin listesi.

    Harici bir veri kaynağı kullanmak istiyorsanız externalDataSource alanını kullanarak veri kaynağından öğeler döndüren bir işlev belirtin.

    Harici bir veri kaynağına gönderilen istekleri azaltmak için aşağıdakileri dahil edebilirsiniz: Kullanıcılar giriş yapmadan önce çoklu seçim menüsünde görüntülenen önerilen öğeler tıklayın. Örneğin, yakın zamanda aradığınız kişiler için belirtir. Harici bir veri kaynağından önerilen öğeleri doldurmak için şunları belirtin: SelectionItem nesneler'i tıklayın.

    Aşağıdaki kod bir öğedeki öğelerin çoklu seçim menüsünü gösterir kullanıcı için harici kişi grubudur. Menüde varsayılan olarak bir kişi gösterilir vegetContacts harici veri kaynağı:

    JSON

    {
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

    Harici veri kaynakları için kullanıcıların başlattığı öğeleri otomatik olarak tamamlayabilirsiniz yazarak başlayabilirsiniz. Örneğin, bir kullanıcı bir web sitesi için Atl şehirleri dolduran bir menü. Chat uygulaması, kullanıcıdan önce Atlanta otomatik öneride bulunabilir yazmayı bitirir. En fazla 100 öğeyi otomatik tamamlayabilirsiniz.

    Öğeleri otomatik olarak tamamlamak için harici verileri sorgulayan bir işlev oluşturursunuz kaynak kullanır ve bir kullanıcı çoklu seçim menüsüne her yazdığında öğeleri döndürür. İlgili içeriği oluşturmak için kullanılan fonksiyonunun şunları yapması gerekir:

    • Kullanıcının menüyle etkileşimini temsil eden bir etkinlik nesnesi iletin.
    • Etkileşim etkinliğinin invokedFunction değeri, externalDataSource alanındaki işlevle eşleşir.
    • İşlevler eşleştiğinde harici verilerdeki önerilen öğeleri döndürün kaynak. Kullanıcının yazdıklarına göre öğe önermek için autocomplete_widget_query tuşu. Bu değer, kullanıcının seçeneğini tıklayın.

    Aşağıdaki kod, harici bir veri kaynağındaki öğeleri otomatik olarak tamamlar. Her bir Önceki örneğe dönelim. Chat uygulaması, getContacts işlevi tetiklendiğinde:

    Apps Komut Dosyası

    apps-script/selection-input/on-widget-update.gs
    /**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    Node.js

    node/selection-input/on-widget-update.js
    /**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    Kullanıcının metin girebileceği bir alan ekleyin

    TextInput widget'ı kullanıcıların metin girebileceği bir alan sağlar. İlgili içeriği oluşturmak için kullanılan widget, kullanıcıların tek tip veri girmesine yardımcı olan önerileri ve birçok farklı işlem vardır. Actions metin girişi alanında bir değişiklik gerçekleştiğinde (ör. kullanıcı ekleme işlemi veya metin siliniyor.

    Kullanıcılardan soyut veya bilinmeyen veriler toplamanız gerektiğinde bunu kullanın TextInput widget'ı. Kullanıcılardan tanımlanmış verileri toplamak için SelectionInput widget'ını kullandığınızdan emin olun.

    Kullanıcıların girdiği metni işlemek için bkz. Kullanıcıların girdiği bilgileri işlem.

    Aşağıda, TextInput widget'ından oluşan bir kart gösterilmektedir:

    Kullanıcının tarih ve saat seçmesine izin verme

    İlgili içeriği oluşturmak için kullanılan DateTimePicker widget'ı kullanıcıların tarih, saat veya hem tarih hem de zaman birlikte çalışır. Alternatif olarak, kullanıcılar tarih ve saatleri seçmek için seçiciyi kullanabilir. Kullanıcılar giriş yaparsa Geçersiz tarih veya saat görürseniz seçici, kullanıcılardan giriş yapmalarını isteyen bir hata gösterir bu bilgilerden faydalanabilirsiniz.

    Kullanıcıların girdiği tarih ve saat değerlerini işlemek için şu sayfaya göz atın: Kullanıcıların girdiği bilgileri işlem.

    Aşağıda, üç farklı türde DateTimePicker widget'ı:

    Kartlara girilen verileri doğrulayın

    Bu sayfada bir kartın action öğesine girilen verilerin nasıl doğrulanacağı açıklanmaktadır. ve widget'lar. Örneğin, bir metin giriş alanına veya belirli sayıda karakter içermesidir.

    İşlemler için gerekli widget'ları ayarla

    Kartın action kapsamında bir işlemin requiredWidgets listesine ihtiyaç duyduğu widget'ların adlarını ekler.

    Bu işlem çağrıldığında burada listelenen widget'lardan herhangi birinin bir değeri yoksa form işlemi gönderimi iptal edilir.

    "all_widgets_are_required": "true" bir işlem için ayarlandığında tüm widget'lar bu işlem için gerekli olan seçeneklerdir.

    Çoklu seçimde bir all_widgets_are_required işlemi ayarlayın

    JSON

    {
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "value": "contact-1",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 1",
                "bottomText": "Contact one description",
                "selected": false
              },
              {
                "value": "contact-2",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 2",
                "bottomText": "Contact two description",
                "selected": false
              },
              {
                "value": "contact-3",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 3",
                "bottomText": "Contact three description",
                "selected": false
              },
              {
                "value": "contact-4",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 4",
                "bottomText": "Contact four description",
                "selected": false
              },
              {
                "value": "contact-5",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 5",
                "bottomText": "Contact five description",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

    dateTime Picker'da bir all_widgets_are_required işlemi ayarlayın

    JSON

    {
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}

    Açılır menüden bir all_widgets_are_required işlemi ayarlayın

    JSON

    {
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

    Metin girişi widget'ı için doğrulamayı ayarlama

    textInput içinde widget'ın doğrulama alanını kullanırsa, öğe için karakter sınırlamasını ve giriş türünü belirtebilir widget'ını tıklayın.

    Metin girişi widget'ı için karakter sınırlaması ayarlayın

    JSON

    {
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"character_limit":15},
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        }
      ]
    }
  ]
}

    Metin girişi widget'ı için giriş türünü ayarlayın

    JSON

    {
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "EMAIL"
            },
            "onChangeAction": {
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "input_type": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

    Sorun giderme

    Bir Google Chat uygulaması veya card bir hata döndürürse Chat arayüzünde "Bir sorun oluştu" mesajı gösteriliyor. veya "İsteğiniz işlenemiyor." Chat kullanıcı arayüzü herhangi bir hata mesajı görüntülenmiyor ancak Chat uygulaması veya kart beklenmeyen bir sonuç veriyorsa; Örneğin karttaki bir mesajda görünür.

    Chat kullanıcı arayüzünde hata mesajı görüntülenmese de Hataları düzeltmenize yardımcı olmak için açıklayıcı hata mesajları ve günlük verileri sunulur Chat uygulamaları için hata günlük kaydı etkinleştirildiğinde. Görüntüleme konusunda yardım için ve hataları düzeltme ile ilgili daha fazla bilgi edinmek için Google Chat hatalarını giderme ve düzeltme