Kartlara etkileşimli kullanıcı arayüzü öğeleri ekleyin

Bu sayfada, widget'ların ve kullanıcı arayüzü öğelerinin kartlara 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ı aşağıdaki Chat arayüzlerini kullanabilir aşağıdaki adımları izleyin:

  • Mesajlar içeren bir e-posta alırsınız.
  • Ana sayfalar Bu, doğrudan Ana Sayfa sekmesinde görünen bir karttır. sohbet mesajı gönderebilir.
  • İletişim kutuları, yani iletişim kutusunda yeni bir pencerede açılır.

Kullanıcılar kartlarla etkileşimde bulunduğunda, Chat uygulamaları uygun şekilde işleme koymaları ve bunlara yanıt vermeleri gerekir. Ayrıntılar için bkz. Google Chat kullanıcılarından bilgi toplayın ve bu bilgileri işleyin.


Chat uygulamaları için mesajlaşma ve kullanıcı arayüzleri tasarlayıp önizlemek üzere Kart Oluşturucu'yu kullanın:

Kart Oluşturucu'yu açın

Ön koşullar

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. Bir aşağıdaki hızlı başlangıç kılavuzlarından birini kullanarak oluşturmak istediğiniz uygulama mimarisinde:

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.

Materyal Tasarım stiline sahip bir düğme ekle

Aşağıda, farklı Materyal Tasarım düğmelerinde bir dizi düğme görüntüleniyor stillerini ayarlayın.

Materyal Tasarım stilini uygulamak için "color" (renk) eklemeyin özelliğini gönderin.

Ö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.

Daraltılabilir bölüm için düğmeyi özelleştirin

Bir kartını inceleyebilirsiniz. Bir öğeyi görsel olarak temsil edecek bir dizi simge veya resim arasından seçim yapın Böylece, kullanıcıların anlaması ve etkileşime geçmesi kolay bir hale gelir. bahsedeceğim.

Taşma Menüsü Ekle

İlgili içeriği oluşturmak için kullanılan Overflow menu , ek seçenekler ve işlemler sunmak için Chat kartlarında kullanılabilir. O halde Kartın arayüzünü sadeleştirerek daha fazla seçenek sunabilirsiniz. düzenli tasarım.

Çip listesi ekle

ChipList widget'ı, bilgileri görüntülemenin çok yönlü ve görsel olarak çekici bir yolunu sunar. Etiketleri, kategorileri veya diğer alakalı verileri temsil etmesi için çip listelerini kullanın. ve içeriğinizle etkileşime geçmelerini kolaylaştırır.

Kullanıcılardan bilgi toplama

Bu bölümde, aşağıdakiler gibi bilgi toplayan widget'ları nasıl ekleyebileceğinizi açıklar: metin veya seçimler yapın.

Kullanıcıların girdilerini nasıl işleyeceğinizi öğrenmek için bkz. Google Chat kullanıcılarından bilgi toplayın ve bu bilgileri işleyin.

Metin toplama

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.

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

Tarih veya saati topla

İ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 alırsa seçici, kullanıcılardan giriş yapmalarını isteyen bir hata gösterir bu bilgilerden faydalanabilirsiniz.

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

Kullanıcıların öğe seçmesine izin ver

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 bir 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 işlem bilgileri.

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ğıda, kullanıcıdan giriş yapılıp yapılmadığını SelectionInput widget'ı ile hem profesyonel hem de özel birini onay kutuları kullanır:

Radyo düğmesi ekle

Aşağıda, kullanıcıdan giriş yapılıp yapılmadığını bir SelectionInput widget'ı kullanan bir kişinin profesyonel veya kişisel olması radyo düğmeleri:

Anahtar ekleme

Aşağıda, kullanıcıdan giriş yapılıp yapılmadığını ya da her ikisini birden yapabileceğiniz bir SelectionInput widget'ı ile kullanır:

Aşağıda, kullanıcıdan giriş yapılıp yapılmadığını 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 kart gösterilmektedir Çoklu seçim menüsünden:

Aşağıdaki verilerden çoklu seçim menüsü için öğeleri doldurabilirsiniz Google Workspace'teki kaynaklar:

  • Google Workspace kullanıcıları: Yalnızca aynı Google Workspace kuruluşuyla ilişkilidir.
  • 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 olacaktır, çünkü 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
          }
        }
      }
    }
  }
}

Ç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 isteklerin sayısını 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
            },
          ]
        }
      }
    }
  };
}

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