Перейти к основному содержимому

@form-guardian/dom

Универсальное автосохранение форм на основе DOM. Работает с любым фреймворком или обычными HTML-формами.

Установка​

npm install @form-guardian/dom

attachFormAutosave(options)​

Основная функция для подключения автосохранения к форме.

Импорт:

import { attachFormAutosave } from '@form-guardian/dom';

Параметры:

  • formId (string, обязательный) - Уникальный идентификатор формы
  • root (HTMLFormElement | HTMLElement, обязательный) - Корневой элемент (форма или контейнер)
  • autoRestore (boolean, опциональный) - Автовосстановление при монтировании (по умолчанию: false)
  • debounceMs (number, опциональный) - Задержка debounce в миллисекундах (по умолчанию: 500)
  • ttl (object | number, опциональный) - Время жизни черновиков
  • blacklist (string[], опциональный) - CSS селекторы для исключения полей
  • whitelist (string[], опциональный) - CSS селекторы для включения полей
  • fieldSelector (string, опциональный) - Селектор для отслеживаемых полей
  • excludeSelector (string, опциональный) - Селектор для исключаемых полей
  • onBeforeSave (function, опциональный) - Колбэк перед сохранением черновика
  • onAfterSave (function, опциональный) - Колбэк после успешного сохранения
  • onBeforeRestore (function, опциональный) - Колбэк перед восстановлением
  • onAfterRestore (function, опциональный) - Колбэк после успешного восстановления
  • onDraftExpired (function, опциональный) - Колбэк когда черновик истекает
  • batchSaveInterval (number, опциональный) - Интервал пакетного сохранения в миллисекундах
  • includeOrigin (boolean, опциональный) - Включить origin в ID черновика (по умолчанию: true)
  • storagePrefix (string, опциональный) - Префикс ключа хранилища (по умолчанию: 'fg')

Возвращает: FormAutosaveHandle

Пример:

const handle = attachFormAutosave({
  formId: 'my-form',
  root: document.getElementById('my-form'),
  autoRestore: true,
  debounceMs: 300,
  onBeforeSave: async (values) => {
    console.log('Сохраняем черновик...', values);
  },
  onAfterSave: async (values) => {
    console.log('Черновик успешно сохранен!');
  },
});

// Доступные методы:
handle.restore();         // Восстановить черновик
handle.clear();          // Очистить черновик
handle.destroy();        // Удалить обработчики событий
handle.hasDraft();       // Проверить наличие черновика
handle.getCurrentValues(); // Получить текущие значения формы

FormAutosaveHandle​

Объект, возвращаемый функцией attachFormAutosave().

Методы​

restore(): Promise<void>​

Восстановить значения черновика в форму.

await handle.restore();

clear(): Promise<void>​

Очистить черновик из хранилища.

await handle.clear();

destroy(): void​

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

handle.destroy();

getCurrentValues(): Promise<T>​

Получить текущие значения формы как объект.

const values = await handle.getCurrentValues();
console.log(values); // { name: 'Иван', email: 'ivan@example.com' }

hasDraft(): Promise<boolean>​

Проверить, существует ли черновик для этой формы.

const exists = await handle.hasDraft();
if (exists) {
  console.log('Черновик найден!');
}

getDraftMeta(): Promise<DraftMeta | null>​

Получить метаданные черновика (временная метка, formId и т.д.) без загрузки значений.

const meta = await handle.getDraftMeta();
if (meta) {
  console.log('Черновик обновлен:', new Date(meta.updatedAt));
}

Примеры использования​

Vanilla JavaScript​

import { attachFormAutosave } from '@form-guardian/dom';

const form = document.getElementById('contact-form');
const autosave = attachFormAutosave({
  formId: 'contact-form',
  root: form,
  autoRestore: true,
  debounceMs: 500,
});

form.addEventListener('submit', async (e) => {
  e.preventDefault();
  // Очистить черновик после успешной отправки
  await autosave.clear();
  // Отправить данные формы...
});

Vue 3​

<script setup>
import { onMounted, onBeforeUnmount, ref } from 'vue';
import { attachFormAutosave } from '@form-guardian/dom';

const formRef = ref(null);
let autosave = null;

onMounted(() => {
  autosave = attachFormAutosave({
    formId: 'my-form',
    root: formRef.value,
    autoRestore: true,
  });
});

onBeforeUnmount(() => {
  if (autosave) {
    autosave.destroy();
  }
});

const handleSubmit = async () => {
  await autosave.clear();
  // Логика отправки...
};
</script>

<template>
  <form ref="formRef" @submit.prevent="handleSubmit">
    <!-- поля формы -->
  </form>
</template>

Angular​

import { Component, ElementRef, OnInit, OnDestroy, ViewChild } from '@angular/core';
import { attachFormAutosave, FormAutosaveHandle } from '@form-guardian/dom';

@Component({
  selector: 'app-my-form',
  template: `<form #myForm (submit)="onSubmit($event)">...</form>`
})
export class MyFormComponent implements OnInit, OnDestroy {
  @ViewChild('myForm') formElement!: ElementRef;
  private autosave: FormAutosaveHandle | null = null;

  ngOnInit() {
    this.autosave = attachFormAutosave({
      formId: 'my-form',
      root: this.formElement.nativeElement,
      autoRestore: true,
    });
  }

  ngOnDestroy() {
    if (this.autosave) {
      this.autosave.destroy();
    }
  }

  async onSubmit(event: Event) {
    event.preventDefault();
    await this.autosave?.clear();
    // Логика отправки...
  }
}

Связанные материалы​