@ithinkdt/page 4.0.18 → 4.0.19

package/README.md

@@ -1 +1,546 @@
 # @ithinkdt/page
+
+## 许可证
+
+MIT
+
+## 安装
+
+```bash
+npm i @ithinkdt/page
+```
+
+> 需要您自行安装依赖 `vue@3` 与 `vue-router@4`。
+
+## 介绍
+
+`@ithinkdt/page` 提供 iThinkDT 页面开发的核心组合式 API，包括：
+
+- 数据源管理（远程分页/本地数据）
+- 前端分页
+- 表单管理（查询筛选、编辑表单、表单弹窗）
+- 表格列定义与自定义列
+- CRUD 操作（新增、编辑、查看、删除）
+- 描述详情展示
+- 模态框（对话框/抽屉）
+- 表单校验规则
+
+## 初始化
+
+### 注册插件
+
+```ts
+import { createApp } from 'vue'
+import pagePlugin from '@ithinkdt/page'
+
+const app = createApp(App)
+
+app.use(pagePlugin, {
+    i18n,
+    getConfirmRenderer: () => renderConfirm,
+    getModalRenderer: () => renderModal,
+    getFormRenderer: () => renderForm,
+    getFormItemRenderer: {
+        text: () => renderTextInput,
+    },
+    getDescriptionRenderer: {
+        text: () => (value) => value,
+    },
+    getTableActionsRenderer: () => renderTableActions,
+    defaultPageSize: 20,
+    defaultFilterCached: true,
+})
+```
+
+## 组合式 API
+
+### `useDs` 数据源
+
+用于管理远程分页数据或本地数据列表，支持增删改操作：
+
+```ts
+import { useDs } from '@ithinkdt/page'
+import { userApi } from '@/api/user'
+
+const ds = useDs(
+    async ({ currentPage, pageSize, sortField, sortOrder }, filter) => {
+        const res = await userApi.page({ currentPage, pageSize, sortField, sortOrder, filter })
+        return res
+    },
+    { pagination: 'remote', defaultPageSize: 20 },
+)
+
+// 刷新数据
+ds.pull({ currentPage: 1, pageSize: 20 })
+
+// 本地插入一条
+ds.insert({ id: 'new', name: '张三' })
+
+// 本地更新一条
+ds.set('id-xxx', { name: '李四' })
+
+// 本地删除一条
+ds.remove('id-xxx')
+```
+
+### `useFilterHelper` 查询筛选表单
+
+```ts
+import { useFilterHelper } from '@ithinkdt/page'
+
+const { model, items, reset, validate } = useFilterHelper(
+    ({ it, model, validate }) => [
+        it('name', '用户名', 'text', { placeholder: '请输入用户名' }),
+        it('status', '状态', 'select', { selectProps: { options: statusOptions } }),
+    ],
+    { cached: true },
+)
+```
+
+### `useFormHelper` 表单管理
+
+```ts
+import { useFormHelper } from '@ithinkdt/page'
+
+const { model, items, validate } = useFormHelper(
+    ({ it, model, validate, group, reset }) => [
+        it('name', '名称', 'text', { required: true }),
+        it('email', '邮箱', 'text', { rule: email('请输入有效邮箱') }),
+        group(computed(() => model.country === 'China'), [
+            it('phone', '手机号', 'text'),
+        ]),
+    ],
+    {
+        initial: { name: '' },
+        onChange(name, value) {
+            console.log(`${name} changed:`, value)
+        },
+    },
+)
+
+// 校验
+const [valid] = await validate()
+if (valid) {
+    await submit(model)
+}
+```
+
+### `useFormModal` 表单弹窗
+
+将表单放入模态框中展示，常用于编辑场景：
+
+```ts
+import { useFormModal } from '@ithinkdt/page'
+
+const { open, close } = useFormModal({
+    title: '编辑用户',
+    type: 'dialog',
+    width: 600,
+    items: ({ it, model }) => [
+        it('name', '名称', 'text', { required: true }),
+    ],
+    onSubmit: async (data) => {
+        await userApi.save(data)
+    },
+    initial: { name: '' },
+})
+
+// 打开弹窗，传入初始数据
+await open({ id: '1', name: '张三' })
+```
+
+### `useSimpleCrud` CRUD 操作
+
+封装新增、编辑、查看、删除的标准流程：
+
+```ts
+import { useSimpleCrud } from '@ithinkdt/page'
+
+const { onAdd, onEdit, onView, onDel } = useSimpleCrud({
+    get: id => userApi.get(id),
+    save: data => userApi.save(data),
+    delete: id => userApi.delete(id),
+    // 增删改查用统一的表单
+    items: ({ it }) => [
+        it('name', '名称', 'text', { required: true }),
+        it('status', '状态', 'select'),
+        it('name', '名称', 'text'),
+        it('email', '邮箱', 'text'),
+    ],
+    // 差别较大的时候，可以分开定义
+    createItems: ({ it }) => [
+        it('name', '名称', 'text', { required: true }),
+    ],
+    editItems: ({ it, model }) => [
+        it('name', '名称', 'text', { required: true }),
+        it('status', '状态', 'select'),
+    ],
+    viewItems: ({ it }) => [
+        it('name', '名称', 'text'),
+        it('email', '邮箱', 'text'),
+    ],
+})
+
+// 新增
+await onAdd({ name: '张三' })
+
+// 编辑
+await onEdit('id-xxx')
+
+// 查看
+await onView('id-xxx')
+
+// 删除（带确认弹窗）
+await onDel('id-xxx')
+```
+
+### `useDeleteHelper` 删除确认
+
+```ts
+import { useDeleteHelper } from '@ithinkdt/page'
+
+const { onDel } = useDeleteHelper({
+    delete: ids => Array.isArray(ids) ? userApi.deleteBatch(ids) : userApi.delete(id),
+})
+
+// 单个删除
+await onDel('id-xxx')
+
+// 批量删除
+await onDel(['id-1', 'id-2'])
+
+// 自定义提示
+await onDel('id-xxx', '确认删除', '该操作不可撤销')
+```
+
+### `useTableHelper` 表格列定义
+
+```ts
+import { useTableHelper, calcActionWidth } from '@ithinkdt/page'
+
+const { columns, custom } = useTableHelper(
+    ({ col, cols, group }) => [
+        col('index', '#', (_, __, i) => i + 1, { width: 60 }),
+        col('name', '用户名', { width: 120 }),
+        col('email', '邮箱', 'text', { ellipsis: true }),
+        col('status', '状态', { width: 100, render: v => v ? '启用' : '禁用' }),
+        cols('操作', [
+            col('$edit', '', (_, record) => h('Button', { onClick: () => onEdit(record) }, '编辑')),
+            col('$delete', '', (_, record) => h('Button', { onClick: () => onDel(record) }, '删除')),
+        ], { fixed: 'right' }),
+    ],
+    {
+        index: i => i + (params.currentPage - 1) * params.pageSize,
+        selectable: canSelect && (record) => record.status === 'selectable',
+        customizable: true,
+        actions: [
+            { preset: 'edit', onClick: (record) => onEdit(record) },
+            { preset: 'delete', onClick: (record) => onDel(record) },
+        ],
+    },
+)
+```
+
+### `useDescriptionsHelper` 描述详情
+
+```ts
+import { useDescriptionsHelper } from '@ithinkdt/page'
+
+const { items, model, reset } = useDescriptionsHelper(
+    ({ it, group }) => [
+        it('name', '用户名', 'text'),
+        it('email', '邮箱'),
+        it('status', '状态', (value) => value ? '启用' : '禁用'),
+        group('contact', '联系方式', [
+            it('phone', '手机号', 'text'),
+            it('address', '地址', 'text'),
+        ]),
+    ],
+)
+
+// 设置数据
+reset({ name: '张三', email: 'zhangsan@example.com', phone: '13800000000' })
+```
+
+### `useModal` 模态框
+
+```ts
+import { useModal, useModalRef } from '@ithinkdt/page'
+
+const xxx = ref('123')
+const modal = useModal({
+    type: 'drawer',
+    title: '编辑',
+    width: 600,
+    content: () => <MyForm xxx={xxx.value} />,
+    onConfirm: async () => {
+        await submit()
+    },
+})
+
+// 打开
+await modal.open()
+
+// 关闭
+modal.close()
+```
+
+### `useDataPagination` 前端分页
+
+```ts
+import { useDataPagination } from '@ithinkdt/page'
+import { ref } from 'vue'
+
+const allData = ref([...])
+const { data, pagination, paginate } = useDataPagination(allData, { pageSize: 10 })
+
+// data 为当前页数据，pagination 为分页状态
+```
+
+## 校验规则
+
+`@ithinkdt/page/rules` 提供常用的表单校验规则：
+
+```ts
+import { required, min, max, email, phone, url, idNo, chinese, noChinese } from '@ithinkdt/page/rules'
+
+const rules = {
+    name: required('请输入名称'),
+    age: min(0, val => '年龄不能小于0'),
+    email: email('请输入有效邮箱'),
+    phone: phone('请输入有效手机号'),
+}
+```
+
+## API 参考
+
+### `useDs(fetch, options?)`
+
+| 参数 | 说明 |
+|------|------|
+| `fetch` | `(sortParams, filter) => Promise<{ total, records } \| T[]>`，数据获取函数 |
+| `options.pagination` | `'remote'` 远程分页，`false` 本地数据 |
+| `options.defaultPageSize` | 默认分页大小，默认 `10` |
+| `options.keyField` | 主键字段名，默认 `'key'` |
+| `options.defaultSortField` | 默认排序字段 |
+| `options.defaultSortOrder` | 默认排序方向，`'asc'` / `'desc'` |
+| `options.shallow` | 是否使用 `shallowReactive`，默认 `true` |
+| `options.immediate` | 是否立即执行 fetch，默认 `false` |
+| `options.resetOnFetch` | fetch 时是否先重置为空，默认 `false` |
+
+| 属性/方法 | 说明 |
+|-----------|------|
+| `state` | 响应式数据（远程分页模式下含 `total` 与 `records`） |
+| `loading` | 加载状态 |
+| `error` | 错误信息 |
+| `execute(...params)` | 执行 fetch 刷新数据 |
+| `get(key)` | 根据主键获取数据项 |
+| `insert(item, index?)` | 插入数据项 |
+| `set(key, item)` | 更新数据项 |
+| `remove(key)` | 删除数据项 |
+
+### `useFilterHelper(items, options?)`
+
+| 参数 | 说明 |
+|------|------|
+| `items` | `(helper) => FormItemOptions[]`，表单项定义函数 |
+| `options.initial` | 表单初始值 |
+| `options.rules` | 校验规则对象或函数 |
+| `options.onChange` | `(name, value) => void`，字段变更回调 |
+| `options.cached` | 是否缓存筛选表单，默认取插件 `defaultFilterCached` |
+| `options.cacheVersion` | 缓存版本号，默认 `1` |
+| `options.customizable` | 是否允许自定义筛选项显隐 |
+
+| 属性/方法 | 说明 |
+|-----------|------|
+| `model` | 响应式表单数据 |
+| `items` | 响应式表单项列表 |
+| `reset(initial?)` | 重置表单 |
+| `validate()` | 校验表单 |
+| `invalid` | 是否校验不通过 |
+| `validation` | 校验结果详情 |
+| `custom(modify)` | 自定义筛选项显隐/排序 |
+
+### `useFormHelper(items, options?)`
+
+| 参数 | 说明 |
+|------|------|
+| `items` | `(helper) => FormItemOptions[]`，表单项定义函数 |
+| `options.initial` | 表单初始值 |
+| `options.rules` | 校验规则对象或函数 |
+| `options.onChange` | `(name, value) => void`，字段变更回调 |
+
+| 属性/方法 | 说明 |
+|-----------|------|
+| `model` | 响应式表单数据 |
+| `items` | 响应式表单项列表 |
+| `reset(initial?)` | 重置表单（`overwrite=true` 覆盖，`reinit=true` 同时重建表单项） |
+| `reinit()` | 重新初始化表单项 |
+| `validate()` | 校验表单 |
+| `invalid` | 是否校验不通过 |
+| `validation` | 校验结果详情 |
+| `beforeSubmit(prop)` | 提交前校验（支持单字段或数组） |
+
+### `useFormModal(options)`
+
+| 参数 | 说明 |
+|------|------|
+| `options.title` | 弹窗标题 |
+| `options.type` | `'dialog'` / `'drawer'`，弹窗类型 |
+| `options.width` | 弹窗宽度 |
+| `options.items` | `(helper) => FormItemOptions[]`，表单项定义函数 |
+| `options.initial` | 表单初始值 |
+| `options.rules` | 校验规则 |
+| `options.onSubmit` | `(data) => Promise<void>`，提交回调 |
+| `options.loading` | 加载状态 |
+| `options.readonly` | 是否只读 |
+| `options.maskClosable` | 点击遮罩是否关闭，默认 `false` |
+| `options.closable` | 是否显示关闭按钮，默认 `true` |
+
+| 属性/方法 | 说明 |
+|-----------|------|
+| `open(initial?, title?)` | 打开表单弹窗 |
+| `close()` | 关闭弹窗 |
+
+### `useSimpleCrud(options)`
+
+| 参数 | 说明 |
+|------|------|
+| `options.get` | `(id) => Promise<Entity>`，获取详情 |
+| `options.post` / `save` | `(data) => Promise<Entity>`，新增 |
+| `options.put` | `(data) => Promise<Entity>`，编辑 |
+| `options.delete` | `(id) => Promise<void>`，删除 |
+| `options.createItems` | 新建表单的表单项定义函数 |
+| `options.editItems` | 编辑表单的表单项定义函数 |
+| `options.viewItems` | 查看表单的表单项定义函数 |
+| `options.items` / `formItems` | 新建和编辑共用的表单项定义函数 |
+| `options.width` | 弹窗宽度，可按 type 返回不同宽度 |
+| `options.cols` | 表单列数，可按 type 返回不同列数 |
+| `options.modalType` | `'dialog'` / `'drawer'`，可按 type 返回不同类型 |
+| `options.deleteButtonText` | 删除按钮文案 |
+
+| 方法 | 说明 |
+|------|------|
+| `onAdd(initial?, title?)` | 新增 |
+| `onEdit(dataOrKey, title?)` | 编辑 |
+| `onView(dataOrKey, title?)` | 查看 |
+| `onDel(keyOrKeys, title?, tip?)` | 删除 |
+
+### `useDeleteHelper(options)`
+
+| 参数 | 说明 |
+|------|------|
+| `options.delete` | `(ids) => Promise<void>`，删除请求函数 |
+| `options.keyField` | 主键字段名，默认使用插件注入的 `keyField` |
+| `options.deleteButtonText` | 删除按钮文案 |
+| `options.renderDelete` | 自定义删除确认内容渲染函数 |
+
+| 方法 | 说明 |
+|------|------|
+| `onDel(keyOrKeys, title?, tip?)` | 删除（带确认弹窗） |
+
+### `useTableHelper(columns, options?)`
+
+| 参数 | 说明 |
+|------|------|
+| `columns` | `(helper) => TableColumnOptions[]`，列定义函数 |
+| `options.index` | 是否显示序号列或自定义序号渲染函数 `(i, record) => VNodeChild` |
+| `options.indexTitle` | 序号列标题，默认 `'#'` |
+| `options.selectable` | 是否可选择或自定义可选择判断函数 `(record) => boolean` |
+| `options.selectType` | `'multiple'` / `'single'`，选择类型 |
+| `options.actions` | 操作按钮列表，内置预设 `{ preset: 'edit' \| 'view' \| 'delete' }` |
+| `options.actionTitle` | 操作列标题，默认 `'操作'` |
+| `options.actionWidth` | 操作列宽度，字符串或根据文案计算宽度函数 |
+| `options.actionHidden` | 是否隐藏操作列 |
+| `options.customizable` | 是否允许自定义列显隐/固定/宽度/排序 |
+| `options.expandable` | 是否可展开行或自定义判断函数 `(record) => boolean` |
+| `options.renderExpand` | `(record, i) => VNodeChild`，展开行渲染函数 |
+
+| 属性/方法 | 说明 |
+|-----------|------|
+| `columns` | 响应式列定义 |
+| `custom(modify)` | 自定义列显隐/固定/宽度/排序；传 `true` 重置为默认 |
+| `dataMode` | 数据模式（`all` / `selection`） |
+| `reinit()` | 重新初始化列定义 |
+
+### `useDescriptionsHelper(items)`
+
+| 参数 | 说明 |
+|------|------|
+| `items` | `(helper) => DescriptionItem[]`，描述项定义函数 |
+
+| 属性/方法 | 说明 |
+|-----------|------|
+| `items` | 响应式描述项列表 |
+| `model` | 响应式数据 |
+| `reset(model?, reinit?)` | 重置数据（`reinit=true` 同时重建描述项） |
+| `reinit()` | 重新初始化描述项 |
+
+### `useModal(options)`
+
+| 参数 | 说明 |
+|------|------|
+| `options.type` | `'dialog'` / `'drawer'`，类型 |
+| `options.title` | 标题 |
+| `options.content` | 内容 |
+| `options.width` | 宽度 |
+| `options.height` | 高度 |
+| `options.confirmText` | 确认按钮文案 |
+| `options.cancelText` | 取消按钮文案 |
+| `options.confirmLoading` | 确认按钮加载状态 |
+| `options.cancelLoading` | 取消按钮加载状态 |
+| `options.onConfirm` | `() => Promise<boolean \| void>`，确认回调，返回 `false` 阻止关闭 |
+| `options.onCancel` | `() => Promise<boolean \| void>`，取消回调 |
+| `options.onClose` | `() => Promise<boolean \| void>`，关闭回调 |
+| `options.closable` | 是否显示关闭按钮，默认 `true` |
+| `options.maskClosable` | 点击遮罩是否关闭，默认 `false` |
+| `options.footer` | 自定义底部内容，`null` 隐藏底部 |
+
+| 方法 | 说明 |
+|------|------|
+| `open(title?)` | 打开模态框 |
+| `close()` | 关闭模态框 |
+
+### `useModalRef()`
+
+| 属性/方法 | 说明 |
+|-----------|------|
+| `inModal` | 是否在模态框上下文内 |
+| `visible` | 模态框可见状态 |
+| `close()` | 关闭模态框 |
+| `setTitle(title)` | 设置模态框标题 |
+
+### `useDataPagination(data, options?)`
+
+| 参数 | 说明 |
+|------|------|
+| `data` | `MaybeRef<T[]>`，原始数据列表 |
+| `options.pageSize` | 每页条数，默认取插件 `defaultPageSize` |
+| `options.currentPage` | 初始页码，默认 `1` |
+| `options.updateOnChange` | 数据变化时是否重置到第一页，默认 `true` |
+
+| 属性/方法 | 说明 |
+|-----------|------|
+| `data` | 当前页数据 |
+| `pagination` | 分页状态（`pageSize`, `currentPage`） |
+| `paginate(params)` | 切换分页 |
+
+### 校验规则（`@ithinkdt/page/rules`）
+
+| 方法 | 说明 |
+|------|------|
+| `required(message, options?)` | 必填校验，`options.required` 控制是否必填，`options.trigger` 触发时机 |
+| `min(min, message, options?)` | 最小值/最小长度，`min` 为最小阈值 |
+| `max(max, message, options?)` | 最大值/最大长度，`max` 为最大阈值 |
+| `minmax(min, max, message, options?)` | 同时校验最小值/最大长度与最大值/最大长度 |
+| `email(message, options?)` | 邮箱格式 |
+| `phone(message, options?)` | 手机号格式（`1` 开头 11 位数字） |
+| `url(message, options?)` | URL 格式 |
+| `idNo(message, options?)` | 身份证格式 |
+| `plateNo(message, options?)` | 车牌号格式 |
+| `chinese(message, options?)` | 纯中文 |
+| `noChinese(message, options?)` | 不含中文 |
+| `pattern(pattern, message, options?)` | 自定义正则，`pattern` 为 `RegExp` 或正则字符串 |
+| `isRequiredRule(rule)` | 判断是否为 `required` 规则 |
+
+> `message` 参数为 `(value, params) => string`，`options.trigger` 默认 `'blur'`（`required` 默认 `['input', 'blur', 'change']`）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ithinkdt/page",
-  "version": "4.0.18",
+  "version": "4.0.19",
   "type": "module",
   "license": "MIT",
   "description": "iThinkDT Page",
@@ -39,19 +39,19 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@vueuse/core": "^14.2.1",
-    "nanoid": "^5.1.7",
-    "@ithinkdt/common": "^4.0.7"
+    "@vueuse/core": "^14.3.0",
+    "nanoid": "^5.1.11",
+    "@ithinkdt/common": "^4.0.8"
   },
   "peerDependencies": {
     "vue": ">=3.5",
     "vue-router": ">=4.5"
   },
   "devDependencies": {
-    "typescript": "~6.0.2",
-    "vite": "^8.0.8",
-    "vue": "^3.5.32",
-    "vue-router": "^5.0.4"
+    "typescript": "~6.0.3",
+    "vite": "^8.0.10",
+    "vue": "^3.5.34",
+    "vue-router": "^5.0.6"
   },
   "scripts": {
     "release": "pnpm publish --no-git-checks"

package/src/form.d.ts

@@ -124,7 +124,7 @@ export interface FormItemHelper<Model extends {}> extends FromValidation<Model>
     ): FormItemOptions<Partial<Model>>
     group(
         this: void,
-        visible: MaybeRef<boolean>,
+        visibility: MaybeRef<boolean>,
         items: (FormItemOptions<Partial<Model>> | Falsely)[]
     ): FormItemOptions<Partial<Model>>[]
 }
@@ -162,7 +162,25 @@ export declare function useFormHelper<Model extends {}>(
     options?: FormHelperOptions<Model>,
 ): FormHelper<Model>
 
+export interface FilterHelperOptions<Model extends {}> extends FormHelperOptions<Model> {
+    /**
+     * 自定义
+     */
+    customizable?: boolean | string | undefined
+    /**
+     * 缓存表单
+     */
+    cached?: boolean | string | undefined
+    /**
+     * 缓存版本，默认 1
+     */
+    cacheVersion?: number | undefined
+}
+
 export interface FilterHelper<Model extends {}> extends FormHelper<Model> {
+    /**
+     * 自定义表单项
+     */
     custom(this: void, modify: {
         key: string
         hidden?: boolean | undefined
@@ -173,20 +191,7 @@ export interface FilterHelper<Model extends {}> extends FormHelper<Model> {
 
 export declare function useFilterHelper<Model extends {}>(
     items: ((helper: FormItemHelper<Model>) => (FormItemOptions<Partial<Model>> | Falsely)[]),
-    options?: FormHelperOptions<Model> & {
-        /**
-         * 缓存表单
-         */
-        cached?: boolean | string | undefined
-        /**
-         * 缓存版本，默认 1
-         */
-        cacheVersion?: number
-        /**
-         * 自定义
-         */
-        customizable?: boolean | string | undefined
-    },
+    options?: FilterHelperOptions<Model>,
 ): FilterHelper<Model>
 
 export interface FormRenderExtraOptions {

package/src/form.js

@@ -1,4 +1,4 @@
-import { toReactive, useSessionStorage, useStorageAsync } from '@vueuse/core'
+import { StorageSerializers, toReactive, useStorage, useStorageAsync } from '@vueuse/core'
 import { nanoid } from 'nanoid'
 import { computed, h, hasInjectionContext, inject, reactive, readonly, ref, shallowReactive, shallowRef, toRaw, unref } from 'vue'
 import { useRoute } from 'vue-router'
@@ -93,11 +93,11 @@ export function useFormHelper(items, { initial: initial0, rules, onChange, inFil
         return { ...options, name, render: render0, label, __key: nanoid(), beforeSubmit }
     }
 
-    const group = (visible, items) => {
+    const group = (visibility, items) => {
         return items.map((item) => {
             return {
                 ...item,
-                hidden: computed(() => unref(visible) == false || unref(item.hidden)),
+                hidden: computed(() => unref(visibility) == false || unref(item.hidden)),
             }
         })
     }
@@ -320,7 +320,7 @@ export function useFormHelper(items, { initial: initial0, rules, onChange, inFil
 }
 
 export function useFilterHelper(items, { customizable = false, cached, cacheVersion = 1, ...options } = {}) {
-    const { defaultFilterCached, customizationStorage = localStorage } = (hasInjectionContext() ? inject(PAGE_INJECTION, pageInjection) : pageInjection) ?? {}
+    const { defaultFilterCached, customizationStorage = localStorage, cacheStorage = sessionStorage } = (hasInjectionContext() ? inject(PAGE_INJECTION, pageInjection) : pageInjection) ?? {}
     let cacheFn
     const returns = useFormHelper(items, {
         ...options,
@@ -367,7 +367,10 @@ export function useFilterHelper(items, { customizable = false, cached, cacheVers
         customizable = 'filter-form-customization#' + useRoute().name
     }
     const customs = customizable
-        ? useStorageAsync(customizable, getDefaultCustom, customizationStorage, { onReady: reinit })
+        ? useStorageAsync(customizable, getDefaultCustom, customizationStorage, {
+                onReady: reinit,
+                serializer: StorageSerializers.object,
+            })
         : ref(getDefaultCustom())
 
     if (!customizable) {
@@ -382,10 +385,13 @@ export function useFilterHelper(items, { customizable = false, cached, cacheVers
     if (cached) {
         if (cacheVersion > 1) {
             for (let i = 1; i < cacheVersion; i++) {
-                sessionStorage.removeItem(cached + '-v' + i)
+                cacheStorage.removeItem(cached + '-v' + i)
             }
         }
-        const cachedModel = useSessionStorage(cached + '-v' + cacheVersion, {})
+        const cachedModel = useStorage(cached + '-v' + cacheVersion, { ...returns.model }, cacheStorage, {
+            mergeDefaults: true,
+            serializer: StorageSerializers.object,
+        })
         cachedModel.value && returns.reset(cachedModel.value)
 
         cacheFn = (model) => {

package/src/plugin.d.ts

@@ -1,4 +1,4 @@
-import { StorageLikeAsync } from '@vueuse/core'
+import { StorageLike, StorageLikeAsync } from '@vueuse/core'
 import { DefineComponent, InjectionKey, VNodeChild } from 'vue'
 
 import { I18nComposable } from '@ithinkdt/common/i18n'
@@ -56,6 +56,11 @@ export interface PageOptions extends PresetDataSourceOptions {
      * 自定义数据存储实现，默认使用 localStorage
      */
     customizationStorage?: StorageLikeAsync
+
+    /**
+     * 自定义缓存实现，默认使用 sessionStorage
+     */
+    cacheStorage?: StorageLike
 }
 
 /**

package/src/table.d.ts

@@ -118,7 +118,7 @@ export interface TableColumnHelper<Model extends {}> {
     ): TableColumnOptions<Model>
     group(
         this: void,
-        hidden: MaybeRef<boolean>,
+        visibility: MaybeRef<boolean>,
         columns: (TableColumnOptions<Model> | Falsely)[]
     ): TableColumnOptions<Model>[]
 }

package/src/table.js

@@ -1,4 +1,4 @@
-import { useStorageAsync } from '@vueuse/core'
+import { StorageSerializers, useStorageAsync } from '@vueuse/core'
 import { nanoid } from 'nanoid'
 import { computed, hasInjectionContext, inject, reactive, ref, shallowReactive, shallowRef, toValue, unref } from 'vue'
 import { useRoute } from 'vue-router'
@@ -112,11 +112,11 @@ export function useTableHelper(columns, { customizable, actions, actionWidth, ac
             ...options,
         }
     }
-    const group = (visible, cols) => {
+    const group = (visibility, cols) => {
         return cols.map((col) => {
             return {
                 ...col,
-                hidden: computed(() => unref(visible) === false || unref(col.hidden)),
+                hidden: computed(() => unref(visibility) === false || unref(col.hidden)),
             }
         })
     }
@@ -278,7 +278,10 @@ export function useTableHelper(columns, { customizable, actions, actionWidth, ac
         customizable = 'table-column-customization#' + useRoute().name
     }
     const customs = customizable
-        ? useStorageAsync(customizable, getDefaultCustom, customizationStorage, { onReady: reinit })
+        ? useStorageAsync(customizable, getDefaultCustom, customizationStorage, {
+                onReady: reinit,
+                serializer: StorageSerializers.object,
+            })
         : ref(getDefaultCustom())
 
     if (!customizable) {