Asset — подключение CSS, JS и строк на страницу
Пространство имен: Bitrix\Main\Page
Модуль: main — подключать отдельно не нужно
Доступно с версии: 14.9.4
Когда использовать
Класс Asset подключает к странице CSS- и JS-файлы и произвольные строки, например метатеги. Объект один на запрос, его возвращает метод getInstance. Код страницы, шаблона или компонента добавляет файлы, а метод $APPLICATION->ShowHead() в шаблоне сайта выводит их в секции <head>.
use Bitrix\Main\Page\Asset;
$asset = Asset::getInstance();
$asset->addCss(SITE_TEMPLATE_PATH . '/css/units.css');
$asset->addJs(SITE_TEMPLATE_PATH . '/js/units.js');
$asset->addString('<meta name="theme-color" content="#2fc6f6">');
Класс раскладывает файлы по наборам. Набор определяет, в какой файл объединения попадет файл и где он выведется на странице.
| Набор | Что входит |
|---|---|
KERNEL |
Файлы ядра и модулей из /bitrix/js/ и /bitrix/css/ и внешние файлы |
TEMPLATE |
Файлы шаблона сайта — их добавляют в header.php и footer.php |
PAGE |
Файлы страницы и компонентов рабочей области |
BODY |
Скрипты для конца страницы. Если шаблон не вызывает $APPLICATION->ShowBodyScripts(), класс выводит их в head |
Если в настройках главного модуля включено объединение CSS или JS, класс собирает файлы набора в один файл в каталоге /bitrix/cache/css/ или /bitrix/cache/js/.
Подробнее — в статье Работа со стилями.
Метод setMaxCss устарел и ничего не делает. Метод moveJsToBody — служебный, ядро вызывает его само.
Методы класса
Объект и режимы
| Метод | Описание | С версии |
|---|---|---|
| getInstance | Возвращает объект | |
| setAjax | Создает новый объект для ответа на AJAX-запрос | |
| setMode | Задает режим композитного сайта | |
| setXhtml | Включает закрывающий слеш в теге link |
Подключение файлов и строк
| Метод | Описание | С версии |
|---|---|---|
| addCss | Добавляет CSS-файл | |
| addJs | Добавляет JS-файл | |
| addString | Добавляет строку HTML на страницу | |
| getStrings | Возвращает строки для места на странице | |
| getLocationByName | Переводит старое обозначение места в константу AssetLocation |
Вывод на страницу
| Метод | Описание | С версии |
|---|---|---|
| getCss | Возвращает HTML подключения CSS | |
| getJs | Возвращает HTML подключения JS и строк | |
| showFilesList | Возвращает скрипт со списком подключенных файлов для JS-ядра | |
| insertCss | Возвращает тег link или style |
|
| insertJs | Возвращает тег script |
|
| setShowHeadString | Отмечает, что шаблон выводит строки в head |
|
| getShowHeadString | Проверяет, выводит ли шаблон строки в head |
|
| setShowHeadScript | Отмечает, что шаблон выводит скрипты отдельно | |
| setShowBodyScript | Отмечает, что шаблон выводит скрипты в конце страницы |
Наборы
| Метод | Описание | С версии |
|---|---|---|
| getTargetName | Возвращает имя текущего набора | |
| getTarget | Возвращает текущий набор | |
| startTarget | Начинает набор | |
| startSet | Начинает набор, то же, что startTarget |
|
| stopTarget | Завершает текущий набор | |
| compositeTarget | Переводит набор в режим AssetMode::COMPOSITE |
|
| setUnique | Задает набору постоянный файл объединения | |
| getTargetList | Возвращает список наборов | |
| getAssetInfo | Возвращает файлы и строки набора |
Оптимизация
| Метод | Описание | С версии |
|---|---|---|
| enableOptimizeCss | Разрешает объединение CSS | |
| disableOptimizeCss | Запрещает объединение CSS | |
| enableOptimizeJs | Разрешает объединение JS | |
| disableOptimizeJs | Запрещает объединение JS | |
| optimizeCss | Проверяет, объединяет ли класс CSS-файлы | |
| optimizeJs | Проверяет, объединяет ли класс JS-файлы | |
| sliceKernel | Проверяет, выделяет ли класс файлы ядра в отдельные наборы | |
| canUseMinifiedAssets | Проверяет, подключает ли класс файлы .min |
|
| gzipEnabled | Проверяет, сжимает ли класс файлы объединения в gzip | |
| write | Записывает файл объединения |
Файлы ядра и модулей
| Метод | Описание | С версии |
|---|---|---|
| addCssKernelInfo | Регистрирует CSS-файлы модуля ядра | |
| addJsKernelInfo | Регистрирует JS-файлы модуля ядра | |
| isKernelCSS | Проверяет, относится ли CSS-файл к ядру | |
| isKernelJS | Проверяет, относится ли JS-файл к ядру | |
| groupCss | Переносит CSS модуля ядра в файл объединения другого модуля | |
| groupJs | Переносит JS модуля ядра в файл объединения другого модуля | |
| moveJs | Переносит JS модуля ядра в конец страницы |
Скрипты в конце страницы
| Метод | Описание | С версии |
|---|---|---|
| setJsToBody | Включает перенос всех скриптов в конец body |
|
| canMoveJsToBody | Проверяет, переносит ли ядро скрипты в конец body |
Пути и содержимое CSS
| Метод | Описание | С версии |
|---|---|---|
| getAssetPath | Удаляет параметры из пути к файлу | |
| getAssetTime | Возвращает метку времени из пути к файлу | |
| getFullAssetPath | Возвращает адрес файла с меткой времени | |
| replaceUrlCss | Делает относительный адрес из CSS абсолютным | |
| fixCssIncludes | Исправляет относительные адреса в содержимом CSS |
Константы
Места для строк задают константы класса Bitrix\Main\Page\AssetLocation.
| Константа | Где выводится строка |
|---|---|
BEFORE_CSS |
Перед CSS-файлами |
AFTER_CSS |
После CSS-файлов, перед скриптами ядра |
AFTER_JS_KERNEL |
После скриптов ядра. Значение по умолчанию |
AFTER_JS |
После всех скриптов в head |
BODY_END |
Вместе со скриптами набора BODY — в конце страницы, если шаблон вызывает ShowBodyScripts(), иначе в head |
Режимы композитного сайта задают константы класса Bitrix\Main\Page\AssetMode. Класс выводит строку или набор, если их режим пересекается с текущим режимом по битам.
| Константа | Значение | Описание |
|---|---|---|
STANDARD |
1 |
Стандартная страница |
COMPOSITE |
2 |
Композитная копия страницы для кеша |
SPECIAL |
4 |
Особый режим вывода |
ALL |
7 |
Все режимы |