Реактивный экземпляр Waline

Официальный клиент @waline/client основан на Vue 3, предоставляет реактивные компоненты и экземпляры, а также обеспечивает поддержку SPA (одностраничных приложений).

Компонент Vue

Если вы создаёте проект на Vue, компонент Waline можно получить, импортировав именованный экспорт Waline из @waline/client/component.

Все свойства компонента реактивны: при изменении свойств поле комментариев обновляется автоматически.

Другие проекты

В других SPA нужно сохранять WalineInstance, который возвращает функция Waline при инициализации.

У экземпляра WalineInstance есть свойство el и два метода: update() и destroy().

update

Вызывать update() можно в любой момент (например, когда пользователь переходит на новый маршрут). Метод update принимает необязательный параметр options: помимо el, любые другие параметры инициализации Waline можно обновить, передав новые значения.

Например:

// in `/` route
const waline = Waline.init({
  serverURL: 'https://example.com',
});

/* User: after some time, route has changed to `/a.html` */

waline.update(); // Now waline will start clear the comment and show a loading state.
// After some time, the counter and comments will be all updated

waline.update({
  lang: 'en',
  login: 'disable',
}); // waline will now display in English, and disable user login

Принцип работы

При вызове update текущие и предыдущие параметры объединяются поверхностным копированием, после чего экземпляр Waline обновляется с новыми параметрами (и сохраняет их).

По умолчанию метод всегда заново формирует значения по умолчанию для ещё не заданных параметров и использует прежние значения для уже заданных.

На два параметра стоит обратить особое внимание: path и locale.

Особенности path

В версии V2 параметр path всегда сбрасывается при вызове update().

Это значит, что при любом обновлении, если не указать path, он будет сброшен в window.location.pathname.

Особенности locale

Из-за поверхностного копирования старые параметры locale полностью перезаписываются новыми, переданными в update.

Мы исходим из того, что пользователи обычно хотят переключить язык отображения при обновлении локали, поэтому такое поведение задано как ожидаемое для плагина. Это также означает, что с помощью update({ locale: {} }) можно очистить пользовательскую конфигурацию локали из истории.

Если действительно нужно обновить одно или несколько отдельных полей locale, передавайте locale целиком.

Кроме того, параметр update() оптимизирован для асинхронных сетевых запросов:

• область комментариев обновляется и запрос повторяется, только если путь действительно изменился;
• новый вызов update() автоматически прерывает ставший ненужным запрос предыдущего update().

el

Свойство el — это HTMLElement, в который смонтирован текущий экземпляр Waline.

Если инициализировать Waline с el: null (использовать только комментарии и статистику просмотров), это свойство будет равно null.

destroy

Метод destroy() уничтожает экземпляр Waline. Он также очищает всё содержимое элемента, в который смонтирован Waline.

Ошибка инициализации

Если вы забыли задать serverURL или Waline не может найти место монтирования по параметру el на странице, Waline вернёт WalineErrorInstance.

У WalineErrorInstance есть только один атрибут errMsg, указывающий причину неудачной инициализации.

Меры предосторожности

Не забывайте уничтожать экземпляр

Чтобы Waline корректно освобождал ресурсы, вызывайте WalineInstance.destroy() вручную перед удалением элемента, в который смонтирован Waline.

Иначе некоторые слушатели могут быть удалены некорректно.