Справочник API
.css() в jQuery
Содержание статьи
-
Категории: CSS , Manipulation › Style Properties
Устанавливает одно или несколько CSS-свойств для всех элементов в наборе jQuery (либо получает значение заданного CSS-свойства для первого элемента набора jQuery).
Синтаксис и описание:
Добавлено в jQuery 1.0.css( propertyName )
Добавлено в jQuery 1.9.css( propertyNames )
Добавлено в jQuery 1.0.css( propertyName, value )
Добавлено в jQuery 1.4.css( propertyName, function( index, value ) )
Добавлено в jQuery 1.0.css( properties )
Команда .css() — универсальный геттер и сеттер CSS-свойств для набора jQuery. Как геттер возвращает вычисленное значение свойства для первого элемента набора; как сеттер — записывает значение (или несколько сразу) в атрибут style каждого элемента набора.
Имена свойств можно писать и как в CSS, через дефис (
background-color), и в camelCase (backgroundColor) — jQuery понимает оба варианта. CSS custom properties (--main-color) с jQuery 3.2 читаются и пишутся как есть, по полному имени.
Возвращаемое значение: (строка | объект | набор jQuery) Геттер с одним именем свойства возвращает строку; геттер с массивом имён (с 1.9) — объект «свойство → значение»; любая форма сеттера возвращает набор jQuery для цепочки вызовов.
Параметры:
propertyName – (строка) Имя CSS-свойства (через дефис или в camelCase) либо имя CSS-переменной как есть (
--accent).propertyNames – (массив строк, с jQuery 1.9) Список имён для пакетного чтения; результат — объект «имя — значение».
value – (строка | число) Новое значение. Число трактуется в пикселях там, где уместно (см. примечание про 4.0); строкой — любая единица (
"2em") или смещение"+=10"/"-=10"(с jQuery 1.6).function( index, value ) – (функция, с jQuery 1.4) Возвращает новое значение; получает индекс элемента и текущее значение стиля.
properties – (объект) Пары «свойство: значение» для пакетной установки.
Примечание:
Геттер смотрит только на первый элемент набора; сеттер применяется ко всем. Меняет стиль мгновенно, без очереди эффектов — для плавного перехода нужен .animate() либо CSS
transition. С jQuery 3.2 CSS custom properties читаются и пишутся по имени как есть ($('.box').css('--accent')), без camelCase.В jQuery 3.x и 4.0:
Ключевое изменение — как jQuery решает, добавлять ли
pxк числовому значению. В jQuery 3.xpxподставлялся почти ко всем числовым CSS-свойствам, кроме известного списка «безразмерных» (opacity,zIndex,lineHeightи т. п.). В jQuery 4.0 логика обратная и заметно уже (проверено по исходникуsrc/css/isAutoPx.js): автоматическийpxдобавляется только к width/height (в т. ч.min-/max-),margin*,padding*,border*Widthиtop/right/bottom/left. Для остальных числовых свойств (letterSpacing,fontSize,borderRadius) единицу в 4.0 нужно указывать явно — иначе значение уйдёт в стиль без единицы и как невалидное будет проигнорировано браузером. Подробнее о других изменениях новой версии — в статье jQuery 4.0: что изменилось.Примечание:
Нативный аналог геттера —
getComputedStyle(el).propertyName; когда в проекте уместнее jQuery, а когда чистый JS — в статье jQuery или чистый JavaScript.
Примеры:
Базовые геттер и сеттер, сеттер сразу нескольких свойств через объект.
var color = $('.price').css('color'); // геттер $('.price').css('color', '#cc0000'); // сеттер одного свойства $('.price').css({ color: '#cc0000', fontWeight: 'bold' }); // сеттер объектомГеттер по массиву свойств (jQuery 1.9+) и работа с CSS-переменной (jQuery 3.2+).
// jQuery 1.9+: получить сразу несколько свойств одним вызовом var styles = $('.box').css(['width', 'height', 'backgroundColor']); // styles.width, styles.height, styles.backgroundColor // jQuery 3.2+: CSS custom property читается и пишется как есть $('.box').css('--accent-color', '#0a84ff'); var accent = $('.box').css('--accent-color');Относительное смещение (jQuery 1.6+), вычисление через функцию и разница единиц измерения между jQuery 3.x и 4.0.
// jQuery 1.6+: увеличить текущую ширину на 20px $('.sidebar').css('width', '+=20'); // jQuery 1.4+: новое значение — на основе старого и индекса $('.col').css('marginLeft', function(index, currentValue) { return parseFloat(currentValue) + index * 10 + 'px'; }); // width входит в список auto-px и в 3.x, и в 4.0 — станет "100px" $('.box').css('width', 100); // letterSpacing НЕ входит в этот список: // jQuery 3.x применит "2px", jQuery 4.0 — невалидное "2" без единицы. // Переносимый вариант — указывать единицу явно: $('.box').css('letterSpacing', '2px');