AdmonitionBlock

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

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

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

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

Отображение ошибки при получении данных с сервера

В этом случае рекомендуется добавить кнопку для инициирования повторной попытки получения данных.

Отображение сообщения об отсутствии данных, которые можно показать

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

Отображение коротких инструкций по использованию сайта или приложения

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

Побуждение пользователей к конкретному действию

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

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

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

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

Сводка

Класс компонента

AdmonitionBlock

Live template компонента (официальный плагин для семейства сред разработки IntelliJ IDEA)

ab-ydf

Stylus-примесь для генерации стилей

provideAdmonitionBlockYDF_Component

Готовые темы

AdmonitionBlock.Themes.regular`

Базовая (по умолчанию)

Готовые геометрические вариации

AdmonitionBlock.GeometricVariations.regular

Базовая (по умолчанию)

AdmonitionBlock.GeometricVariations.stickyNoteLike

Похожая на клейкие листочки

Готовые декоративные вариации

AdmonitionBlock.DecorativeVariations.notice

Заметка

AdmonitionBlock.DecorativeVariations.error

Ошибка либо критически важное примечание

AdmonitionBlock.DecorativeVariations.warning

Предупреждение

AdmonitionBlock.DecorativeVariations.success

Успешное выполннение действия

AdmonitionBlock.DecorativeVariations.guidance

Объяснение

AdmonitionBlock.DecorativeVariations.question

Вопрос

Loading placeholder

Недоступен

Класс AdmonitionBlockClass

Свойства React-компонента

Примеры

Минимальный пример (только обязательные свойства)

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

<AdmonitionBlock
  decorativeVariation={ AdmonitionBlock__YDF.DecorativeVariations.notice }
>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
    labore et dolore magna aliqua.
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
    commodo consequat.
</AdmonitionBlock>

Заголовок (свойство title)

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

<AdmonitionBlock
  tile="Titulo"
  decorativeVariation={ AdmonitionBlock__YDF.DecorativeVariations.notice }
>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
    labore et dolore magna aliqua.
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
    commodo consequat.
</AdmonitionBlock>

SVG-иконки

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

<AdmonitionBlock
  decorativeVariation={ AdmonitionBlock__YDF.DecorativeVariations.notice }
  SVG_Icon={ true }
>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
    labore et dolore magna aliqua.
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
    commodo consequat.
</AdmonitionBlock>

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

<AdmonitionBlock
  tile="Titulo"
  decorativeVariation={ AdmonitionBlock__YDF.DecorativeVariations.notice }
  SVG_Icon={ true }
>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
    labore et dolore magna aliqua.
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
    commodo consequat.
</AdmonitionBlock>

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

<AdmonitionBlock
  decorativeVariation={ AdmonitionBlock.DecorativeVariations.warning }
  SVG_Icon={ SampleThirdPartyIcon }
  rootElementAttributes={ { lang: "la" } }
>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
    labore et dolore magna aliqua.
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
    commodo consequat.
</AdmonitionBlock>

import React from "react";

export const SampleThirdPartyIcon: React.FC<Readonly<{ className?: string; }>> =
    ({ className }: Readonly<{ className?: string; }>): React.ReactNode =>
        <svg
          xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"
          className={ className }
        >
          <path
            d={
              "M5,3H19A2,2 0 0,1 21,5V19A2,2 0 0,1 19,21H5A2,2 0 0,1 3,19V5A2,2 0 0,1 5,3M13," +
                "13V7H11V13H13M13,17V15H11V17H13Z"
            }
          />
        </svg>;

Как видно, пользовательская иконка меньше по размерам, чем стандартная. На самом деле, высота у них одинаковая (она задана в через стили), а проблема заключается в том, что у этой иконки между областью, называемой «view box» и фигурой, которую образует элемент path, имеется зазор. Этот зазор не имеет отношения к CSS-свойствам padding и margin, ровно как и не имеет отношения с CSS как к таковому — дело в самом SVG-изображении. Проблема в том, что у каждого поставщика SVG-иконок своя величина этого зазора, а в YDF такого зазора нет, потому что регулировать расстояние до других элементов надлежит уже с помощью CSS.

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