Списки й поля для кожної мови
Для розробників, у коді: повторювані рядки, що адресуються за позицією, порожній список, який називає свої поля, і перемикачі, які вирішують, яка версія поля показана.
Дві форми ламають плоске сканування елементів: повторюваний список (п’ять FAQ-чіпів — це
п’ятнадцять елементів, кожен — шанс написати в сусідній рядок) і перемикач варіантів (одне
поле з англійською, українською й польською версіями, з яких видно лише одну). Вісім атрибутів
описують обидві, і назви — ваші: ніщо у віджеті не знає, що означає faq чи lang.
Повторюваний список
<div data-sa-list="faq" data-sa-fields="enabled,question:lang,delete">
<div data-sa-row>
<input type="checkbox" data-sa-field="enabled" aria-label="Показувати чіп" />
<input data-sa-field="question" data-sa-variant-of="lang" aria-label="Питання" />
<button data-sa-field="delete">Видалити</button>
</div>
…
</div>
<button data-sa-add="faq">Додати чіп</button>| Атрибут | На чому | Сенс |
|---|---|---|
data-sa-list="faq" |
контейнер | Список стає одним записом маніфесту й адресується як faq[2].question — рядки лічаться в порядку документа від 1. |
data-sa-row |
кожен рядок | Один повторюваний рядок. |
data-sa-field="question" |
елемент усередині рядка | Назва поля в рядку. Називає і власні кнопки рядка; delete зберігає свою згоду. Проходить усередину хоста компонента. |
data-sa-add="faq" |
кнопка, що додає рядок | Оголошує натискання нешкідливим: віджет натискає її сам, стільки разів, скільки потрібно для запитаного номера рядка, тож помічник ніколи не вгадує ідентичність нового рядка. Ніколи на «Зберегти», «Надіслати» чи «Видалити». |
data-sa-fields="enabled,question:lang,delete" |
контейнер | Що містить рядок, для порожнього списку — без рядка на екрані нема звідки прочитати назви полів. Поле з перемикачем називає свою вісь (question:lang), інакше перший запис у нього відхиляється через відсутність ключів. |
Помічник бачить один рядок: [list faq] "FAQ chips" — 2 row(s) · fields: enabled (checkbox), question (input, lang: en/uk, showing en), delete (button) · add: "Додати чіп". Індекс рядка на
один більший за наявні і є створенням: віджет натискає кнопку додавання стільки разів,
скільки бракує, чекає, поки сторінка перемалюється, перелічує заново і провалює крок, якщо рядок
не з’явився. Створені рядки повідомляються за позицією, ніколи за ідентифікаторами всередині. За
один виклик створюється щонайбільше 20 рядків; faq[999] коштує один відхилений крок, а не 999
натискань.
Позначений список замінює символічну адресу $new, якою помічник користується на нерозмічених
екранах, для цього списку: кожен елемент усередині позначеного рядка зникає з плоского маніфесту.
Підказка (data-sa-hint) усередині рядка відкидається — ставте її на елементи самого списку поза
рядками.
Перемикач варіантів
<div role="group" aria-label="Мова" data-sa-variants="lang">
<button aria-pressed="true" data-sa-variant="en">English</button>
<button aria-pressed="false" data-sa-variant="uk">Українська</button>
</div>
<input data-sa-variant-of="lang" aria-label="Привітання" />| Атрибут | На чому | Сенс |
|---|---|---|
data-sa-variants="lang" |
перемикач | Перемикач, який вирішує, яка версія поля показана; назва осі — ваша (мови, валюти, розміри, тарифи). |
data-sa-variant="uk" |
кожен варіант | Ключ цієї версії. Не може бути порожнім. |
data-sa-variant-of="lang" |
поле | Це поле містить версію для кожного ключа цієї осі. |
data-sa-variant-options="en=English,uk=Українська" |
випадний перемикач | Його варіанти існують лише поки він відкритий, а сканування не має його відкривати. Оголосіть пари ключ=підпис; віджет тоді працює з ним як із будь-яким комбобоксом — відкрити, знайти підпис, клікнути. |
Помічник надсилає одне значення на ключ — {"en": "…", "uk": "…"} — а віджет сам керує
перемикачем: перемикає на кожну версію, включно з тією, що вже показана, пише і перечитує.
Простий рядок у поле з віссю відхиляється з переліком ключів: яка версія показана — це стан
екрана, і писати в неї правильно лише випадково. Керівний перемикач — той, що всередині
найближчого спільного предка поля, тож два перемикачі однієї осі на одному екрані не
плутаються.
Оголошення перемикача також каже помічнику, що його натискання нічого не зберігає —
показано іншу версію, жодне значення не змінилося, — і саме це не дає кліку на мову
повідомлятися як незбережена правка чи запускати автозбереження. Перемикач, що не керує жодним
полем на ім’я, оголошує порожню вісь: data-sa-variants="" з ключем на кожному варіанті.
Неоголошений перемикач навмисно все одно вважається зміною. Ціна — зайва примітка про збереження; навпаки було б гірше: правка, повідомлена як збережена і тихо втрачена.
Без розмітки: $new
На нерозміченому екрані помічник усе одно може будувати список: натискає «Додати» і адресує
створені цим натисканням елементи як $new, $new.2, $new.3 у порядку документа — віджет
розв’язує їх за тим, що натискання справді додали на сторінку, тож $new, за яким нічого немає,
провалює крок, а не пише деінде. Це працює — і це джерело більшості помилок, які атрибути списків
існують, щоб прибрати; позначте список раз, і вгадування припиниться.
Що каже підтвердження
Пакет, що створив рядки, повідомляє їх за позицією (faq: rows 3–4 created), запис варіантів
повідомляє кожну версію (uk: written, pl: replaced), а відхилений запис називає причину:
needs_variants (простий рядок у поле з віссю — далі ключі), variants_unknown (випадний
перемикач без оголошених варіантів), no_such_variant, switch_failed (варіант недоступний або
не перемкнувся), no_new_row (кнопка додавання нічого не додала), too_many_rows.