Совместимость с jQuery

Виджеты в стиле amoCRM пишутся как define(['jquery'], function ($) { ... }). Bito разрешает эту зависимость в настоящий jQuery 4 — полную (не slim) сборку, которая поставляется вместе с админ-панелью. В нём заменены лишь несколько методов; всё остальное — DOM, события (включая пространства имён), эффекты, плагины $.fn, $.Deferred — работает как в обычном jQuery 4.

Он доступен только как зависимость 'jquery' (или '$') вашего модуля и как $modal в колбэке settings. Bito не записывает его в window.$ или window.jQuery, а сама админ-панель jQuery не использует — сторонний скрипт, ожидающий глобальную переменную, его не найдёт. Все виджеты на странице делят один экземпляр $: плагин, добавленный вами в $.fn, виден и другим виджетам, поэтому давайте ему уникальное имя.

Что заменено

Метод	Что происходит
$.ajax, $.get, $.post	Идут через HTTP-клиент админ-панели — см. ниже.
$.trim	Удалён в jQuery 4, возвращён: String(value ?? '').trim().
$.isArray	Удалён в jQuery 4, возвращён: Array.isArray.
$.isFunction	Удалён в jQuery 4, возвращён: typeof value === 'function'.
$.parseJSON	Удалён в jQuery 4, возвращён: ровно JSON.parse — пустая строка бросает ошибку.

Только эти семь. Другие помощники, удалённые в jQuery 4, — например $.type, $.now, $.isNumeric, $.isWindow, $.camelCase, .andSelf(), .size() — не возвращены: замените их в старом коде нативными аналогами.

$.ajax идёт через HTTP-клиент приложения

$.ajax, $.get и $.post работают не через XHR jQuery, а поверх того же HTTP-клиента, что использует админ-панель. Поэтому запрос получает авторизацию вошедшего пользователя, язык, часовой пояс и ключ идемпотентности — собственные ключи виджету не нужны. Из этого следует:

• HTTP-метод сводится. Только GET остаётся GET; любой другой type/method, включая PUT, DELETE и PATCH, отправляется как POST — в соответствии с админ-API, где даже чтение идёт через POST.
• URL берётся как есть. В отличие от bito.ajax, префикс за вас никто не добавляет.
• Поддерживаемые параметры: url, type/method, data, headers, timeout, success, error, complete. dataType и прочие настройки jQuery игнорируются, умолчания $.ajaxSetup тоже не применяются.
• Конверт ответа разворачивается. success и done получают часть data ответа Bito, а не весь конверт { code, data, ... }.
• Помощники jQuery, построенные на этих трёх методах ($.getJSON, .load()), идут тем же путём. Поскольку dataType игнорируется, $.getScript скрипт не выполняет.

Возвращается promise jQuery Deferred (done/fail/always/then) с добавленными полями в духе jqXHR:

Поле	Значение
status	200 при успехе; HTTP-статус из ошибки Bito при ошибке; 0 при сетевом сбое
statusText	"OK" при успехе, текст ошибки при ошибке
responseJSON	Развёрнутый ответ (при успехе) или конверт ошибки Bito (при ошибке)
responseText	То же самое в виде JSON-строки
readyState	1 до завершения запроса, затем 4
abort()	Ничего не делает. Запрос отменить нельзя.
getResponseHeader(), getAllResponseHeaders()	Всегда null / "" — заголовки ответа недоступны

success(data, 'success', jqXHR), error(jqXHR, 'error', err) и complete(jqXHR, status) вызываются в порядке jQuery, а done/fail срабатывают синхронно, как в jQuery.

$.ajax({
  url: '/back-api/admin/customer/get-paging',
  data: { page: 1, limit: 20 },
  success: function (data) { /* data — часть `data` конверта */ },
  error: function (jqXHR) {
    if (jqXHR.status === 403) { /* ... */ }
  },
})

WARNING

Если админ-API вернёт 401, админ-панель разлогинит пользователя — это касается и запросов вашего виджета.

Для вызовов админ-API Bito предпочтительнее bito.ajax — он сам добавляет префикс.