Style.setProperty: примеры (JAVASCRIPT)

Простые примеры использования

Изменение стандартного CSS-свойства:

const elem = document.getElementById('myElement');
elem.style.setProperty('color', 'blue');
// Эквивалентно elem.style.color = 'blue';

// Визуально цвет текста элемента становится синим.

Установка свойства с приоритетом 'important':

elem.style.setProperty('display', 'block', 'important');

// Свойство display: block будет иметь приоритет !important.

Работа с кастомными CSS-переменными:

document.documentElement.style.setProperty('--header-height', '80px');
// Устанавливает значение для переменной в корневом элементе.

// Переменная --header-height будет доступна для использования в CSS.

Удаление свойства:

elem.style.setProperty('margin', '');
// Удаляет свойство margin из inline-стилей элемента.

// Свойство margin удалено. Будет применено значение из CSS-правил.

Похожие методы в JavaScript

Прямое присваивание свойств объекта style: element.style.color = 'red'; Более краткий синтаксис для стандартных свойств, но не работает с кастомными свойствами и флагом !important.

element.style.cssText: element.style.cssText = 'color: red; background: blue;'; Позволяет установить несколько свойств сразу как строку, но полностью перезаписывает все inline-стили элемента.

Добавление/удаление CSS-классов: element.classList.add('active'); Управление стилями через заранее определенные классы в CSS. Предпочтительнее для сложных, многосвойственных изменений и лучшей отделенности логики от представления.

Выбор метода: setProperty лучше использовать для кастомных свойств, установки !important или когда имя свойства заранее неизвестно и хранится в переменной. Прямое присваивание удобно для простых, известных свойств. Классы — для структурных изменений внешнего вида.

Типичные ошибки

Использование camelCase для стандартных свойств: Метод ожидает CSS-нотацию с дефисами.

// Неправильно:
elem.style.setProperty('backgroundColor', 'green');
// Правильно:
elem.style.setProperty('background-color', 'green');

// В первом случае свойство не будет применено.

Некорректное значение для priority: Допустимы только 'important' или пустая строка.

elem.style.setProperty('color', 'red', 'very-important'); // Игнорируется
// priority не будет распознан, флаг !important не установится.

// Свойство применится без флага !important.

Попытка использовать для несуществующего элемента:

const missingElem = document.querySelector('.nonexistent');
missingElem.style.setProperty('color', 'red'); // Ошибка TypeError

// Uncaught TypeError: Cannot read properties of null (reading 'style')

Забытое приведение чисел к строке: Значение всегда должно быть строкой.

// Неправильно, число будет преобразовано неявно, но это плохая практика:
elem.style.setProperty('z-index', 100);
// Явное приведение к строке:
elem.style.setProperty('z-index', '100');

Изменения в последних версиях

Метод setProperty() существует давно и стабилен. Существенных изменений в его работе или сигнатуре в последних версиях спецификаций не было.

Основные связанные нововведения касаются поддержки CSS Custom Properties (переменных), для работы с которыми setProperty является основным методом в JavaScript. Расширилась поддержка браузерами, но сам API метода не менялся.

При работе с флагом priority стоит учитывать, что спецификация CSS Object Model (CSSOM) четко определяет его значения.

Расширенные примеры

Динамическая темизация с кастомными свойствами:

// Установка темы из JavaScript
function setTheme(primaryColor, fontSize) {
  const root = document.documentElement;
  root.style.setProperty('--primary', primaryColor);
  root.style.setProperty('--base-size', `${fontSize}px`);
}
// Вызов функции
setTheme('#1a73e8', 16);

// CSS-переменные --primary и --base-size обновлены для всего документа.

Постепенная анимация через requestAnimationFrame:

const box = document.querySelector('.box');
let opacity = 0;
function fadeIn() {
  opacity += 0.01;
  box.style.setProperty('opacity', opacity.toString());
  if (opacity < 1) {
    requestAnimationFrame(fadeIn);
  }
}
fadeIn();

// Плавное появление элемента от прозрачного к непрозрачному.

Управление комплексными трансформациями без перезаписи:

// Безопасное добавление вращения к существующей трансформации
const elem = document.querySelector('.rotatable');
const currentTransform = elem.style.transform || '';
// Добавляем rotate(45deg) к текущему значению
// setProperty позволяет избежать конфликта с другими частями transform
elem.style.setProperty('transform', `${currentTransform} rotate(45deg)`.trim());

// К текущим трансформациям элемента добавляется вращение на 45 градусов.

Получение и изменение свойства с учетом приоритета:

// Установка с флагом important
const btn = document.getElementById('submit-btn');
btn.style.setProperty('display', 'none', 'important');
// Проверка, установлен ли important (через getPropertyPriority)
const priority = btn.style.getPropertyPriority('display');
console.log(priority); // 'important'
// Удаление свойства вместе с его приоритетом
btn.style.removeProperty('display');

// Кнопка будет скрыта с высоким приоритетом,
// а затем свойство display полностью удалено из inline-стилей.

Аналоги в других языках

Python (Tkinter): Установка свойств виджетов через метод configure.

label.configure(text='Новый текст', background='gray')
# Изменяет несколько свойств виджета одновременно.

# Внешний вид виджета label обновляется.

PHP (DOM Extension): Работа со стилями через атрибут элемента.

$element->setAttribute('style', 'color: red; font-weight: bold;');
# Аналогично cssText в JavaScript, заменяет все inline-стили.

// Атрибут style элемента получает новое значение.

C# (Windows Forms): Изменение свойств элемента управления.

button1.BackColor = System.Drawing.Color.Red;
// Синтаксис похож на прямое присваивание в JS.

// Цвет фона кнопки изменяется на красный.

Отличия: В Python, PHP, C# работа со стилями часто является частью более общих API для управления свойствами объектов или виджетов, тогда как в JavaScript setProperty - специализированный метод для CSS, работающий со строковыми именами свойств.