Параметры и возвращаемые значения

Umbrella JS — это компактная и удобная библиотека для работы с DOM в JavaScript, которая предоставляет цепочку методов, схожих с jQuery, но с минимальным размером и высокой производительностью. Понимание параметров и возвращаемых значений функций библиотеки является ключевым для эффективного использования её возможностей.

Выбор элементов и возвращаемые объекты

Функция u(selector) используется для выбора элементов DOM. Параметр selector может быть:

  • CSS-селектором — строка, например '.class', '#id' или 'div > p'.
  • DOM-элементом — одиночный элемент.
  • NodeList или массив элементов — можно передавать результат document.querySelectorAll() или массив.

Возвращаемое значение всегда является объектом Umbrella, который содержит выбранные элементы и предоставляет методы для дальнейшей работы. Этот объект поддерживает цепочку вызовов, что позволяет выполнять несколько операций последовательно без повторного выбора элементов.

let elems = u('.item'); // elems — объект Umbrella, содержащий элементы с классом item

Методы для работы с содержимым элементов

html([content]) — чтение или установка HTML-содержимого:

  • Если content не передан, возвращается строка HTML первого элемента.
  • Если content передан, устанавливается содержимое всех выбранных элементов и возвращается объект Umbrella для цепочек.
let firstHtml = u('#container').html(); // возвращает HTML первого элемента
u('.item').html('<span>Новое содержимое</span>'); // возвращает объект Umbrella

text([content]) — аналогично html(), но работает с текстовым содержимым.

val([value]) — используется для получения или установки значений формы:

  • Без аргументов возвращает значение первого элемента формы.
  • С аргументом устанавливает значение для всех выбранных элементов и возвращает объект Umbrella.

Атрибуты и свойства

attr(name, [value]):

  • Если передан только name, возвращается значение атрибута первого элемента.
  • Если передан value, атрибут устанавливается для всех выбранных элементов, возвращается объект Umbrella.

removeAttr(name) удаляет указанный атрибут с каждого элемента и возвращает объект Umbrella.

prop(name, [value]) аналогичен attr(), но работает с DOM-свойствами элементов, например checked или disabled.

Работа с классами

Методы управления классами возвращают объект Umbrella, что позволяет строить цепочки:

  • addClass(className) — добавляет класс к каждому элементу.
  • removeClass(className) — удаляет класс.
  • toggleClass(className) — переключает класс.
  • hasClass(className) — возвращает true, если первый элемент содержит указанный класс.
if (!u('#submit').hasClass('disabled')) {
    u('#submit').addClass('active');
}

Манипуляции с DOM

append(content) и prepend(content):

  • content может быть строкой HTML, DOM-элементом или объектом Umbrella.
  • Возвращают объект Umbrella с исходными элементами, а не вставленным контентом.

remove() удаляет выбранные элементы из DOM и возвращает объект Umbrella.

empty() очищает содержимое элементов, возвращает объект Umbrella.

Работа с событиями

on(event, handler) и off(event, handler):

  • event — название события ('click', 'input' и др.).
  • handler — функция-обработчик.
  • Возвращают объект Umbrella для цепочек вызовов.

trigger(event) активирует событие на всех выбранных элементах и возвращает объект Umbrella.

Размеры и позиционирование

  • width([value]) и height([value]):

    • Без аргументов возвращают числовое значение ширины/высоты первого элемента.
    • С аргументом устанавливают размеры всех элементов, возвращают объект Umbrella.

  • offset():

    • Без аргументов возвращает объект { top, left } с позиционированием первого элемента относительно документа.
    • С объектом { top, left } задаёт позицию элементов, возвращает объект Umbrella.

Итоговая структура возвращаемых значений

  1. Если метод читает данные — возвращается примитивное значение (строка, число, объект, булево) для первого элемента.
  2. Если метод изменяет элементы — возвращается объект Umbrella, поддерживающий цепочку методов.

Эта строгая схема позволяет легко предсказывать поведение функций и строить цепочки манипуляций с DOM без необходимости создавать промежуточные переменные.

Особенности работы с массивами и множественными элементами

Объект Umbrella хранит выбранные элементы в массивоподобной структуре. Методы автоматически применяются ко всем элементам, а возвращаемые значения читаются только с первого. Исключением являются методы вроде map(callback) и each(callback), которые позволяют выполнять операции и собирать результаты для всех элементов.

u('.item').each(function(el, index) {
    console.log(index, u(el).text());
});

Метод map() возвращает массив результатов, что отличается от большинства методов, возвращающих объект Umbrella.

Особенности параметров функций

  • Методы, принимающие строки (html, text, attr), поддерживают также функцию в качестве параметра, которая получает текущий индекс и текущее значение, возвращая новое значение.
  • Параметры типа DOM-элемент или Umbrella используются для вставки или объединения элементов, поддерживая гибкость при манипуляциях с деревом DOM.
u('.item').html((i, oldHtml) => `<span>${i}: ${oldHtml}</span>`);

Эта функциональность позволяет создавать динамические изменения контента без явного перебора элементов, сохраняя компактность кода.

Оглавление