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

Библиотека Cash — это лёгкий и современный аналог jQuery, предоставляющий удобный API для работы с DOM, событиями, AJAX и анимацией. Важной частью работы с Cash является понимание параметров функций, так как от этого зависит корректность выполнения операций и предсказуемость результатов.

Селекторы

Практически все функции Cash, которые работают с элементами DOM, принимают первым аргументом селектор. Селектор может быть:

  • Строкой — CSS-селектор, по которому будут найдены элементы.

    const items = $('li.active');

  • DOM-элементом — одиночный HTML-элемент.

    const item = $(document.getElementById('main'));

  • Массивом или NodeList — коллекция элементов, на которых будет применяться метод Cash.

    const nodes = $([document.body, document.head]);

Если селектор не соответствует ни одному элементу, Cash возвращает пустой объект, что позволяет безопасно вызывать методы без дополнительных проверок на null или undefined.

Колбэки и функции

Многие методы Cash принимают функцию обратного вызова (callback), которая вызывается для каждого элемента коллекции:

  • В качестве параметров функции колбэка передаются:

    1. Индекс элемента в коллекции (index).
    2. Текущий элемент (element).

  • Функция может возвращать значение, которое влияет на выполнение метода, например, при использовании методов .css(), .attr() или .html().

Пример использования колбэка для динамического изменения текста:

$('li').text((index, oldText) => `Элемент ${index}: ${oldText}`);

Параметры для стилей и атрибутов

Методы .css(), .attr(), .prop() могут принимать два типа аргументов:

  1. Строковый ключ и значение:

    $('div').css('color', 'red');
$('input').attr('disabled', true);

  2. Объект с парами ключ–значение, что позволяет устанавливать несколько свойств одновременно:

    $('div').css({
  color: 'blue',
  backgroundColor: 'yellow'
});

Параметры событий

Методы работы с событиями .on(), .off(), .one() имеют несколько вариантов вызова:

  • on(event, selector, handler) Позволяет делегировать событие для потомков:

    $(document).on('click', 'button', event => console.log(event.target));

  • on(event, handler) Применяется напрямую к выбранным элементам:

    $('button').on('click', () => alert('Нажато!'));

  • Параметр event может содержать данные, переданные через .trigger().

Параметры анимации

Методы .fadeIn(), .fadeOut(), .slideUp(), .slideDown() используют следующие параметры:

  • duration — время анимации в миллисекундах или строковые значения 'slow'/'fast'.
  • easing — функция ускорения ('linear' или 'swing').
  • callback — функция, выполняющаяся после завершения анимации.

Пример:

$('div').fadeIn(400, 'swing', () => console.log('Анимация завершена'));

AJAX-параметры

Метод .ajax() в Cash наследует структуру из jQuery и принимает объект с настройками:

  • url — адрес запроса.
  • method — HTTP-метод ('GET', 'POST' и т.д.).
  • data — данные запроса, объекты автоматически сериализуются.
  • dataType — ожидаемый формат ответа ('json', 'text', 'html').
  • success и error — функции обратного вызова при завершении запроса.

Пример:

$.ajax({
  url: '/api/users',
  method: 'GET',
  dataType: 'json',
  success: data => console.log(data),
  error: err => console.error(err)
});

Возвращаемые значения методов Cash

Cash стремится к предсказуемости. Основные принципы:

  • Цепочка методов: почти все методы возвращают объект Cash, что позволяет вызывать методы подряд.

    $('div').addClass('highlight').fadeIn(300);

  • Доступ к конкретному значению:

    • .html(), .text(), .val() без аргументов возвращают текущее содержимое элемента.

      const value = $('input').val();

    • .attr() и .prop() при вызове без значения возвращают текущее свойство или атрибут.

  • Булевы значения: методы вроде .hasClass() возвращают true или false.

  • Итераторы и массивы: методы .toArray() и .get() возвращают массив элементов DOM.

Особенности обработки undefined и null

  • Методы Cash не выбрасывают исключений при работе с пустыми коллекциями.
  • При попытке получить значение с несуществующего атрибута или свойства возвращается undefined.
  • Методы изменения свойств на пустой коллекции не вызывают ошибок и возвращают объект Cash для сохранения цепочки.

Резюме по параметрам и возвращаемым значениям

  1. Селекторы могут быть строкой, элементом или коллекцией.
  2. Колбэки получают индекс и элемент, могут возвращать значения для изменения содержимого.
  3. Методы стилей, атрибутов и свойств поддерживают строки и объекты.
  4. События и анимации имеют свои специфические наборы параметров, включая callback.
  5. AJAX использует объект настроек с success/error.
  6. Возвращаемые значения: объекты Cash для цепочек, конкретные данные при геттер-методах, булевы значения при проверках, массивы через .toArray() или .get().
  7. Пустые коллекции обрабатываются безопасно, исключения не выбрасываются.

Такое структурированное понимание параметров и возвращаемых значений позволяет использовать Cash максимально эффективно и без неожиданных ошибок.

Оглавление