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

Bliss.js является легковесной библиотекой для работы с DOM и упрощения манипуляций с элементами веб-страницы. Ключевым аспектом её использования является строгая структура передаваемых параметров и понимание возвращаемых значений методов.

Передача параметров

В большинстве функций Bliss.js используются следующие типы параметров:

  1. Селекторы и элементы

    • Параметром может быть CSS-селектор (string) или объект HTMLElement.

    • Например, метод Bliss.$ принимает селектор и возвращает первый элемент, соответствующий условию.

      const button = Bliss.$('#submit');

    • В случае передачи HTMLElement функции обрабатывают его напрямую, минуя поиск в DOM.

  2. Объекты конфигурации

    • Многие методы принимают объект с опциями, позволяя задавать несколько параметров сразу.

    • Пример для метода Bliss.on:

      Bliss.on(button, {
  click: () => console.log('Нажатие'),
  mouseover: () => console.log('Наведение')
});

    • Ключи объекта — названия событий, значения — функции-обработчики.

  3. Функции обратного вызова (callback)

    • Bliss.js активно использует callback-функции для обработки событий и асинхронных операций.

    • Callback может принимать аргументы, автоматически передаваемые библиотекой, например событие или индекс элемента:

      Bliss.$$('.items').forEach((el, idx) => console.log(el, idx));

Обработка нескольких элементов

Bliss.js поддерживает работу как с одиночными элементами, так и с коллекциями элементов. При этом параметры и возвращаемые значения ведут себя различно:

  • Методы, работающие с одиночным элементом

    • Возвращают конкретный HTMLElement или значение свойства.

    • Например:

      const text = Bliss.$('#title').textContent;

  • Методы для коллекций

    • Возвращают массив элементов или массив значений.
    • Методы, подобные Bliss.$$('.items'), возвращают Array, даже если найден один элемент.
    • Такой подход облегчает использование функций map, filter и forEach.

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

Bliss.js строго структурирует возвращаемые значения для удобства цепочек вызовов:

  1. Цепочки вызовов

    • Большинство методов возвращают либо сам элемент, либо коллекцию элементов, что позволяет строить цепочки:

      Bliss.$('#container')
  .addClass('active')
  .setAttribute('data-loaded', 'true');

  2. Значения свойств

    • При получении значения конкретного свойства метод возвращает примитивное значение (string, boolean, number) вместо объекта.

      const isVisible = Bliss.$('#menu').visible;

  3. Булевы значения

    • Проверка состояния элемента или события возвращает логический тип:

      const hasClass = Bliss.$('#item').hasClass('highlight');

Типизация и допустимые значения

Bliss.js не использует строгую типизацию TypeScript по умолчанию, но соблюдение правильного типа параметров критично для корректной работы функций:

  • Селектор должен быть строкой с корректным CSS-синтаксисом.
  • Объект опций не должен содержать неизвестных ключей.
  • Callback-функции должны быть функциями, иначе произойдёт ошибка во время выполнения.

Обработка ошибок параметров

Bliss.js включает встроенные проверки:

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

Практические рекомендации

  • Использовать объекты конфигурации для группировки параметров.

  • Предпочитать селекторы над прямыми элементами только при необходимости поиска.

  • Проверять возвращаемые значения перед применением методов коллекции:

    const items = Bliss.$$('.item');
if (items.length > 0) {
  items.forEach(el => el.addClass('visible'));
}

  • Для методов, возвращающих примитивные значения, избегать применения цепочек без обертки элемента.

Понимание правил передачи параметров и обработки возвращаемых значений позволяет максимально эффективно использовать Bliss.js, строить надёжные цепочки вызовов и предотвращать ошибки при работе с DOM.

Оглавление