form

Bir cümlenin yetersiz kaldığı durumlar için yapılandırılmış girdi. form, bir ila on arasında tipli alanı toplar ve bunları bir mesajdan ayrı bir istek biçimi olan form_submission olarak geri gönderir; böylece değerler düz metinden ayrıştırılmak yerine tipli olarak iletilir.

Aşağıda listelenen on üç alan türü: altı temel tür (text, number, select, toggle, date, time) ve Flutter 0.41.0 / Web 0.18.0 sürümünden itibaren email, tel, url, multiline, multi_select, date_range ve upload.

Flutter SDK ve Web SDK ile, her ikisi de 0.1.0 sürümünden itibaren yerel olarak render edilir; form v2 türleri, autofill, sayı ve tarih sınırları, stepper ve aranabilir seçimler Flutter 0.41.0 ve Web 0.18.0 sürümünden itibaren render edilir.

Ne zaman kullanılmamalı?

Birkaç yanıtı olan tek bir soru için form kullanmayın. Bunun için choice vardır ve iki dokunma yerine tek dokunmayla çalışır.

Randevu almak için time alanı kullanmayın: kullanıcı hangi saatlerin uygun olduğunu bilemez, bu nedenle bunun yerine datetime_slots sunun. Bir şeyi onaylamak için de form kullanmayın: onaylama işlemi sunucu tarafında oluşturulan confirm_card bileşenidir.

Alan türleri

autofill, alanın ne için olduğunu belirtir (name, email, tel, street_address, postal_code, city, country); böylece cihaz bu alanı otomatik doldurabilir.

Bir formun asla istemeyeceği şeyler

Alanı parola, tek kullanımlık veya SMS kodu, kart numarası, CVV, PIN veya güvenlik kodu, IBAN ya da kimlik veya pasaport numarası olarak adlandırılan, etiketlenen veya tanımlanan bir form, istemde ne yazarsa yazsın asla gösterilmez: sunucu bunun yerine fallback_text değerini koyar. Bir asistanın içinde böyle bir form kimlik avı (phishing) gibi görünür. IBAN yalnızca aksiyonlarınızdan birinin parametresi olarak istenir.

upload, siz Files in forms ayarını açana kadar (Settings → Keys & environments) kapalıdır. Form aracılığıyla gönderilen dosyalar Rendel'e diğer tüm ekler gibi ulaşır ve bunları yükleyen cihaza göre kontrol edilir. Bir dosya, içinde bulunduğu sohbet ile birlikte silinir; bir turda hiçbir zaman gönderilmeyen dosya ise bir gün sonra silinir.

Props

Her blok ayrıca type ve 1 ila 300 karakterden oluşan zorunlu bir fallback_text taşır.

Ağ üzerinde

{
  "id": "blk_11",
  "type": "form",
  "fallback_text": "A return request form: order number, reason, number of pairs.",
  "props": {
    "form_id": "return_request",
    "title": "Start a return",
    "fields": [
      {
        "kind": "text",
        "name": "order_id",
        "label": "Order number",
        "required": true,
        "placeholder": "1042"
      },
      {
        "kind": "select",
        "name": "reason",
        "label": "Reason",
        "required": true,
        "options": [
          {
            "label": "Too small",
            "value": "too_small"
          },
          {
            "label": "Arrived damaged",
            "value": "damaged"
          }
        ]
      },
      {
        "kind": "number",
        "name": "pairs",
        "label": "How many pairs",
        "required": true
      },
      {
        "kind": "toggle",
        "name": "keep_box",
        "label": "I still have the original box"
      }
    ],
    "submit_label": "Request pickup"
  }
}

Etkileşim

Gönderim işlemi doğrular, ardından iletir:

{
  "form_submission": {
    "form_id": "return_request",
    "values": { "order_id": "1042", "reason": "damaged", "pairs": 2, "keep_box": true }
  }
}

Değerler string, number, boolean veya dize listesidir. Bir number alanı sayı olarak gönderilir; date YYYY-MM-DD ve time HH:mm biçiminde gönderir; multi_select işaretli değerleri, upload ise upload id değerlerini liste olarak gönderir; date_range ise iki dize gönderir: {name}_start ve {name}_end.

Kısmen doldurulmuş değerler bloğun kendisinde saklanır; bu sayede önceki bir sayfaya geri dönüp tekrar ileri gitmek formu sıfırlamaz.

Durumlar

Erişilebilirlik

Metin ve sayı alanları, görünür etiketlerini alanın kendi erişilebilir düğümüyle birleştirir; böylece yer tutucu kaybolduğunda bile adlandırılmış kalırlar. Select, date, time ve toggle kendilerine ait eksiksiz bir etiket taşır ve iki kez okunmasını önlemek için görünür etiket ekran okuyucudan gizlenir. Hatalar live region olarak iletilir.

fallback_text, formu göremeyen bir kullanıcının doldurmaya değer olup olmadığını anlayabilmesi için formun ne istediğini açıklamalıdır.