general-form-storage/README.md

A form storage solution with cross-tab synchronization

# FormStorage - 跨标签页表单同步解决方案

![npm](https://img.shields.io/npm/v/general-form-storage)
![license](https://img.shields.io/npm/l/general-form-storage)

`FormStorage` 是一个专为 Vue 3 设计的表单状态管理库，提供跨标签页的实时数据同步和自动保存功能。

## ✨ 特性

- **跨标签页同步**：使用 BroadcastChannel 实现不同标签页间的实时数据同步
- **自动保存**：在页面隐藏或关闭时自动保存表单数据
- **防抖保存**：内置防抖机制，避免频繁保存
- **数据隔离**：通过 formId 区分不同表单的数据
- **轻量无依赖**：无需依赖任何其他模块

## 📦 安装

```bash
npm install general-form-storage
# 或
yarn add general-form-storage
```

## 🚀 快速开始

> 注：以下例子中仅是在 Vue3 环境下的使用教程，实际可脱离 Vue 环境

```javascript
import { ref } from "vue";
import FormStorage from "general-form-storage";

const formData = ref({
  username: "",
  email: "",
  preferences: {},
});

// 创建 FormStorage 实例
const formStorage = new FormStorage("userForm", formData);

// 初始化
formStorage.init();

// 在组件中使用
watch(
  formData,
  () => {
    formStorage.debouncedSaveData();
  },
  { deep: true }
);
```

## 📚 API 文档

### `FormStorage` 类

#### 构造函数

```ts
new FormStorage(formId: string, formData: Ref<object>)
```

- `formId`: 表单唯一标识符
- `formData`: Vue 3 的 ref 响应式对象

#### 方法

| 方法名                   | 参数               | 返回值 | 描述                             |
| :----------------------- | :----------------- | :----- | :------------------------------- |
| `init()`                 | -                  | void   | 初始化，从 localStorage 加载数据 |
| `saveData()`             | -                  | void   | 立即保存数据                     |
| `debouncedSaveData()`    | -                  | void   | 防抖保存（延迟 3000ms）          |
| `loadData()`             | -                  | void   | 从 localStorage 加载数据         |
| `clearData()`            | -                  | void   | 清除当前表单数据                 |
| `syncData(data: object)` | data: 要同步的数据 | void   | 手动同步数据                     |
| `static clearAll()`      | -                  | void   | 清除所有表单数据                 |

### 生命周期集成

FormStorage 会自动：

1. 在页面隐藏时保存数据
2. 在页面关闭前保存数据
3. 在跨标签页修改时同步数据

## 🌟 高级用法

### 自定义防抖时间

```javascript
// 在构造函数后覆盖默认防抖函数
formStorage.debouncedSaveData = formStorage.debounce(
  formStorage.saveData,
  5000
);
```

### 路由切换时保存

```javascript
const router = useRouter();

router.beforeEach((to, from) => {
  formStorage.saveData();
  return true;
});
```

## ⚠️ 注意事项

1. 每个表单应有唯一的 formId
2. 数据大小受 localStorage 限制（通常 5MB）
3. 不支持 IE 浏览器（依赖 BroadcastChannel）

## 🤝 贡献

欢迎提交 issue 或 pull request。

## 📜 许可证

MIT © [empty_reason]