5.11.1. Коллекции изображений

Changed in version 1.23.0-ms15: Добавлена возможность использования SVG-коллекций.

5.11.1.1. Общая информация

Сервер предоставляет API для работы с коллекциями изображений.

Получение коллекций изображений осуществляется через EngineEndpoint.

Виды коллекций изображений:

  • Коллекции векторных изображений (формируются на основании .svg файлов).

  • Коллекции растровых изображений (формируются на основании .png файлов).

  • Совмещенная коллекция векторных изображений (формируется при наличии подкаталога svg и на основании набора .svg файлов из этого подкаталога с дополнением .png файлами растровой коллекции из корневого каталога коллекции, преобразованными в SVG формат).

Способы хранения коллекций изображений:

  • В локальных файлах сервера. Путь к коллекциям изображений: ${G3_HOME}/server/resources/imagecollection/.

    Warning

    В файловой системе каталоги с коллекциями изображений необходимо именовать в нижнем регистре.

  • В таблице BTK_COMPONENT внутри БД.

    Warning

    БД поддерживает только растровые коллекции изображений

Note

Как реализовано получение коллекций из прикладного проекта:

  1. Из прикладного проекта отправляется запрос на сервер для получения коллекции по указанному имени (например: toolbarprimary).

  2. Сервер обрабатывает запрос в зависимости от того, была ли данная коллекция запрошена ранее

    2.1. Если коллекция запрашивается впервые:

    1. Сервер извлекает изображения из указанной коллекции (из локальной папки, если коллекция хранится в локальных файлах сервера, или из таблицы BTK_COMPONENT, если коллекция хранится в БД).

    2. Для локальных файлов на сервере: если в папке коллекции есть подкаталог svg с .svg файлами, то векторные изображения сначала берутся из этого подкаталога и далее дополняются, преобразованными из .png в .svg, изображениями из корневой папки коллекции. Дополнение осуществляется изображениями с уникальными номерными именами, заполняя пропуски в нумерации.

    3. Из этих изображений сервер формирует единый файл — спрайт изображений, который преобразуется в массив битов.

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

    5. Спрайт изображений отправляется на прикладной проект.

    2.2. Если коллекция уже запрашивалась ранее:

    1. Сервер получает спрайт изображений для запрашиваемой коллекции из кэша коллекций

    2. Спрайт изображений отправляется на прикладной проект.

    2.3. Если запрошенная коллекция не найдена сервер возвращает коллекцию not_found.

    2.4. Если коллекция состоит из изображений, имена которых не представляют положительные целые числа:

    1. Для растровых изображений отправляется байтовый массив с нулевой длиной.

    2. Для векторных изображений отправляется пустая коллекция.

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

See also

5.11.1.2. Правила

  • Изображения в коллекции изображений необходимо называть по соответствующим им порядковому номеру, последовательно и без пропусков. Например: 0.png, 1.png, 2.png.

  • Нумерация изображений в коллекции изображений начинается с 0, в других номерах лидирующие нули недопустимы (например: 00, 01, 004).

  • Изображения внутри одной коллекции изображений должны иметь одинаковые высоту и ширину.

  • Если для одной коллекции изображений имеются файлы с разным размером изображений, то необходимо разделить коллекцию на отдельные коллекции изображений с указанием соответствующего размера изображений. Пример: btk_license16 и btk_license24, btk_scheduler16 и btk_scheduler24.

  • Изображения должны быть квадратными. Например, 16x16 пикселей.

  • Поддерживаемые размеры изображений 16px и 24px.

  • Изображения в корневом каталоге коллекции изображений должны иметь одинаковое расширение. Например: только .png файлы.

  • Изображения в подкаталоге svg совмещенной коллекции изображений должны иметь расширение только .svg.

  • Если в коллекции имеются файлы с разными расширениями, то будет выбрано только одно расширение в соответствии с установленным приоритетом. Файлы с другими расширениями не будут добавлены в спрайт.

    Attention

    Приоритет расширений файлов (от наиболее приоритетных к менее приоритетным):

    • .svg

    • .png

  • После добавления/удаления изображения из коллекции, которая уже запрашивались ранее в рамках работающего сервера, необходимо перезапустить сервер, чтобы применились изменения

5.11.1.2.1. Коллекции векторных изображений

  • Указание свойств высоты (height) и ширины (width) в атрибутах изображения для .svg файла является обязательным, иначе в дальнейшем изображение не будет использоваться.

Пример указания свойств высоты и ширины в .svg файле
<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M8 4.95117C6.99219 4.95117 6.37109 6.04102 6.37109 7.8457V8.15625C6.37109 9.9668 6.99805 11.0508 8 11.0508C9.00195 11.0508 9.62305 9.96094 9.62305 8.15625V7.8457C9.62305 6.04688 9.00195 4.95117 8 4.95117Z" fill="black"/>
    <path d="M16 8C16 12.4183 12.4183 16 8 16C3.58172 16 0 12.4183 0 8C0 3.58172 3.58172 0 8 0C12.4183 0 16 3.58172 16 8ZM7.98828 12.1582C9.8457 12.1582 10.9473 10.5762 10.9473 8.16797V7.83984C10.9473 5.41406 9.86914 3.84375 8.01172 3.84375C6.14844 3.84375 5.04688 5.43164 5.04688 7.83984V8.16797C5.04688 10.5879 6.13672 12.1582 7.98828 12.1582Z" fill="black"/>
</svg>

5.11.1.3. Рекомендации

  • Рекомендуется называть коллекцию изображений в зависимости от её тематики или от места её использования (например, toolbarprimary и toolbarsecondary — это коллекции, используемые в панели инструментов).