Yamato DaiwaFrontend (2.0.0-beta.4)
English
日本語
Русский

AdmonitionBlock

Рамки с текстом использовались ещё задолго до компьютеризации — в книгах и другой печатной продукции. Хотя чаще всего рамкой выделяют важный текст, иногда рамкой обрамляются заметки, примечания и прочая второстепенная информация.

В разработке сайтов и приложений, выделение блока текста в рамку стало более продвинутым и частым.

  • Как и в печатной продукции, рамка используется на сайтах с большим количеством текста для выделения его фрагментов. Чтобы посетитель мог мгновенно оценить важность выделяемого текста, используется цветовая кодировка: для важных блоков обычно выбирают тёплые цвета (красный, оранжевый, жёлтый), в остальных случаях — холодные (синий, голубой, зелёный) или ахроматические (чёрная или серая рамка с белым или светло-серым фоном). Кроме того, иногда используются иконки.
  • В графических пользовательских интерфейсах (GUI) рамка с текстом приобрела дополнительную функцию, став одним из способов оповещения пользователя. В отличие от всплывающих сообщений, отображающихся короткий промежуток времени, рамка с текстом обычно отображается постоянно или до тех пор, пока пока пользователь не уберёт её с помощью соответствующей кнопки (если таковая имеется). Рекомендуется также предложить пользователю отреагировать на сообщение, добавив внутрь рамки дополнительные кнопки.

Использовать рамку с текстом для оповещения пользователя рекомендуется в следующих случаях:

Отображение ошибки при получении данных с сервера
В этом случае рекомендуется добавить кнопку для инициирования повторной попытки получения данных.
Отображение сообщения об отсутствии данных, которые можно показать
Следует подготовить отдельные сообщения для случаев, когда нет данных, удовлетворяющих поисковому запросу, и для случая, когда данных нет вообще. Предложить пользователю отреагировать на сообщение тоже следует по-разному: в первом случае — подготовить копку для сброса поискового запроса, а во втором — предложить добавить данные, если пользователю это позволено авторизованному на данный момент пользователю.
Отображение коротких инструкций по использованию сайта или приложения
Это очень важно делать для не только для новых пользователей конкретно Вашего сайта или приложения, но и для пользователей с низким уровнем компьютерной грамотности, которых ещё очень много.
Побуждение пользователей к конкретному действию
Например, если на Вашем сайте или приложении регистрация опциональная, то можно предложить пользователю зарегистрироваться и объяснить, какие преимущества это даст. Разумеется, в данном случае должны быть ссылки на страницу регистрации и авторизации (для уже загеристрированных пользователей).

Напротив, в следующих случах рамка с текстом не является лучших выбором:

  • Отображение ошибки при отправке данных
  • Отображение сообщения об успешной отправке данных
  • Отображение сообщения об успешном входе в систему или выходе из неё

Для этих сценариев гораздо лучше подходят всплывающие сообщения (в YDF это компонент Snackbar).

Сводка

Pug-примесь
AdmonitionBlock--YDF
Live template Pug-примеси (официальный плагин для семейства сред разработки IntelliJ IDEA)
ab-ydf
Stylus-примесь для генерации стилей
provideAdmonitionBlockYDF_Component
Готовые темы
AdmonitionBlock__YDF.Themes.regular`
Базовая (по умолчанию)
Готовые геометрические вариации
AdmonitionBlock__YDF.GeometricVariations.regular
Базовая (по умолчанию)
AdmonitionBlock__YDF.GeometricVariations.stickyNoteLike
Похожая на клейкие листочки
Готовые декоративные вариации
AdmonitionBlock__YDF.DecorativeVariations.notice
Заметка
AdmonitionBlock__YDF.DecorativeVariations.error
Ошибка либо критически важное примечание
AdmonitionBlock__YDF.DecorativeVariations.warning
Предупреждение
AdmonitionBlock__YDF.DecorativeVariations.success
Успешное выполннение действия
AdmonitionBlock__YDF.DecorativeVariations.guidance
Объяснение
AdmonitionBlock__YDF.DecorativeVariations.question
Вопрос
Loading placeholder
Недоступен

Использование

Разметка

Подключение в проект

Разметка данного компонента поставляется в виде Pug-примеси AdmonitionBlock--YDF. Способ подключения — стандартный: путём включения Pug-файла Components.pug в Ваш pug-файл, при этом туда же предварительно должен быть включён файл Functionality.pug (последний уже входит в шаблоны страниц , повторное включение приведёт к ошибке).

Pug-примесь AdmonitionBlock--YDF

AdmonitionBlock--YDF
(
Параметр №1
Обязательный
Общее техническое наименование
properties
Русскоязычное имя
Свойства
Тип
Properties
):void
Properties
Свойства
{
title
Русскоязычное наименование
Заголовок
Обязательное
Нет
Тип
string
Минимум символов
1
SVG_Icon
Русскоязычное наименование
SVG-иконка
Варианты
  • Тип
    boolean
  • Тип
    object
    Структура объекта
    object
    {
    innerElementID
    Обязательное
    Да
    Тип
    string
    Минимум символов
    1
    SVG_ElementAttributes
    Значение по умолчанию
    {}
    Тип
    Объект типа «ассоциативный массив»
    Значения ассоциативного массива
    Тип
    string
    Минимум символов
    1
    }
Обязательное
Нет
dismissible
Русскоязычное наименование
Возможно ли убрать
Значение по умолчанию
false
Тип
boolean
theme
Русскоязычное наименование
Тема
Значение по умолчанию
AdmonitionBlock__YDF.Themes.regular
Тип
string
Допустимые варианты
  • AdmonitionBlock__YDF.Themes.regular
  • (Любые, определённые через AdmonitionBlock__YDF.defineThemes(themesNames))
areThemesCSS_ClassesCommon
Русскоязычное наименование
Являются ли CSS-классы тем общими для всех компонентов
Значение по умолчанию
AdmonitionBlock__YDF.areThemesCSS_ClassesCommon
Тип
boolean
geometricVariation
Русскоязычное наименование
Геометрическая вариация
Значение по умолчанию
AdmonitionBlock__YDF.GeometricVariations.regular
Тип
string
Допустимые варианты
  • AdmonitionBlock__YDF.GeometricVariations.regular
  • AdmonitionBlock__YDF.GeometricVariations.stickyNoteLike
  • (Любые, определённые через AdmonitionBlock__YDF.defineGeometricVariations(geometricVariationsNames))
decorativeVariation
Русскоязычное наименование
Декоративная вариация
Обязательное
Да
Тип
string
Допустимые варианты
  • AdmonitionBlock__YDF.DecorativeVariations.notice
  • AdmonitionBlock__YDF.DecorativeVariations.error
  • AdmonitionBlock__YDF.DecorativeVariations.warning
  • AdmonitionBlock__YDF.DecorativeVariations.success
  • AdmonitionBlock__YDF.DecorativeVariations.guidance
  • AdmonitionBlock__YDF.DecorativeVariations.question
  • (Любые, определённые через AdmonitionBlock__YDF.defineDecorativeVariations(decorativeVariationsNames))
}
Минимальный пример (только обязательные свойства)

В простейшем случае, из свойств необходимо указать только декоративную вариацию, поскольку декоративной вариации по умолчанию нет. С помощью декоративной вариации кодируется важность сообщения.Текст сообщения либо его HTML-код указывается через блок Pug-примеси:

Заголовок (свойство title)
Русскоязычное наименование
Заголовок
Обязательное
Нет
Тип
string
Минимум символов
1

Сообщение в рамке будет с большей вероятностью прочитано и осмыслено, если снабдить его кратким и чётким заголовком. В условиях острого дефицита времени, характерного для современного образа жизни, люди часто не читают страницу полностью, а пробегают глазами по заголовкам, и если какой-то из них для конкретного человека чем-то важен, то только тогда он начнёт читать связанный с этим заголовком текст. Хотя добавленный заголовок не будет использовать тэги HTML-заголовков (h1-h6), он будет семантически связан с содержимым блока Pug-примеси.

SVG-иконка (свойство SVG_Icon)
Русскоязычное наименование
SVG-иконка
Варианты
  • Тип
    boolean
  • Тип
    object
    Структура объекта
    object
    {
    innerElementID
    Обязательное
    Да
    Тип
    string
    Минимум символов
    1
    SVG_ElementAttributes
    Значение по умолчанию
    {}
    Тип
    Объект типа «ассоциативный массив»
    Значения ассоциативного массива
    Тип
    string
    Минимум символов
    1
    }
Обязательное
Нет

Иконка вдобавок к цвету фона позволяет лучше передать важность сообщения. Для того, чтобы отобразилась иконка по умолчанию (зависит от декоративной вариации), необходимо указать свойству SVG_Icon значение true:

Наиболее рекомендуемым вариантом является сочетание заголовков и иконок:

Пользовательские иконки

К сожалению ввиду того, что Pug не поддерживает слоты (как, например, слоты во феймворке Vue), а Pug-примесь не является функцией, возвращающей строчное значение с HTML-кодом, возможность указать пользовательскую SVG-иконку вместо стандартной ограничена. Решение основывается на использовании svg-элемента use, который позволяет сослаться на другой элемент, находящийся на той же HTML-странице, но при этом он не обязательно должен быть видимым. Когда иконка добавлена на страницу, укажите свойству SVG_Icon значение на сей раз объектного типа со следующими свойствами:

innerElementID
Идентификатор дочернего элемента по отношению к элементу svg целевой иконки. Если элемент svg имеет несколько дочерних элементов, то их необходимо объединить в группу (элемент g), и тогда идентификатор должен быть у этой группы.
SVG_ElementAttributes
Внутренний объект типа «ассоциативный массив», через который следует передать аттрибуты тэга svg, необходимые для нормального отображения целевой иконки. Обычно используется аттрибут viewBox, но возможны и любые другие валидные аттрибуты тэга svg, при этом имена аттрибутов должны быть такими же, как и в обычном HTML-коде или Pug-коде (например, viewBox записывается в верблюжьем регистре, а color-interpolation — в шашлычной нотации, при этом в последнем случае ключ необходимо обернуть в кавычки).
Кнопки

Многие сообщения могут вызвать ступор у пользователей с низкой компьютерной грамотностью, а таковых всё ещё немало. Чтобы повысить комфорт таких пользователей, следует предложить им как-либо отреагировать на сообщение, при этом подготовить кнопку для соответствующего действия. Например:

  • В случае сообщения об ошибке при получении данных можно подготовить кнопку, которая запустит процесс повторного получения данных. Если ошибка произошла из-за нестабильного интернет соединения, то при его восстановлении повторная попытка получения данных может завершиться успешно.
  • В случае сообщения о том, что данных пока нет, можно предложить пользователю эти данные добавить, если у него есть на это право. Если для добавления данных существует отдельная страница, то кнопка в данном случае будет ссылкой, ведущей на эту страницу.
  • Если же вообще данные есть, но нет данных, соответствующей конкретному фильтру, то соответствующему сообщению можно добавить кнопку сброса фильтров.

Если кнопка или ссылка одна, и Вы хотите расположить её по центру, то укажите ей CSS-класс AdmonitionBlock--YDF-CenteredButton:

Если пользователю предлагается несколько способов отреагировать на сообщение, то оберните Ваши кнопки в блочный элемент с CSS-классом AdmonitionBlock--YDF-ActionBar:

Убирание

Для того, чтобы дать возможность пользователю убрать рамку с текстом (без сторонней логики), необходимо выполнить следующие действия:

  1. При использовании Pug-примеси AdmonitionBlock--YDF указать свойству dismissible единственного параметра значение true. Это отобразит кнопку убирания, однако на этом этапе она пока работать не будет.
  2. Подключить в Ваш TypeScript-код класс AdmonitionBlock и воспользоваться одним из его методов. Все они добавляют прослушивания события нажатия на кнопку убирания. Например, чтобы что активировать все рамки с текстом, отображающиеся на странице на данный момент, вызовите статический метод initializeAll:

© 2023 Yamato Daiwa Co., Ltd.