Inline-правки текста через виджет

SenlerWidget.createTextEdit(config) помогает запросить изменение текста, показать предварительный вариант и применить его после подтверждения. Сайт отвечает за кнопки, загрузку, сравнение и оформление редактора. Метод требует совместимой версии SDK и виджета.

Сначала выберите область правки

• scope: "selection" меняет только непустой диапазон, возвращённый getSelection().
• scope: "field" меняет всё поле, в том числе пустое. Это режим по умолчанию.

Сохраните выделение до потери фокуса. start и end — позиции UTF-16 в той же строке, которую возвращает getValue(), а не поиск фрагмента по совпадению текста.

Создайте контроллер

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

const field = document.querySelector("#description");
const editor = SenlerWidget.createTextEdit({
  fieldId: "product:123:description",
  getValue: () => field.value,
  setValue: (value) => {
    field.value = value;
    field.dispatchEvent(new Event("input", { bubbles: true }));
  },
  getSelection: () => ({
    start: field.selectionStart,
    end: field.selectionEnd,
  }),
});

async function improve() {
  try {
    const preview = await editor.generatePreview({
      instruction: "Сделай формулировку понятнее.",
      newDialog: true,
      scope: "field",
    });
    showReview({
      before: preview.sourceText,
      after: preview.replacementText,
      onAccept: () => {
        try { editor.apply(preview); }
        catch (error) { showError(error.message); }
      },
    });
  } catch (error) {
    showError(error.message);
  }
}

showReview и showError — функции интерфейса вашего сайта, не методы виджета. Пример создаёт отдельный диалог на каждый запрос. Для повторного использования диалога используйте getOrCreateDialog и передавайте его dialogId вместо newDialog.

Передайте данные поля

• fieldId — непустой стабильный ID поля.
• getValue() — полный текущий текст.
• setValue(value) — запись подтверждённого результата в редактор.
• getSelection() — диапазон { start, end } для правки выделения.
• getRevision() — необязательная версия состояния редактора; помогает обнаружить изменение с последующей отменой.

Агенту отправляется инструкция и текст выбранной области, а не всё поле при правке выделения. Дополнительные сведения можно передать через contextItems или context в параметрах запроса. Не подключайте правку к паролям, секретам и другим данным, которые нельзя передавать агенту.

Если getValue() возвращает Markdown, пересчитывайте выделение редактора в позиции исходного Markdown. Позиции отображаемого текста не подходят для строки с разметкой и экранированием.

Запустите правку или откройте чат

generatePreview({ instruction, scope, ...options }) возвращает Promise с предварительным вариантом. Поддерживаются параметры ask, кроме text: dialogId, newDialog, ref, контекст, отмена, тайм-аут и callbacks.

По умолчанию includeHistory: false и includeActions: false: прежние сообщения не входят в запрос модели, зарегистрированные действия сайта не передаются. Это не отключает другие инструменты агента и не заменяет его системную инструкцию. Для предсказуемой правки используйте агента, который возвращает только исправленный текст.

Чтобы показать обсуждение результата, вызовите SenlerWidget.selectDialog(preview.dialogId), затем SenlerWidget.open(). Открытие чата само по себе не запускает новую правку.

Покажите предварительный вариант и примените его

preview содержит fieldId, requestId, dialogId, полный исходный sourceText, полный новый replacementText, выбранный selectedText и его замену selectedTextReplacement.

Контроллер принимает ровно один успешный ответ и не меняет поле при получении результата. Покажите сравнение, затем по подтверждению вызовите editor.apply(preview). Для выделения контроллер сохраняет остальной текст без изменений.

При применении проверяются текущее значение и getRevision(), если он задан. Устаревший, чужой или уже применённый вариант отклоняется. Не копируйте результат прямо в поле в обход этой проверки.

Обработайте состояния

Показывайте загрузку, пока generatePreview ожидается, и снимайте её при результате или ошибке. Для промежуточного состояния доступны onStatus, onChunk и onAnswer; фрагменты стриминга не являются готовой правкой.

• invalid_selection — выделение пустое или не соответствует исходной строке.
• invalid_preview — нет ровно одного успешного ответа либо вариант нельзя применить этим контроллером.
• stale_preview — содержимое поля изменилось после начала запроса.

Ошибки отправки, отмена и тайм-аут обрабатываются как в ask. После ошибки можно повторить запрос; подтверждённый на сервере запрос может продолжить работу даже после прекращения ожидания.

Жизненный цикл

Вызывайте editor.destroy(), когда поле удаляется со страницы: контроллер прекращает ожидание своих запросов и не принимает новые правки. SenlerWidget.destroy() освобождает все контроллеры своего экземпляра. Повторная правка берёт уже обновлённое значение поля. В режиме button_only запросы к агенту недоступны.

Где смотреть полный контракт

Public API описывает методы экземпляра, отправка сообщений — результат и ошибки запросов. Специальное действие или кнопка агента для доставки правки не требуется.