Перейти к содержанию

JS/CSS-вставки в карточке задачи

В мобильном приложении JS-вставка отображается в карточке задачи как отдельная вкладка с веб-виджетом: блок HTML-содержимого, которое приходит с заданного в настройке эндпоинта и показывается во встроенном веб-вью.

Настройка выполняется в настройках категории, раздел «Настройки JS и CSS вставок».

Это не событийная кастомизация формы задачи средствами JS/CSS веб-клиента. Тот механизм относится к веб-клиенту и в мобильном приложении не применяется — см. Форма задачи → JS-вставки (первоисточник).

Отличия от похожих механизмов

Похожий механизм Чем отличается
dashboardCustomURL webView-плитка на дашборде, отображающая внешний URL во фрейме (previewURL). Это не вкладка в карточке задачи.
Виджеты домашнего экрана ОС Нативные home-screen виджеты операционной системы, к карточке задачи отношения не имеют.
Событийные веб JS/CSS-вставки Событийная кастомизация формы задачи средствами JS/CSS — механизм веб-клиента. В мобильном приложении не применяется. Первоисточник.

Как настроить виджет

Шаг 1. Создать вставку в настройках категории

В настройках категории откройте раздел «Настройки JS и CSS вставок» и создайте вставку:

  • тип контента — js;
  • включите флаг «использовать в MTF»;
  • задайте название вставки — оно станет заголовком вкладки в карточке задачи.

Вкладка появляется в карточке задачи, когда вставка имеет тип js и включён флаг использования в MTF. Если название вставки не задано, заголовком вкладки служит ключ title из блока конфигурации (см. ниже); если не задано ни то ни другое — вкладка не создаётся.

Шаг 2. Описать блок конфигурации __WIDGET_CONFIG__

В тело вставки поместите блок конфигурации между парными маркерами:

/* __WIDGET_CONFIG__
{
  "title": "Заголовок секции",
  "url": "https://example.com/widget или /relative/path",
  "method": "POST",
  "body": {
    "param1": "@ep1234",
    "param2": "@taskId",
    "param3": 123,
    "param4": true
  }
}
__WIDGET_CONFIG__ */

Ключи JSON:

Ключ Тип Обязательный По умолчанию Описание
url строка да — Абсолютный URL или относительный путь эндпоинта виджета. Не должен быть пустым.
method строка нет POST HTTP-метод запроса: GET или POST.
body объект нет {} Параметры запроса. Допускаются только плоские значения: строка, число, булево.
title строка нет — Заголовок вкладки. Используется, если название вставки (шаг 1) не задано.

Вложенные объекты и массивы в body не поддерживаются — при их наличии виджет не загрузится. Передавайте только плоские пары «ключ — значение».

Шаг 3. Подстановки в url и body

Перед отправкой запроса в url и в строковых значениях body подставляются динамические значения текущей задачи:

Плейсхолдер Значение
@taskId Идентификатор текущей задачи.
@ep123 или @ep{123} Значение дополнительного параметра задачи с указанным идентификатором.

Нестроковые значения body (числа, булевы) подставлению не подлежат и передаются как есть.

Шаг 4. Требования к эндпоинту (контракт ответа)

Приложение обращается к url указанным методом (для POST — передаёт body как параметры запроса) и ожидает в ответ JSON:

{
  "ok": true,
  "html": "<div>...содержимое виджета...</div>",
  "error": null
}

Поведение приложения в зависимости от ответа:

  • ok + непустой html — виджет показывается или обновляется, содержимое сохраняется для быстрого показа при следующем открытии;
  • ok + пустой html — содержимое виджета очищается;
  • сбой запроса при наличии ранее показанного содержимого — на экране остаётся прежнее содержимое и выводится предупреждение, что данные могут быть неактуальны;
  • сбой запроса без ранее сохранённого содержимого — отображается состояние ошибки.

Шаг 5 (опционально). Оформляющий контейнер — emptyPortal

Серверная настройка emptyPortal задаёт идентификатор «пустого портала», который служит оформляющим контейнером виджета и наследует его тему и стили. Содержимое виджета встраивается внутрь этого контейнера, не затирая его оформление.

Если emptyPortal не задан, используется стандартный пустой контейнер без дополнительного оформления.

Поведение и быстрый показ

  • При открытии вкладки ранее показанное содержимое выводится сразу, а в фоне выполняется обновление с сервера.
  • Содержимое виджета сохраняется в привязке к конкретной задаче и конкретной вставке.
  • Оформляющий контейнер (портал) кешируется до 1 часа.

Рекомендация

Виджет в карточке задачи — поддерживаемый способ встроить веб-содержимое в карточку. Для кастомизации самой формы задачи (поля, режимы отображения, настройки) используйте мобильные шаблоны — см. Шаблоны — обзор.

Связанные документы