Icon

Icon — системный модуль, хранящий каталог иконок интерфейса (Font Awesome и Bootstrap Icons) и подбирающий лучшую иконку под текстовый запрос через полнотекстовый поиск. Подключается через REQUIRE Icon (который, в свою очередь, делает REQUIRE Utils, Reflection, SystemEvents).

Свойства поиска и ранжирования опираются на примитивы toTsVector / toTsQuery / tsRank из модуля Utils (см. его раздел «Полнотекстовый поиск»).

Каталог иконок

Каждая иконка — объект класса Icon. Поля каталога:

Свойство	Что хранит
name[Icon]	имя иконки (голое имя, используемое в CSS-классе, например user, home)
explicit[Icon]	дополнительные слова для поиска, собранные из ресурсов *Icons.properties (текст совпадения с наибольшим весом)
label[Icon]	человекочитаемая подпись
terms[Icon]	поисковые термины через пробел
synonyms[Icon]	синонимы через пробел
styles[Icon]	доступные стилевые классы иконки (набор free-стилей Font Awesome или bi для Bootstrap Icons)
type[Icon]	семейство иконки, выводится из styles[Icon]: 'bi', если стиль bi, иначе 'fa'

Icon.null — предопределённый объект «без иконки» (выбирается, когда иконку показывать не нужно); его name[Icon] и explicit[Icon] при старте устанавливаются в 'null'.

Иконка ищется по имени и семейству через icon[name, type] — агрегацию по паре (name[Icon], type[Icon]), проиндексированную для прямого поиска.

iconClass[Icon, STRING] строит строку CSS-класса для иконки в запрошенном стиле:

Семейство (type[Icon])	Результирующий класс
'bi'	'bi bi-' + name(i)
'fa', стиль brands	'fa-brands fa-' + name(i)
'fa', прочие стили	'fa-' + style + ' fa-' + name(i), если иконка предлагает запрошенный style, иначе 'fa fa-' + name(i)

Полнотекстовый поиск и ранжирование

Для каждой иконки модуль материализует по одному ts-вектору на поле каталога — searchExplicit[Icon], searchLabel[Icon], searchTerms[Icon], searchSynonyms[Icon] — и один объединённый ts-вектор search[Icon] по конкатенации explicit / label / terms / synonyms, используемый как MATCH-индекс для отбора кандидатов. searchStyles[Icon] материализует слово стиля иконки по умолчанию ('regular' для Bootstrap Icons, пусто для стиля brands, иначе styles иконки) — для штрафа за несовпадение стиля.

Строка запроса превращается в TSQUERY через nameToIconQuery[STRING]: он разбивает CamelCase, дефисы и пробелы на отдельные слова, приводит их к нижнему регистру и соединяет оператором OR, чтобы совпадение по любому слову считалось. lengthIconQuery[TSQUERY] даёт число слов в таком запросе ((numNode(query) + 1) / 2).

tsRank[Icon, TSQUERY, STRING] — итоговая оценка релевантности иконки для запроса и запрошенного стиля. Это взвешенная сумма пофайловых оценок, масштабированная числом слов запроса, со штрафом за несовпадение стиля:

Поле	Вес	Модель ранжирования
explicit	12	tsRank (лишние explicit-слова не понижают оценку)
label	8	tsRankLN с базой нормализации 4 (короткие подписи получают более высокую оценку)
terms	6	tsRank (лишние термины не понижают оценку)
synonyms	4	tsRankLN с базой нормализации 16 (длинный список синонимов гасится, чтобы избежать ложных срабатываний)

Взвешенная сумма умножается на lengthIconQuery[TSQUERY], поэтому совпадение по большему числу слов запроса повышает, а не размывает оценку. Наконец, если иконка не предлагает запрошенный стиль (searchStyles[Icon] не содержит стиль), оценка уменьшается на 0.25.

Пофайловые помощники explicitRank[Icon, TSQUERY], labelRank[Icon, TSQUERY], termsRank[Icon, TSQUERY], synonymsRank[Icon, TSQUERY] показывают вклад каждого поля (та же модель и вес, масштабированные числом слов запроса) для разбора.

Поиск лучшей иконки

Поиск лучшей иконки читает одну или несколько строк запроса и пишет для каждой CSS-класс выбранной иконки и её оценку:

Свойство	Направление	Что хранит
bestIconNames[STRING]	вход	признак строки запроса для обработки; строка имеет вид query,style
bestIconClasses[STRING]	выход	iconClass лучшей подходящей иконки для строки
bestIconRanks[STRING]	выход	оценка tsRank этой иконки

getBestIcons[] обрабатывает каждую помеченную строку. Часть до запятой берётся как текст запроса, часть после — как стиль; строится TSQUERY по запросу, и среди иконок, чей search[Icon] совпадает с ним, выбирается иконка с наибольшим tsRank[Icon, TSQUERY, STRING]; затем её класс и оценка пишутся в bestIconClasses[STRING] и bestIconRanks[STRING].

Форма icons запускает это из интерфейса: searchAndStyle[] склеивает введённый текст поиска и стиль как search() + ',' + style(), и при любом изменении любого из них помечает эту склеенную строку и вызывает getBestIcons[].

Импорт иконок

importIcons[] загружает каталог и держит объекты Icon в синхронизации с ним:

• Читает /web/icons_with_synonyms.json и, под защитой importIconsHash[] (MD5 ресурса), повторно импортирует только при изменении файла. При изменении создаёт новый Icon для каждой пары (name, type), которой ещё нет, обновляет label / terms / synonyms / styles из файла (в нижнем регистре), удаляет иконки, которых в нём больше нет (сохраняя Icon.null), и сохраняет новый хеш.
• Затем читает каждый ресурс *Icons.properties и наполняет explicit[Icon] для каждой иконки из подходящих ключей свойств, разбитых на отдельные слова.

Свойства отображения

Эти свойства строят небольшие фрагменты HTML для композиции картинки (или бейджа) с текстом:

Свойство	Что строит
badge[STRING]	HTML бейджа с указанным текстом
imaged[HTML, STRING, …]	HTML, компонующий картинку и текст; флаги управляют вертикальной раскладкой, ведущей позицией, переносом слов и сворачиванием, а более короткие перегрузки задают значения по умолчанию
badged[STRING, STRING, …]	та же композиция с бейджем вместо картинки; целочисленная перегрузка рисует числовой бейдж
imagedCaption[StaticObject]	компонует image и caption объекта в один фрагмент «картинка плюс текст»

Формы и навигатор

Форма icons — экран поиска и предпросмотра иконок: показывает поле поиска, выбранный стиль, лучшую подходящую иконку с её классом и оценкой, а также полную таблицу иконок с их полями и пофайловой оценкой. Размещена в навигаторе в папке system (пункт icons). isIconModuleAvailable[] устанавливается в TRUE, сигнализируя о наличии модуля.

Язык

• Оператор MATCH — полнотекстовое совпадение, по которому отбираются иконки-кандидаты под запрос.
• Оператор FORMULA — синтаксис, через который объявлены свойства ранжирования и разбиения строк.

Связано

• System modules — общий список модулей платформы.
• Utils — его раздел «Полнотекстовый поиск» описывает примитивы toTsVector / toTsQuery / tsRank, на которых построен этот модуль.
• Reflection — модуль метаданных, подключаемый вместе с Icon.
• SystemEvents — модуль событий жизненного цикла сервера, подключаемый вместе с Icon.