Плашка

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

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

Не берите плашку для действия — для этого есть кнопка. Для фразы о результате действия подойдёт тост. Признак, который принадлежит самому имени объекта (подписан, закреплён), ставят значком у имени в шапке объекта.

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

Виды#

Нейтральная плашка — признак без оценки. Её заливка — surface-container-highest, текст — приглушённый.

Статусные виды берут тональные контейнеры Material: заливка — контейнер роли, текст — цвет «на контейнере». Цвет узнаётся издалека, а текст на нём остаётся читаемым в обеих темах.

Вид можно назвать и по-русски: «успех», «предупреждение», «ошибка», «акцент». Неизвестный вид даёт нейтральную плашку: в CSS-класс попадает только значение из списка.

Ссылка и подсказка#

С Адресом плашка становится ссылкой: на наведении её заливку накрывает слой состояния. Так плашка «внешний» ведёт к списку всех внешних объектов.

Подсказка печатается атрибутом title — всплывающей подсказкой мыши. Она поясняет, но не заменяет текст плашки.

Крестик снятия#

Действие — разметка управления, которая печатается ВНУТРИ плашки. Поэтому перенос строки не отрывает крестик от подписи. Крестик — обычная кнопка-значок с подписью.

Действие вместе с Адресом кит не соберёт: кнопка внутри ссылки не нажимается, и компонент бросает исключение.

Крестик тихой формой#

Чаще всего крестик что-то снимает на сервере: исключение из рассылки, отбор, метку. Слово Снять(Адрес, Поле, Значение) (дев-сборка 8) печатает плашку внутри её маленькой тихой формы: форма уходит POST на Адрес без перезагрузки, скрытым полем Поле=Значение, а крестик — кнопка её отправки. Токен форма берёт у предков, как любая форма холста (слово Токен, дом настроек); адрес — как у слова Форма: относительный дописывается к адресу контекста. Полей несколько — вторым аргументом структура. Имя крестика для скринридера — четвёртым аргументом, по умолчанию «Снять «текст плашки»» (ключ словаря tag.remove).

Ряд таких плашек раскладывает Кит.РядПлашек: формы встают в него, как сами плашки, и переносятся вместе. Без скрипта крестик отправляет форму обычной навигацией.

Снять вместе с Адресом или Действием кит не соберёт, а форму без токена не напечатает: она выглядела бы рабочей, а получила бы 403.

Ряд плашек#

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

Неопределено вместо модели — признака нет, и плашка не печатается. Это правило живёт в компоненте, поэтому в ряд можно класть признаки как есть, без проверок.

Гайдлайны#

HTML = Набор.Тег().Отрисовать(Новый Структура("Текст, Вид", "устаревший", "warn"));

HTML = Набор.Тег().Отрисовать(Новый Структура("Текст, Вид",
	"Эта редакция устарела, обновитесь до 1.1.0 как можно скорее", "warn"));

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

HTML = Набор.Тег().Ряд(Плашки);

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

HTML = Набор.Тег().Ряд(Плашки);

Крестик = Набор.Кнопка().Отрисовать(
	Новый Структура("Подпись, Вариант, Размер, Иконка, ТолькоИконка",
		"Снять отбор «внешний»", "ссылка", "малый", "закрыть", Истина));

HTML = Набор.Тег().Отрисовать(Новый Структура("Текст, Действие", "внешний", Крестик));

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

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

• Смысл плашки несёт её текст, а цвет только повторяет его. Плашку без слов не ставьте: скринридер прочтёт пустоту. Нет признака — передайте Неопределено, и плашки не будет.
• Подпись крестика уходит в aria-label. Называйте в ней, что снимается: «Снять отбор «внешний»», а не «Закрыть». У крестика тихой формой подпись по умолчанию так и названа — «Снять «текст плашки»».
• Подсказка в title не видна с клавиатуры и на телефоне. Не кладите туда то, без чего плашку не понять.
• Плашка-ссылка — обычная ссылка с текстом: её находит обход по Tab и список ссылок скринридера.

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

На холсте плашка и ряд плашек — узлы. Их кладут в ячейку таблицы, в ряд шапки, в сводку.

Дети узла-плашки печатаются ВМЕСТО значка и текста модели. Так плашку собирают из своих узлов — например, с кодом версии внутри: строка среди детей становится текстом.

Модель#

В наборе компонентов плашка зовётся Набор.Тег(), а класс компонента — Плашка: имя Тег в OneScript занято. Структура с этими полями — прежний вид модели: в дереве холста Вид, Адрес, Иконка и Подсказка пишут слова Кит.Плашка. Слова для Действия нет — крестик снятия собирают компонентом строкой, а крестик, который снимает на сервере, — словом Снять (поле модели Снять).

Отрисовывает плашку.

Параметры:
 Модель - Структура, Строка, Неопределено - текст плашки либо структура: Текст
          (экранируется), Вид ("" | "ok" | "warn" | "err" | "accent"), Адрес (плашка
          становится ссылкой), Иконка, Подсказка (атрибут title), Действие —
          ДОВЕРЕННЫЙ HTML управления при плашке (крестик снятия): печатается ВНУТРИ
          неё, поэтому перенос строки не отрывает его от подписи. С Адресом
          несовместимо. Неопределено — признака нет, плашка не печатается. Внутри —
          ДОВЕРЕННЫЙ HTML содержимого: печатается ВМЕСТО значка и текста, когда плашку
          собирают из своих узлов. Снять (дев-сборка 8) — Структура: Действие (адрес
          формы), Скрытые (ДОВЕРЕННЫЙ HTML скрытых полей формы, токен среди них), Подпись
          (имя крестика; по умолчанию словарь tag.remove с текстом плашки): плашка
          печатается внутри своей маленькой тихой формы (form.tag-form, data-quiet), а
          крестик — кнопкой её отправки. На холсте её собирает слово Снять.

Возвращаемое значение:
 Строка - HTML-фрагмент; "" для Неопределено. Кидается исключением, если Действие
          задано вместе с Адресом или Снять — вместе с Адресом или Действием.

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

Параметры:
 Список - Массив - модели плашек (см. Отрисовать); Неопределено в списке пропускается.

Возвращаемое значение:
 Строка - фрагмент div.tag-row либо пустая строка для пустого ряда. Имя класса без
          кавычек намеренно: закавыченное сканер мёртвых правил CSS зачтёт за разметку.

Плашка — короткий признак: состояние, тип, источник. Содержимое можно собрать узлами:
они печатаются ВМЕСТО значка и текста модели. Слова: Вид, Адрес, Иконка, Подсказка.

Параметры:
 Модель - Строка, ЭлементЭкрана, Структура, Неопределено - текст плашки либо первый
          узел её содержимого; Структура — прежний вид модели; Неопределено — плашки
          нет, узел печатается пустой строкой.
 Р2…Р8  - ЭлементЭкрана, Строка - (необязательные) ещё узлы содержимого.

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

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

Параметры:
 Список - Массив, ЭлементЭкрана - модели компонента «Плашка», узлы плашек (можно вперемешку)
          либо первая плашка-узел.
 Р2…Р8  - ЭлементЭкрана - (необязательные) следующие плашки-узлы.

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

Крестик плашки — снятие её тихой формой: плашка печатается внутри своей маленькой формы,
которая уходит POST на Адрес без перезагрузки, а крестик — кнопка её отправки. Токен форма
берёт у предков, как любая форма холста (слово Токен, дом настроек); адрес — как у слова
Форма: относительный дописывается к адресу контекста. Ряд таких плашек раскладывает
Кит.РядПлашек.

Параметры:
 Адрес_ - Строка - куда уходит форма.
 Поле - Строка, Структура, Соответствие - имя скрытого поля формы либо все её поля.
 Значение_ - Строка - (необязательный) значение поля.
 Подпись_ - Строка - (необязательный) имя крестика для скринридера; по умолчанию словарь
            tag.remove с текстом плашки.

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