Seçim girişi

SelectionInput widget'ı onay kutuları, radyo düğmeleri, anahtarlar veya açılır menü gibi seçilebilir bir öğe grubu sağlar. Kullanıcılardan tanımlanmış ve standartlaştırılmış verileri toplamak için bu widget'ı kullanabilirsiniz. Kullanıcılardan tanımlanmamış veriler toplamak için bunun yerine TextInput widget'ını kullanın.

SelectionInput widget'ı, kullanıcıların tek tip veri girmelerine yardımcı olan önerileri ve değişiklik yapılan işlemleri destekler. Bunlar, kullanıcının seçim girişi alanında bir öğeyi seçmesi veya seçimini kaldırması gibi bir değişiklik gerçekleştiğinde çalışan Actions işlemleridir.

Chat uygulamaları, seçilen öğelerin değerini alabilir ve işleyebilir. Form girişleriyle çalışma hakkında ayrıntılı bilgi için Form verilerini alma bölümüne bakın.

Örnekler

Bu bölümde, SelectionInput widget'ını kullanan kartlara dair örnekler yer almaktadır. Örneklerde farklı türde bölüm girişleri kullanılmaktadır:

• Onay kutuları
• Radyo düğmeleri
• Anahtarlar
• Açılır menü
• Çoklu seçim menüsü

1. Örnek: onay kutuları

Aşağıda, kullanıcıdan, onay kutuları kullanan bir SelectionInput widget'ıyla bir kişinin profesyonel ve/veya kişisel olup olmadığını belirtmesini isteyen bir iletişim kutusu görüntülenmektedir:

2. Örnek: radyo düğmeleri

Aşağıda, kullanıcıdan, radyo düğmeleri kullanan bir SelectionInput widget'ındaki bir kişinin profesyonel mi yoksa kişisel mi olduğunu belirtmesini isteyen bir iletişim kutusu görüntülenmektedir:

3. örnek: anahtarlar

Aşağıda, kullanıcıdan, anahtar kullanan bir SelectionInput widget'ındaki bir kişinin profesyonel mi yoksa kişisel mi olduğunu belirtmesini isteyen bir iletişim kutusu görüntülenmektedir:

4. Örnek: Açılır menü

Aşağıda, kullanıcıdan, açılır menü kullanan bir SelectionInput widget'ını kullanarak kişinin profesyonel mi yoksa kişisel mi olduğunu belirtmesini isteyen bir iletişim kutusu görüntülenmektedir:

5. Örnek: çoklu seçim menüsü

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

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

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

Google Workspace'teki veri kaynakları

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

• Google Workspace kullanıcıları: Yalnızca aynı Google Workspace kuruluşundaki kullanıcıları doldurabilirsiniz.
• Chat alanları: Çoklu seçim menüsüne öğe giren kullanıcı, yalnızca kendi Google Workspace kuruluşunda ait olduğu alanları görüntüleyebilir ve seçebilir.

Google Workspace veri kaynaklarını kullanmak için platformDataSource alanını belirtirsiniz. Diğer seçim giriş türlerinin aksine, bu seçim öğeleri dinamik olarak Google Workspace'ten alındığı için SectionItem nesnelerini çıkarırsınız.

Aşağıdaki kodda, Google Workspace kullanıcılarından oluşan çoklu seçim menüsü gösterilmektedir. Kullanıcıları doldurmak için seçim girişi 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 kod, Chat alanlarının çok seçimli bir menüsünü göstermektedir. Boşlukları doldurmak için seçim girişi hostAppDataSource alanını belirtir. Çoklu seçim menüsü de defaultToCurrentSpace değerini true olarak ayarlar. Böylece mevcut alan, menüde varsayılan seçim olarak belirlenir:

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, öğeleri üçüncü taraf veya harici bir veri kaynağından da doldurabilir. Örneğin, kullanıcının bir müşteri ilişkileri yönetimi (CRM) sistemindeki potansiyel müşteriler listesinden seçim yapmasına yardımcı olmak için çoklu seçim menülerini kullanabilirsiniz.

Harici bir veri kaynağı kullanmak için veri kaynağından öğe döndüren bir işlev belirtmek üzere externalDataSource alanını kullanırsınız.

Harici veri kaynağına gönderilen istekleri azaltmak için, kullanıcılar menüye yazmadan önce çoklu seçim menüsünde görünen önerilen öğeleri ekleyebilirsiniz. Örneğin, kullanıcı için son aranan kişileri doldurabilirsiniz. Önerilen öğeleri harici bir veri kaynağından doldurmak için SelectionItem nesnelerini belirtin.

Aşağıdaki kod, kullanıcıya ait harici bir kişi grubundan öğe içeren çoklu seçim menüsünü gösterir. Menü varsayılan olarak bir kişi görüntüler ve harici veri kaynağından öğe almak ve doldurmak için getContacts işlevini çalıştırır:

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ında, kullanıcıların çoklu seçim menüsünde yazmaya başladığı öğeleri otomatik olarak tamamlayabilirsiniz. Örneğin, bir kullanıcı ABD'deki şehirleri dolduran bir menü için Atl yazmaya başlarsa Chat uygulamanız kullanıcı yazmayı tamamlamadan otomatik olarak Atlanta önerisinde bulunabilir. 100 adede kadar öğeyi otomatik tamamlayabilirsiniz.

Öğeleri otomatik olarak tamamlamak için harici veri kaynağını sorgulayan ve bir kullanıcı çoklu seçim menüsüne her yazı yazarken öğe döndüren bir işlev oluşturursunuz. İşlev aşağıdakileri yapmalıdır:

• Kullanıcının menüyle etkileşimini temsil eden bir etkinlik nesnesi iletin.
• Etkileşim etkinliğinin invokedFunction değerinin externalDataSource alanındaki işlevle eşleştiğini belirleyin.
• İşlevler eşleştiğinde harici veri kaynağından önerilen öğeleri döndürün. Kullanıcının yazdıklarına bağlı olarak öğe önermek için autocomplete_widget_query anahtarının değerini alın. Bu değer, kullanıcının menüye ne yazdığını gösterir.

Aşağıdaki kod, harici bir veri kaynağındaki öğeleri otomatik olarak tamamlar. Önceki örnekte, Chat uygulaması getContacts işlevinin tetiklendiği zamana dayalı olarak öğeler önerir:

Apps Komut Dosyası

apps-script/selection-input/on-widget-update.gs

GitHub'da göster

/**
 * 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

GitHub'da göster

/**
 * 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
            },
          ]
        }
      }
    }
  };
}

JSON gösterimi ve alanları

JSON gösterimi

{ "name": string, "label": string, "type": enum (SelectionType), "items": [ { object (SelectionItem) } ], "onChangeAction": { object (Action) }, "multiSelectMaxSelectedItems": integer, "multiSelectMinQueryLength": integer, // Union field multi_select_data_source can be only one of the following: "externalDataSource": { object (Action) }, "platformDataSource": { object (PlatformDataSource) } // End of list of possible types for union field multi_select_data_source. }

Alanlar
name	string Bir form giriş etkinliğindeki seçim girişini tanımlayan ad. Form girişleriyle çalışma hakkında ayrıntılı bilgi için Form verilerini alma bölümüne bakın.
label	string Kullanıcı arayüzünde, seçim giriş alanının üzerinde görünen metin. Kullanıcının, uygulamanızın ihtiyacı olan bilgileri girmesine yardımcı olacak metni belirtin. Örneğin, kullanıcılar açılır menüden iş biletinin aciliyetini seçiyorsa "Aciliyet" veya "Aciliyet durumunu seçin" etiketi olabilir.
type	enum (SelectionType) SelectionInput widget'ında kullanıcılara gösterilen öğelerin türü. Seçim türleri farklı etkileşim türlerini destekler. Örneğin, kullanıcılar bir veya daha fazla onay kutusu seçebilir, ancak bir açılır menüden yalnızca bir değer seçebilir.
items[]	object (SelectionItem) Seçilebilir öğelerden oluşan bir dizi. Örneğin, bir dizi radyo düğmesi veya onay kutusu. 100 adede kadar öğeyi destekler.
onChangeAction	object (Action) Belirtilmişse form, seçim değiştiğinde gönderilir. Belirtilmemişse formu gönderen ayrı bir düğme belirtmeniz gerekir. Form girişleriyle çalışma hakkında ayrıntılı bilgi için Form verilerini alma bölümüne bakın.
multiSelectMaxSelectedItems	integer Çoklu seçim menüleri için, bir kullanıcının seçebileceği maksimum öğe sayısı. Minimum değer 1 öğedir. Belirtilmemişse varsayılan olarak 3 öğe olur.
multiSelectMinQueryLength	integer Çoklu seçim menülerinde, kullanıcının Chat uygulaması sorgulamasından önce girdiği metin karakteri sayısı otomatik olarak tamamlanır ve menüde önerilen öğeler gösterilir. Belirtilmemişse varsayılan olarak statik veri kaynakları için 0 karakter, harici veri kaynakları için 3 karakter varsayılan olur.
Birlik alanı multi_select_data_source. Yalnızca sohbet uygulamaları. Çoklu seçim menüsü için, seçim öğelerini dolduran veri kaynağı. multi_select_data_source, aşağıdakilerden yalnızca biri olabilir:
externalDataSource	object (Action) İlişkisel veri tabanı gibi harici bir veri kaynağı.
platformDataSource	object (PlatformDataSource) Google Workspace'ten bir veri kaynağı.

SelectionType

Sıralamalar
CHECK_BOX	Bir dizi onay kutusu. Kullanıcılar bir veya daha fazla onay kutusunu işaretleyebilir.
RADIO_BUTTON	Bir dizi radyo düğmesi. Kullanıcılar bir radyo düğmesi seçebilir.
SWITCH	Bir anahtar grubu. Kullanıcılar bir veya daha fazla anahtarı açabilir.
DROPDOWN	Açılır menü. Kullanıcılar menüden bir öğe seçebilir.
MULTI_SELECT	Chat uygulamaları tarafından desteklenir ancak Google Workspace Eklentileri tarafından desteklenmez. Statik veya dinamik veriler için çoklu seçim menüsü. Kullanıcılar, menü çubuğundan bir veya daha fazla öğe seçer. Kullanıcılar dinamik verileri doldurmak için değer de girebilir. Örneğin, kullanıcılar bir Google Chat alanının adını yazmaya başlayabilir. Widget, alanı otomatik olarak önerir. Çoklu seçim menüsündeki öğeleri doldurmak için aşağıdaki veri kaynağı türlerinden birini kullanabilirsiniz: Statik veri: Öğeler widget'ta SelectionItem nesneleri olarak belirtilir. En fazla 100 öğe. Google Workspace verileri: Öğeler, Google Workspace kullanıcıları veya Google Chat alanları gibi Google Workspace verileri kullanılarak doldurulur. Harici veriler: Öğeler Google Workspace dışındaki bir harici veri kaynağından doldurulur. Çoklu seçim menülerinin nasıl uygulanacağına ilişkin örnekler için SelectionInput widget sayfasına bakın.

SelectionItem

JSON gösterimi
{ "text": string, "value": string, "selected": boolean, "startIconUri": string, "bottomText": string }

Alanlar
text	string Öğeyi tanımlayan veya kullanıcılara açıklayan metin.
value	string Bu öğeyle ilişkilendirilen değer. Müşteri bunu bir form girişi değeri olarak kullanmalıdır. Form girişleriyle çalışma hakkında ayrıntılı bilgi için Form verilerini alma bölümüne bakın.
selected	boolean Öğenin varsayılan olarak seçili olup olmadığı. Seçim girişi yalnızca bir değer kabul ediyorsa (radyo düğmeleri veya açılır menü gibi) bu alanı yalnızca bir öğe için ayarlayın.
startIconUri	string Çoklu seçim menülerinde, öğenin text alanının yanında görüntülenen simgenin URL'si. PNG ve JPEG dosyalarını destekler. HTTPS URL'si olmalıdır. Örneğin, https://developers.google.com/chat/images/quickstart-app-avatar.png.
bottomText	string Çoklu seçim menüleri için, öğenin text alanının altında görüntülenen bir metin açıklaması veya etiket.

İşlem

Form gönderildiğinde davranışı açıklayan bir işlem. Örneğin, formu işlemek için bir Apps Komut Dosyası'nı çağırabilirsiniz. İşlem tetiklenirse form değerleri sunucuya gönderilir.

JSON gösterimi
{ "function": string, "parameters": [ { object (ActionParameter) } ], "loadIndicator": enum (LoadIndicator), "persistValues": boolean, "interaction": enum (Interaction) }

Alanlar
function	string İçeren öğe tıklandığında veya otomatik olarak etkinleştirildiğinde çağrılacak özel bir işlev. Örneğin kullanımı Etkileşimli kartlar oluşturma başlıklı makalede bulabilirsiniz.
parameters[]	object (ActionParameter) İşlem parametrelerinin listesi.
loadIndicator	enum (LoadIndicator) Harekete geçirici mesajda bulunurken görüntülenen yükleme göstergesini belirtir.
persistValues	boolean İşlemden sonra form değerlerinin korunup korunmayacağını belirtir. false, varsayılan değerdir. true ise form değerleri işlem tetiklendikten sonra kalır. İşlem işlenirken kullanıcının değişiklik yapmasına izin vermek için LoadIndicator özelliğini NONE olarak ayarlayın. Chat uygulamalarındaki kart mesajları için işlemin ResponseType değerini de UPDATE_MESSAGE olarak ayarlamanız ve işlemi içeren karttaki cardId etiketinin aynısını kullanmanız gerekir. false ise işlem tetiklendiğinde form değerleri temizlenir. İşlem işlenirken kullanıcının değişiklik yapmasını engellemek için LoadIndicator özelliğini SPINNER olarak ayarlayın.
interaction	enum (Interaction) İsteğe bağlı. İletişim kutusu açarken gereklidir. Bir kullanıcıyla etkileşime (ör. bir kullanıcının kart mesajındaki bir düğmeyi tıklaması) yanıt olarak yapılması gereken işlem. Belirtilmemişse uygulama, normal şekilde bir action yürüterek (ör. bir bağlantıyı açma veya bir işlevi çalıştırma) yanıt verir. Bir interaction belirtildiğinde, uygulama özel etkileşimli yollarla yanıt verebilir. Örneğin, interaction OPEN_DIALOG olarak ayarlandığında uygulama bir iletişim kutusu açabilir. Belirtildiğinde, bir yükleme göstergesi gösterilmez. Chat uygulamaları tarafından desteklenir ancak Google Workspace Eklentileri tarafından desteklenmez. Bir eklenti için belirtilirse kartın tamamı kaldırılır ve istemcide hiçbir şey gösterilmez.

ActionParameter

İşlem yöntemi çağrıldığında sağlanacak dize parametrelerinin listesi. Örneğin, şu üç erteleme düğmesini kullanabilirsiniz: Şimdi ertele, bir gün ertele veya gelecek hafta ertele. action method = snooze() kullanarak dize parametreleri listesinde erteleme türünü ve erteleme süresini iletebilirsiniz.

Daha fazla bilgi için CommonEventObject sayfasına bakın.

JSON gösterimi
{ "key": string, "value": string }

Alanlar
key	string İşlem komut dosyası için parametrenin adı.
value	string Parametrenin değeri.

LoadIndicator

Harekete geçirici mesajda bulunurken görüntülenen yükleme göstergesini belirtir.

Sıralamalar
SPINNER	İçeriğin yüklenmekte olduğunu belirten bir döner simge görüntüler.
NONE	Hiçbir şey gösterilmez.

Etkileşim

İsteğe bağlı. İletişim kutusu açarken gereklidir.

Bir kullanıcıyla etkileşime (ör. bir kullanıcının kart mesajındaki bir düğmeyi tıklaması) yanıt olarak yapılması gereken işlem.

Belirtilmemişse uygulama, normal şekilde bir action yürüterek (ör. bir bağlantıyı açma veya bir işlevi çalıştırma) yanıt verir.

Bir interaction belirtildiğinde, uygulama özel etkileşimli yollarla yanıt verebilir. Örneğin, interaction OPEN_DIALOG olarak ayarlandığında uygulama bir iletişim kutusu açabilir.

Belirtildiğinde, bir yükleme göstergesi gösterilmez.

Chat uygulamaları tarafından desteklenir ancak Google Workspace Eklentileri tarafından desteklenmez. Bir eklenti için belirtilirse kartın tamamı kaldırılır ve istemcide hiçbir şey gösterilmez.

Sıralamalar
INTERACTION_UNSPECIFIED	Varsayılan değer. action, normal şekilde çalışır.
OPEN_DIALOG	Chat uygulamalarının kullanıcılarla etkileşimde bulunmak için kullandığı pencereli, kart tabanlı bir arayüz olan iletişim kutusunu açar. Kart mesajlarındaki düğme tıklamalarına yanıt olarak yalnızca Chat uygulamaları tarafından desteklenir. Google Workspace Eklentileri tarafından desteklenmez. Bir eklenti için belirtilirse kartın tamamı kaldırılır ve istemcide hiçbir şey gösterilmez.

Sorun giderme

Bir Google Chat uygulaması veya kart hata döndürdüğünde Chat arayüzünde "Bir sorun oluştu" veya "İsteğiniz işleme alınamıyor" mesajı gösterilir. Bazen Chat kullanıcı arayüzünde hata mesajı gösterilmez ancak Chat uygulaması veya kartı beklenmedik bir sonuç üretir. Örneğin, bir kart mesajı görünmeyebilir.

Chat kullanıcı arayüzünde bir hata mesajı gösterilmese de, Chat uygulamaları için hata günlük kaydı etkinken hataları düzeltmenize yardımcı olmak üzere açıklayıcı hata mesajları ve günlük verileri kullanılabilir. Hataları görüntüleme, hata ayıklama ve düzeltme konusunda yardım almak için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.