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 Все режимы

Смотрите также