Zepto опирается на компактный набор функций, где каждый вызов имеет чётко определённые параметры и предсказуемые возвращаемые значения. Отсутствие громоздких абстракций делает интерфейс библиотеки линейным и прозрачным.
Основная функция Zepto() и её сокращение
$() принимают строковый CSS-селектор, DOM-элемент, массив
элементов или объект Zepto. Переданный аргумент определяет итоговый
набор выбранных элементов. Дополнительно допускается второй
параметр-контекст: узкий диапазон поиска по DOM.
Типы аргументов:
NodeList.Возвращаемое значение: объект Zepto, представляющий коллекцию элементов и методы для дальнейших операций.
Манипулирующие методы (append, prepend,
before, after, remove,
empty и др.) принимают строки с HTML, DOM-элементы или
объекты Zepto. Параметры интерпретируются без преобразования типов.
Вызовы возвращают текущую коллекцию Zepto, что обеспечивает цепочку
вызовов.
При передаче функций-колбэков в методы вставки (append,
prepend) аргументом колбэка становится индекс элемента в
коллекции, а результатом колбэка — HTML-строка или DOM-узел для вставки.
Возвращаемое значение метода остаётся объектом Zepto.
Методы attr, prop, data и
val работают в двух режимах:
undefined при отсутствии атрибута.Функции-установщики принимают индекс элемента и предыдущее значение атрибута; результаты функций должны быть примитивами или строками.
Метод css принимает имя свойства либо объект свойств. В
режиме чтения возвращается вычисленное значение свойства в виде строки.
В режиме записи метод возвращает объект Zepto. При передаче колбэков
аргументами становятся индекс и текущее значение свойства; возврат
колбэка интерпретируется как новое значение.
Методы addClass, removeClass,
toggleClass поддерживают строковые аргументы или функции.
Возвращаемым значением всегда остаётся объект Zepto. В случае
toggleClass допускается логический флаг, принудительно
определяющий состояние класса.
Методы on и off принимают имя события,
селектор для делегирования и обработчик. Порядок аргументов:
(тип, [селектор], обработчик, [параметры]). Возвращаемым
значением является объект Zepto.
Обработчики событий получают объект события, дополненный
Zepto-специфичными свойствами, и контекст this, указывающий
на текущий элемент DOM. Возвращаемые значения обработчиков не
используются Zepto, за исключением случая false, который
предотвращает поведение по умолчанию и останавливает всплытие.
Метод trigger принимает имя события и необязательные
данные. Возвращаемым значением снова служит объект Zepto.
Функция $.ajax принимает объект конфигурации. Основные
параметры: url, type, data,
dataType, timeout, success,
error, complete. Функция возвращает объект
XMLHttpRequest или его аналог. Обработчики получают данные
ответа, статус и сам объект запроса. Возвращаемые значения обработчиков
игнорируются.
Методы-обёртки $.get, $.post,
$.getJSON принимают URL, данные и колбэки. Эти вызовы
возвращают XMLHttpRequest и не поддерживают цепочку
Zepto.
Метод animate принимает объект конечных свойств,
длительность, кривую ускорения и колбэк завершения. Возвращаемым
значением является объект Zepto. Колбэк завершения вызывается без
аргументов. Методы show, hide,
toggle в анимационных режимах разделяют такой же набор
параметров и поведение.
Методы each, map, filter,
not, eq получают индекс и элемент.
each возвращает исходную коллекцию Zepto.map возвращает новый объект Zepto с результатами.filter и not принимают селектор или
функцию; возвращают новую коллекцию Zepto.eq принимает индекс и возвращает коллекцию из одного
элемента.Методы width, height, offset,
position принимают ноль или один параметр. При чтении
возвращаются числа или объекты с координатами. При записи возвращается
объект Zepto. Колбэки принимают индекс и текущее значение.
Zepto строго разделяет возвращаемые значения:
Такое разделение упрощает предсказуемость цепочек вызовов: методы не меняют тип возвращаемого значения при одинаковом наборе параметров.
Отсутствие элемента или невозможность применить операцию в
большинстве случаев приводит к тихой обработке: операции записи
возвращают пустую коллекцию Zepto, операции чтения —
undefined или пустые строки. Исключения сознательно не
генерируются, что упрощает цепочное применение, но требует аккуратной
проверки результатов от операций чтения.
Центральный принцип интерфейса Zepto — возвращаемой сущностью почти всегда является объект Zepto, который хранит внутреннюю ссылку на массив DOM-элементов. Этот массив не копируется при передаче в методы и предусматривает конкатенацию, фильтрацию и переиспользование без дополнительных аллокаций.
Использование колбэков характерно для большинства методов. Колбэки принимают:
Возвращаемое значение колбэков либо становится аргументом операции, либо игнорируется, если операция направлена на получение значения.
Большая часть методов допускает перегрузку параметров по типу. Такой стиль снижает необходимость в дополнительных API и позволяет описывать разные операции в едином синтаксисе. Перегрузка не нарушает предсказуемость: одинаковые типы аргументов порождают одинаковый тип результата.
В отдельных случаях методы отдают нативные DOM-объекты или массивы
(get, toArray). Эти методы служат границей
между Zepto и внешним кодом, что позволяет комбинировать библиотеку с
нативными API без накладных преобразований.
Параметры и возвращаемые значения в Zepto формируют лаконичную систему: минимальное количество типов аргументов, чёткая стратегия разделения режимов чтения и записи, неизменность типа возвращаемого значения при одинаковых параметрах и поддержка функциональных паттернов. Такая модель обеспечивает предсказуемость и линейность использования, что особенно заметно при построении цепочек операций над DOM.