Функция up.replace

Функция up.replace является одной из ключевых возможностей библиотеки Unpoly, обеспечивающей замену содержимого целевого элемента на странице без полной перезагрузки. Основной принцип работы заключается в том, что переданный HTML-фрагмент или результат AJAX-запроса подставляется в указанный контейнер, при этом Unpoly автоматически обрабатывает анимацию, скрипты и стили.

Синтаксис:

up.replace(target, content, options)
  • target — CSS-селектор, DOM-элемент или объект up.Fragment, определяющий контейнер, в который будет подставлен контент.
  • content — HTML-строка, DOM-элемент, DocumentFragment или промис, возвращающий контент.
  • options — объект с дополнительными настройками замены, такими как анимация, фокус, события и управление историей браузера.

Замена содержимого

Самая простая форма использования:

up.replace('#content', '<div>Новый контент</div>');

В этом примере элемент с идентификатором content полностью заменяется новым HTML. Все дочерние элементы удаляются, а на их место вставляется указанный фрагмент.

Ключевые особенности:

  • Скрипты в контенте: любые <script> внутри переданного HTML автоматически выполняются.
  • События на старом контенте: Unpoly очищает события, привязанные через up.on к удаляемым элементам.
  • Стили: inline-стили и классы применяются к новому контенту без изменений в глобальных стилях.

Целевой элемент

target может быть задан различными способами:

  1. CSS-селектор:
up.replace('.main-panel', '<p>Обновлено</p>');
  1. DOM-элемент:
const container = document.querySelector('#sidebar');
up.replace(container, '<ul><li>Элемент</li></ul>');
  1. Фрагмент Unpoly:
up.ajax('/fragment')
  .then(fragment => up.replace(fragment.target, fragment));

Фрагменты позволяют плавно интегрировать асинхронные запросы с минимальным количеством кода.

Работа с асинхронным контентом

up.replace поддерживает промисы, возвращающие HTML. Это особенно удобно при использовании up.ajax:

up.replace('#content', up.ajax('/posts/latest'));

В этом случае Unpoly дождётся завершения AJAX-запроса, затем вставит полученный HTML в указанный контейнер. Любые ошибки запроса можно обработать через метод .catch.

Настройки и опции

Анимация

Unpoly позволяет плавно заменять контент с эффектами появления и исчезновения:

up.replace('#content', '<div>Обновлено</div>', { fade: true });
  • fade: true — плавное исчезновение старого контента и появление нового.
  • Можно использовать другие эффекты, например slide: true.

История браузера

Опция history управляет записью действия в историю:

up.replace('#content', '<div>Страница обновлена</div>', { history: true });

Если установлено history: true, URL в адресной строке обновится без перезагрузки страницы. По умолчанию Unpoly пытается сохранить текущую историю, если используется AJAX.

События до и после замены

Unpoly предоставляет хуки для управления процессом:

up.replace('#content', '<p>Новый текст</p>', {
  onBeforeReplace: (event) => {
    console.log('Старый контент ещё доступен', event.oldFragment);
  },
  onAfterReplace: (event) => {
    console.log('Новый контент добавлен', event.newFragment);
  }
});
  • onBeforeReplace — вызывается перед заменой, позволяет отменить действие через event.preventDefault().
  • onAfterReplace — вызывается после успешной вставки нового контента.

Управление фокусом

Опция focus позволяет автоматически установить фокус на новый элемент:

up.replace('#form-container', '<input type="text" id="name">', { focus: '#name' });

Unpoly корректно перемещает фокус на указанный селектор после вставки контента.

Частичная замена

up.replace не ограничивается полной заменой контейнера. Можно обновлять только часть содержимого:

up.replace('#comments', '<li>Новый комментарий</li>', { append: true });
  • append: true — новый HTML добавляется в конец контейнера.
  • prepend: true — добавление в начало.
  • replace: false — предотвращает удаление существующих элементов (по умолчанию replace равен true).

Примеры интеграции с формами

Unpoly отлично работает с формами и их асинхронной отправкой:

up.form('#new-post', {
  success: (response, event) => {
    up.replace('#posts', response.html, { append: true });
  }
});

В этом примере после успешной отправки формы новый пост добавляется в список постов без перезагрузки страницы. Весь процесс полностью управляется Unpoly, включая валидацию, отображение ошибок и плавную анимацию вставки.

Преимущества использования up.replace

  • Избавляет от необходимости ручного манипулирования DOM и обработки событий.
  • Поддерживает асинхронные операции и плавные анимации.
  • Интегрируется с историей браузера и формами.
  • Уменьшает количество дублируемого кода и повышает отзывчивость интерфейса.

Функция up.replace является базовым инструментом для создания динамических, отзывчивых веб-приложений на базе Unpoly, обеспечивая лёгкую замену контента с минимальными усилиями и полной поддержкой современных веб-паттернов.

Оглавление