Тумблер

Когда использовать#

• Настройка, у которой ровно два состояния, и одно из них — «выключено»: видимость, уведомления, внешний доступ.
• Серверу нужно явное значение в обоих положениях, а не только «отмечено».

Не берите тумблер для выбора из двух равноправных вариантов («локальный» или «внешний»): там нет «выключенного», и для этого есть поле выбора. Согласие и признаки в длинной форме ставьте флажком.

В дереве холста тумблер собирается словами: имя и метка позицией, состояние и подписи — цепочкой (см. Язык узлов).

Состояния#

Метка называет настройку. ПодписьВкл и ПодписьВыкл печатаются под ней приглушённой строкой и говорят, что значит текущее положение. Подписи состояний необязательны, но с ними человеку не надо гадать, что значит «бегунок справа».

Подпись состояния печатает сервер по текущему значению. Без скрипта она не меняется до отправки формы: вид меняет только бегунок.

Подсказка — строка под тумблером о последствиях.

Источник — откуда взялось значение: «по умолчанию · ключ конфигурации». Он стоит мелко справа в строке подсказки, как у поля, и на телефоне уходит под подсказку. Справка — длинное пояснение за значком «?» рядом с тумблером: поповер открывается щелчком, тумблер ссылается на него для скринридера (aria-describedby).

Заблокированный тумблер показывает состояние и не переключается. Он не отправляется, поэтому Имя ему не нужно.

Что уходит на сервер#

Браузер не отправляет снятый флажок вовсе. Поэтому тумблер печатает пару: флажок со значением ЗначениеВкл («1») и сразу за ним скрытое поле с ЗначениеВыкл («0»). Включённый отправляет «1» и «0», и сервер берёт первое; выключенный — только «0».

<div class="toggle"><label class="toggle__box"><input type="checkbox" class="toggle__input" name="режим" value="тёмная" checked><span class="toggle__track" aria-hidden="true"><span class="toggle__thumb"></span></span><span class="toggle__text"><span class="toggle__label">Тёмная тема</span></span></label><input type="hidden" name="режим" value="светлая"></div>

Читайте тумблер на сервере сравнением со ЗначениеВкл. Проверка ЗначениеЗаполнено не годится: выключенный тумблер присылает явное «0», а строка «0» заполнена.

Тумблер — поле формы: новое состояние вступает в силу, когда форму отправят. В доме настроек сохранение берёт на себя панель сохранения.

Сохранять сразу#

Настройка, которую ждут применённой в момент щелчка, — уведомления, видимость, тема, — помечается СохранятьСразу. Переключение само отправляет форму тумблера. Если форма собрана с БезПерезагрузки(), отправка уходит в фоне: страница не перезагружается, бегунок доезжает своей анимацией, а подпись состояния обновляет ответ сервера.

<div class="toggle"><label class="toggle__box"><input type="checkbox" class="toggle__input" name="сбои" value="1" checked data-autosubmit><span class="toggle__track" aria-hidden="true"><span class="toggle__thumb"></span></span><span class="toggle__text"><span class="toggle__label">Письма о сбоях</span><span class="toggle__state">приходят</span></span></label><input type="hidden" name="сбои" value="0"></div>

Без скрипта переключение никуда не уходит, и форме нужна кнопка отправки. Если у формы тумблера своей кнопки нет, кит печатает её сам: рядом с первым тумблером СохранятьСразу — малую кнопку-значок «сохранить» (имя — словарь toggle.save), а где скрипт работает, лист её прячет — кроме формы с другим полем, как и свою кнопку. Своя кнопка формы — кнопка отправки (не ссылка, не БезОтправки), панель сохранения, шаги, панель секции-формы; с ней запасной кнопки нет и разметка прежняя. Тумблер вне формы и тумблер, напечатанный строкой (Набор.Тумблер()), кнопки не получают.

Свою кнопку можно поставить и самому — так было до 0.13.0-dev.7. Где скрипт работает, лист её прячет — в любой форме, где кроме тумблеров с СохранятьСразу полей нет: в теле секции, в карточке, в действиях записи реестра. Форма, в которой есть и другое поле, свою кнопку показывает: другое поле иначе не отправить. Отправку по изменению делает скрипт кита, поэтому её можно повесить и на другое поле узлом холста: Поле.Признак("autosubmit", "").

Гайдлайны#

HTML = Набор.Тумблер().Отрисовать(
	Новый Структура("Имя, Метка, Включено, ПодписьВкл, ПодписьВыкл",
		"видимость", "Видимость проекта", Истина, "публичный", "приватный"));

HTML = Набор.Тумблер().Отрисовать(Новый Структура("Имя, Метка, Включено",
	"видимость", "Сделать проект приватным?", Истина));

Варианты = Новый Массив();
Варианты.Добавить(Новый Структура("Значение, Подпись", "локальный", "Локальный"));
Варианты.Добавить(Новый Структура("Значение, Подпись", "внешний", "Внешний"));

HTML = Набор.Поле().Отрисовать(Новый Структура("Имя, Метка, Тип, Значение, Варианты",
	"тип", "Тип проекта", "выбор", "внешний", Варианты));

HTML = Набор.Тумблер().Отрисовать(
	Новый Структура("Имя, Метка, Включено, ПодписьВкл, ПодписьВыкл",
		"тип", "Тип проекта", Истина, "внешний", "локальный"));

Доступность#

• В основе — настоящий <input type="checkbox">. Он не скрыт через display: none, а прозрачен и лежит поверх дорожки: тумблер берёт фокус и переключается пробелом.
• Метка и подпись состояния лежат в том же <label>, что и флажок: щелчок по тексту переключает, скринридер читает название.
• Дорожка помечена aria-hidden: состояние сообщает сам флажок.
• Фокус с клавиатуры виден обводкой цветом secondary вокруг дорожки.
• Активный тумблер без Имени кит не соберёт: браузер не отправил бы его состояние.

Узлом холста#

Поля модели пишут слова: Включено, Подсказка, Заблокировано, СохранятьСразу, пары — Значения(Вкл, Выкл) и Подписи(Вкл, Выкл).

Модель#

Поля модели — из комментария в исходнике компонента. Структура с этими полями — прежний вид модели: в дереве холста те же поля пишут слова Кит.Тумблер.

Тумблер — поле выбора из двух состояний. Слова: Метка, Включено, Подсказка,
СохранятьСразу, Заблокировано, Значения(Вкл, Выкл), Подписи(Вкл, Выкл).

Параметры:
 Модель - Строка, Структура - имя поля; Структура — прежний вид модели.
 Метка  - Строка - (необязательный) подпись тумблера.

Возвращаемое значение:
 ЭлементЭкрана

Отрисовывает тумблер как фрагмент <div class="toggle">.

Параметры:
 Модель - Структура - Имя (атрибут name, обязательно, кроме заблокированного),
          Метка, Включено, ЗначениеВкл ("1"), ЗначениеВыкл ("0"), ПодписьВкл,
          ПодписьВыкл, Подсказка, Заблокировано (только показ, скрытого поля нет),
          СохранятьСразу (переключение само отправляет форму тумблера: у формы
          БезПерезагрузки() — в фоне, без перезагрузки страницы. Без скрипта форму
          отправляет кнопка: своя у формы или запасная, см. ЗапаснаяКнопка).
          Источник — откуда взялось значение («по умолчанию · mail.enabled»): мелкая
          надпись справа в строке подсказки, как у поля. Справка — длинное пояснение:
          значок «?» рядом с тумблером открывает поповер, тумблер ссылается на него
          aria-describedby. Без Источника и Справки разметка прежняя.
          ЗапаснаяКнопка (0.13, дев-сборка 7; ставит холст у тумблера СохранятьСразу в форме
          без своей кнопки отправки): рядом с тумблером — малая кнопка-значок «сохранить»
          (имя — словарь toggle.save), которой форма уходит без скрипта; при работающем
          скрипте лист её прячет. Тумблер и кнопка — в обёртке .toggle-save.

Возвращаемое значение:
 Строка - HTML-фрагмент. Кидается исключением, если у активного тумблера нет Имени.