Базовые ассеты SF4 и их подключение через загрузчикlink

В SF4 ассеты подключаются не “россыпью” по файлам, а пакетами (группами ресурсов). Пакет описывает:

• имя и “домашнюю” директорию пакета (dir);
• версии пакета (например default) и каталог версии (asset[version][dir]);
• перечень файлов, которые нужно подключить (file[]), где каждый файл имеет path и type (style, script, реже string).

Загрузка пакета происходит через внутренний загрузчик ассетов SF4 (который, в итоге, добавляет ресурсы стандартным способом Bitrix через \Bitrix\Main\Page\Asset::getInstance()->addCss/addJs/addString). Важно, что при включённой опции Bitrix use_minified_assets загрузчик пытается взять .min.css/.min.js, если такой файл существует рядом с обычным.

Практически это даёт два удобства:

1. включение ресурсов “по смыслу”: “подключи bootstrap”, “подключи simai.framework”, “подключи fancybox” — вместо ручного списка CSS/JS;
2. контроль версий и состава пакетов централизованно в конфигурации, а не размазан по шаблонам.

Проектные CSS/JS через {site_dir}/simai.data/templatelink

Проектные стили/скрипты (то, что относится к конкретному сайту/решению) размещаются в проектном слое:

• {site_dir}/simai.data/template/style/...
• {site_dir}/simai.data/template/js/...

Логика здесь такая: системные пакеты и системная “база” остаются в ядре, а всё, что относится к конкретному проекту (визуальные правки, дополнительный JS, правки поведения, интеграции), кладётся в simai.data/template, чтобы:

• обновления SF4 не затирали правки проекта;
• перенос сайта между средами был предсказуемым;
• проектная часть отделялась от платформы.

На уровне практики это обычно выглядит так:

• базовая страница подключает системные пакеты SF4;
• поверх них подключаются проектные файлы (CSS/JS) из simai.data/template, либо напрямую в шаблоне, либо через объявление собственных пакетов в конфигурации ассетов сайта.

Конфигурация ассетов на уровне сайта: {site_dir}/simai.data/config/.asset.config.phplink

Для сайта предусмотрен отдельный конфиг:

• {site_dir}/simai.data/config/.asset.config.php

По смыслу он такой же, как системный конфиг пакетов: описывает пакеты, версии и список файлов, которые нужно подключать “группой”. Это удобная точка управления тем, какие именно ресурсы считаются “базовыми” для вашего проекта и как они должны подключаться.

Типовой формат пакета (упрощённо, в стиле SF4) выглядит так:

<?php

return [
    'my.project' => [
        'name' => 'My Project Assets',
        'dir' => '/my.project',
        'asset' => [
            'default' => [
                'version' => '1.0.0',
                'dir' => '/v1',
                'file' => [
                    ['path' => '/css/project.css', 'type' => 'style'],
                    ['path' => '/js/project.js', 'type' => 'script'],
                ],
            ],
        ],
    ],
];

Смысл: вы можете собрать свои CSS/JS в отдельный пакет и подключать его так же, как системные (bootstrap, swiper, simai.framework и т.д.), не размазывая подключения по страницам.

Правило проекта: конфигурация ассетов сайта замещает, а не дополняет системнуюlink

В вашем проектном подходе действует принцип замещения: если на уровне сайта объявлен пакет (или переопределён системный пакет тем же кодом), то используется проектное определение пакета, а не “добавка поверх системного”.

Что это означает на практике:

• если вы переопределяете системный пакет (например, хотите зафиксировать состав/версии, чтобы обновление ядра не поменяло поведение сайта), вы описываете пакет в {site_dir}/simai.data/config/.asset.config.php с тем же кодом;
• дальше сайт будет опираться на вашу конфигурацию пакета как на стабильную точку, а изменения в ядре не будут “случайно” менять набор подключаемых файлов.

Этот принцип особенно полезен, когда:

• в ядре обновили состав пакета (добавили/убрали plugin-файлы), а проект должен остаться стабильным;
• вы хотите заранее контролировать, какие библиотеки реально используются на сайте;
• вы настраиваете производительность и исключаете лишние ресурсы, сохраняя предсказуемый результат.