失忆
4 months ago
committed by
GitHub
GitHub
222 changed files with 8522 additions and 5049 deletions
@ -0,0 +1,85 @@ |
|||
import { faker } from '@faker-js/faker'; |
|||
import { eventHandler, getQuery } from 'h3'; |
|||
import { verifyAccessToken } from '~/utils/jwt-utils'; |
|||
import { unAuthorizedResponse, usePageResponseSuccess } from '~/utils/response'; |
|||
|
|||
const formatterCN = new Intl.DateTimeFormat('zh-CN', { |
|||
timeZone: 'Asia/Shanghai', |
|||
year: 'numeric', |
|||
month: '2-digit', |
|||
day: '2-digit', |
|||
hour: '2-digit', |
|||
minute: '2-digit', |
|||
second: '2-digit', |
|||
}); |
|||
|
|||
function generateMockDataList(count: number) { |
|||
const dataList = []; |
|||
|
|||
for (let i = 0; i < count; i++) { |
|||
const dataItem: Record<string, any> = { |
|||
id: faker.string.uuid(), |
|||
name: faker.commerce.product(), |
|||
status: faker.helpers.arrayElement([0, 1]), |
|||
createTime: formatterCN.format( |
|||
faker.date.between({ from: '2022-01-01', to: '2025-01-01' }), |
|||
), |
|||
deptId: faker.string.uuid(), |
|||
remark: faker.lorem.sentence(), |
|||
}; |
|||
|
|||
dataList.push(dataItem); |
|||
} |
|||
|
|||
return dataList; |
|||
} |
|||
|
|||
const mockData = generateMockDataList(100); |
|||
|
|||
export default eventHandler(async (event) => { |
|||
const userinfo = verifyAccessToken(event); |
|||
if (!userinfo) { |
|||
return unAuthorizedResponse(event); |
|||
} |
|||
|
|||
const { |
|||
page = 1, |
|||
pageSize = 20, |
|||
name, |
|||
id, |
|||
remark, |
|||
startTime, |
|||
endTime, |
|||
deptId, |
|||
status, |
|||
} = getQuery(event); |
|||
let listData = structuredClone(mockData); |
|||
if (name) { |
|||
listData = listData.filter((item) => |
|||
item.name.toLowerCase().includes(String(name).toLowerCase()), |
|||
); |
|||
} |
|||
if (id) { |
|||
listData = listData.filter((item) => |
|||
item.id.toLowerCase().includes(String(id).toLowerCase()), |
|||
); |
|||
} |
|||
if (remark) { |
|||
listData = listData.filter((item) => |
|||
item.remark?.toLowerCase()?.includes(String(remark).toLowerCase()), |
|||
); |
|||
} |
|||
if (startTime) { |
|||
listData = listData.filter((item) => item.createTime >= startTime); |
|||
} |
|||
if (endTime) { |
|||
listData = listData.filter((item) => item.createTime <= endTime); |
|||
} |
|||
if (['0', '1'].includes(status as string)) { |
|||
listData = listData.filter((item) => item.status === Number(status)); |
|||
} |
|||
if (deptId) { |
|||
listData = listData.filter((item) => item.deptId === deptId); |
|||
} |
|||
return usePageResponseSuccess(page as string, pageSize as string, listData); |
|||
}); |
|||
@ -0,0 +1,2 @@ |
|||
import { register } from 'node:module'; |
|||
register('./dayjs-resolve-hook.mjs', import.meta.url); |
|||
@ -0,0 +1,10 @@ |
|||
const DAYJS_SUBPATH_RE = /^dayjs\/(plugin|locale)\/([^./]+)$/; |
|||
|
|||
/** @type {import('node:module').ResolveHook} */ |
|||
export async function resolve(specifier, context, nextResolve) { |
|||
const match = specifier.match(DAYJS_SUBPATH_RE); |
|||
if (match) { |
|||
return nextResolve(`${specifier}.js`, context); |
|||
} |
|||
return nextResolve(specifier, context); |
|||
} |
|||
@ -0,0 +1,172 @@ |
|||
--- |
|||
outline: deep |
|||
--- |
|||
|
|||
# Vben Cropper 图片裁剪 |
|||
|
|||
`VCropper` 是一个纯原生实现的图片裁剪组件，支持自由比例和固定比例裁剪，可通过方法调用获取裁剪后的图片。 |
|||
|
|||
> 如果文档内没有参数说明，可以尝试在在线示例内寻找 |
|||
|
|||
::: info 写在前面 |
|||
|
|||
如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。 |
|||
|
|||
::: |
|||
|
|||
## 基础用法 |
|||
|
|||
最基本的图片裁剪，支持自由比例调整。 |
|||
|
|||
<DemoPreview dir="demos/vben-cropper/basic" /> |
|||
|
|||
## 固定比例裁剪 |
|||
|
|||
通过 `aspectRatio` 属性设置裁剪比例，格式为 `"宽:高"`，如 `"1:1"`、`"16:9"`、`"3:4"` 等。 |
|||
|
|||
<DemoPreview dir="demos/vben-cropper/aspect-ratio" /> |
|||
|
|||
## API |
|||
|
|||
### Props |
|||
|
|||
| 属性名 | 描述 | 类型 | 默认值 | |
|||
| ------------- | ------------------------------------- | -------- | ------ | |
|||
| `img` | 图片地址（必填） | `string` | - | |
|||
| `width` | 容器宽度 | `number` | `500` | |
|||
| `height` | 容器高度 | `number` | `400` | |
|||
| `aspectRatio` | 裁剪比例，格式如 `"1:1"`、`"16:9"` 等 | `string` | - | |
|||
|
|||
### Methods |
|||
|
|||
通过 `ref` 调用组件方法： |
|||
|
|||
```vue |
|||
<script setup lang="ts"> |
|||
import { ref } from 'vue'; |
|||
import { VCropper } from '@vben/common-ui'; |
|||
|
|||
const cropperRef = ref<InstanceType<typeof VCropper>>(); |
|||
|
|||
const handleCrop = async () => { |
|||
const result = await cropperRef.value?.getCropImage(); |
|||
// result 为 Blob 或 base64 字符串 |
|||
}; |
|||
</script> |
|||
``` |
|||
|
|||
#### getCropImage |
|||
|
|||
裁剪并获取图片。 |
|||
|
|||
```ts |
|||
interface GetCropImageOptions { |
|||
/** 输出图片格式 */ |
|||
format?: 'image/jpeg' | 'image/png'; |
|||
/** 压缩质量（0-1），仅对 jpeg 格式有效 */ |
|||
quality?: number; |
|||
/** 输出类型 */ |
|||
outputType?: 'base64' | 'blob'; |
|||
/** 目标宽度（可选，不传则为原始裁剪宽度） */ |
|||
targetWidth?: number; |
|||
/** 目标高度（可选，不传则为原始裁剪高度） */ |
|||
targetHeight?: number; |
|||
} |
|||
|
|||
getCropImage( |
|||
format?: 'image/jpeg' | 'image/png', |
|||
quality?: number, |
|||
outputType?: 'base64' | 'blob', |
|||
targetWidth?: number, |
|||
targetHeight?: number, |
|||
): Promise<Blob | string | undefined> |
|||
``` |
|||
|
|||
**参数说明：** |
|||
|
|||
| 参数 | 类型 | 默认值 | 描述 | |
|||
| --- | --- | --- | --- | |
|||
| `format` | `'image/jpeg' \| 'image/png'` | `'image/png'` | 输出图片格式 | |
|||
| `quality` | `number` | `0.92` | 压缩质量（0-1），仅 jpeg 有效 | |
|||
| `outputType` | `'base64' \| 'blob'` | `'blob'` | 输出类型，base64 字符串或 Blob 对象 | |
|||
| `targetWidth` | `number` | - | 目标宽度，不传则使用原始裁剪宽度 | |
|||
| `targetHeight` | `number` | - | 目标高度，不传则使用原始裁剪高度 | |
|||
|
|||
## 功能特性 |
|||
|
|||
### 裁剪操作 |
|||
|
|||
- **拖拽移动** - 拖拽裁剪框中心区域移动裁剪位置 |
|||
- **边角调整** - 拖拽四角调整裁剪框大小 |
|||
- **边缘调整** - 拖拽四边中点调整单边 |
|||
|
|||
### 比例控制 |
|||
|
|||
- **自由比例** - 不设置 `aspectRatio` 时，可自由调整任意比例 |
|||
- **固定比例** - 设置 `aspectRatio` 后，裁剪框始终保持设定比例 |
|||
|
|||
### 高清屏适配 |
|||
|
|||
组件自动适配 Retina 等高清屏幕，保证输出图片清晰无模糊。 |
|||
|
|||
### 图片适配 |
|||
|
|||
- 图片自动等比缩放以完整显示在容器内 |
|||
- 支持本地图片和网络图片 |
|||
- 网络图片需目标服务端支持 CORS 才能导出裁剪结果 |
|||
|
|||
## 使用示例 |
|||
|
|||
```vue |
|||
<script setup lang="ts"> |
|||
import { ref } from 'vue'; |
|||
import { VCropper } from '@vben/common-ui'; |
|||
|
|||
const cropperRef = ref<InstanceType<typeof VCropper>>(); |
|||
const imageUrl = ref('https://example.com/image.jpg'); |
|||
const croppedImage = ref(''); |
|||
|
|||
// 获取裁剪后的 Blob 对象 |
|||
const handleCropBlob = async () => { |
|||
const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob'); |
|||
if (blob instanceof Blob) { |
|||
// 上传到服务器或创建预览URL |
|||
const url = URL.createObjectURL(blob); |
|||
croppedImage.value = url; |
|||
} |
|||
}; |
|||
|
|||
// 获取裁剪后的 base64 字符串 |
|||
const handleCropBase64 = async () => { |
|||
const base64 = await cropperRef.value?.getCropImage('image/png', 1, 'base64'); |
|||
if (typeof base64 === 'string') { |
|||
croppedImage.value = base64; |
|||
} |
|||
}; |
|||
|
|||
// 导出指定尺寸 |
|||
const handleCropWithSize = async () => { |
|||
const blob = await cropperRef.value?.getCropImage( |
|||
'image/jpeg', |
|||
0.9, |
|||
'blob', |
|||
200, // 目标宽度 |
|||
200, // 目标高度 |
|||
); |
|||
}; |
|||
</script> |
|||
|
|||
<template> |
|||
<div> |
|||
<VCropper |
|||
ref="cropperRef" |
|||
:img="imageUrl" |
|||
:width="500" |
|||
:height="400" |
|||
aspect-ratio="1:1" |
|||
/> |
|||
<button @click="handleCropBlob">裁剪</button> |
|||
<img v-if="croppedImage" :src="croppedImage" /> |
|||
</div> |
|||
</template> |
|||
``` |
|||
@ -0,0 +1,199 @@ |
|||
--- |
|||
outline: deep |
|||
--- |
|||
|
|||
# Vben Tiptap 富文本编辑器 |
|||
|
|||
基于 [Tiptap](https://tiptap.dev/) 构建的富文本编辑器组件，支持丰富的文本格式化、图片插入、图片上传等功能。 |
|||
|
|||
> 如果文档内没有参数说明，可以尝试在在线示例内寻找 |
|||
|
|||
::: info 写在前面 |
|||
|
|||
如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。 |
|||
|
|||
::: |
|||
|
|||
## 基础用法 |
|||
|
|||
<DemoPreview dir="demos/vben-tiptap/basic" /> |
|||
|
|||
## 组件列表 |
|||
|
|||
### VbenTiptap |
|||
|
|||
富文本编辑器主组件。 |
|||
|
|||
### VbenTiptapPreview |
|||
|
|||
富文本内容预览组件，用于只读展示编辑器内容。 |
|||
|
|||
## API |
|||
|
|||
### Props |
|||
|
|||
| 属性名 | 说明 | 类型 | 默认值 | |
|||
| --- | --- | --- | --- | |
|||
| `modelValue` (v-model) | 编辑器内容（HTML字符串） | `string` | `''` | |
|||
| `editable` | 是否可编辑 | `boolean` | `true` | |
|||
| `toolbar` | 是否显示工具栏 | `boolean` | `true` | |
|||
| `previewable` | 是否显示预览按钮 | `boolean` | `true` | |
|||
| `placeholder` | 占位提示文本 | `string` | - | |
|||
| `minHeight` | 最小高度 | `number \| string` | `240` | |
|||
| `maxHeight` | 最大高度 | `number \| string` | `400` | |
|||
| `extensions` | 自定义 Tiptap 扩展配置 | `Extensions` | - | |
|||
| `imageUpload` | 图片上传配置 | `ImageUploadOptions` | - | |
|||
|
|||
### Events |
|||
|
|||
| 事件名 | 说明 | 参数类型 | |
|||
| -------- | -------------- | ----------------------- | |
|||
| `change` | 内容变化时触发 | `VbenTiptapChangeEvent` | |
|||
|
|||
#### VbenTiptapChangeEvent |
|||
|
|||
```ts |
|||
interface VbenTiptapChangeEvent { |
|||
html: string; // HTML 内容 |
|||
json: JSONContent; // JSON 结构内容 |
|||
text: string; // 纯文本内容 |
|||
} |
|||
``` |
|||
|
|||
### ImageUploadOptions |
|||
|
|||
图片上传配置项： |
|||
|
|||
```ts |
|||
interface ImageUploadOptions { |
|||
/** 允许的文件类型，默认 'image/*' */ |
|||
accept?: string; |
|||
/** 最大文件大小(字节)，默认 5MB */ |
|||
maxSize?: number; |
|||
/** 上传失败回调，未提供时使用 alert 弹窗提示 */ |
|||
onUploadError?: (error: unknown) => void; |
|||
/** 上传函数，返回图片 URL */ |
|||
upload: ( |
|||
file: File, |
|||
onProgress?: (percent: number) => void, |
|||
) => Promise<string>; |
|||
} |
|||
``` |
|||
|
|||
### VbenTiptapPreview Props |
|||
|
|||
| 属性名 | 说明 | 类型 | 默认值 | |
|||
| ----------- | ------------------ | ------------------ | ------ | |
|||
| `content` | 要预览的 HTML 内容 | `string` | `''` | |
|||
| `minHeight` | 最小高度 | `number \| string` | `160` | |
|||
| `class` | 自定义类名 | `any` | - | |
|||
|
|||
## 工具栏功能 |
|||
|
|||
编辑器工具栏提供以下功能： |
|||
|
|||
### 格式化 |
|||
|
|||
- **撤销/重做** - 撤销或重做编辑操作 |
|||
- **清除格式** - 清除选中文本的所有格式 |
|||
- **粗体** - 加粗文本 |
|||
- **斜体** - 斜体文本 |
|||
- **下划线** - 下划线文本 |
|||
- **删除线** - 删除线文本 |
|||
- **行内代码** - 行内代码标记 |
|||
|
|||
### 结构 |
|||
|
|||
- **标题** - 段落、H1-H4 标题切换 |
|||
- **有序列表** - 有序编号列表 |
|||
- **无序列表** - 无序符号列表 |
|||
- **引用块** - 引用块样式 |
|||
- **代码块** - 多行代码块 |
|||
|
|||
### 链接与图片 |
|||
|
|||
- **插入链接** - 插入或编辑超链接 |
|||
- **移除链接** - 移除选中文本的链接 |
|||
- **插入图片** - 通过 URL 插入图片 |
|||
|
|||
### 样式 |
|||
|
|||
- **文字颜色** - 设置文字颜色（预设色板） |
|||
- **背景颜色** - 设置文字背景高亮颜色 |
|||
|
|||
### 对齐 |
|||
|
|||
- **左对齐** - 文本左对齐 |
|||
- **居中对齐** - 文本居中对齐 |
|||
- **右对齐** - 文本右对齐 |
|||
|
|||
### 其他 |
|||
|
|||
- **预览** - 在弹窗中预览编辑内容 |
|||
|
|||
## 图片上传 |
|||
|
|||
<DemoPreview dir="demos/vben-tiptap/image-upload" /> |
|||
|
|||
当配置 `imageUpload` 时，工具栏的图片按钮会变为下拉菜单，包含「本地上传」和「URL 插入」两个选项。 |
|||
|
|||
### 上传方式 |
|||
|
|||
支持三种图片上传方式： |
|||
|
|||
1. **文件选择** - 点击工具栏本地上传按钮 |
|||
2. **拖拽上传** - 直接拖拽图片到编辑器区域 |
|||
3. **粘贴上传** - 粘贴图片到编辑器 |
|||
|
|||
### 上传进度显示 |
|||
|
|||
上传过程中会显示： |
|||
|
|||
- **加载指示器** - 旋转动画指示上传进行中 |
|||
- **进度条** - 当上传函数提供 `onProgress` 回调时，显示进度条 |
|||
|
|||
### 文件校验 |
|||
|
|||
- `accept` - 指定允许的文件类型（MIME类型） |
|||
- `maxSize` - 最大文件大小限制（字节） |
|||
- 校验失败时会触发 `onUploadError` 回调或默认 alert 提示 |
|||
|
|||
::: warning 注意事项 |
|||
|
|||
- 仅支持单张图片上传，多图拖拽/粘贴时会提示并仅处理第一张 |
|||
- 上传中不要保存编辑器内容（`getHTML()`），因为此时图片 URL 为临时 blob URL |
|||
- 自定义 `extensions` 时，图片上传功能将不显示（因为可能缺少 uploadImage 命令） |
|||
|
|||
::: |
|||
|
|||
## 自定义扩展 |
|||
|
|||
通过 `extensions` 属性可以传入自定义的 Tiptap 扩展配置： |
|||
|
|||
```vue |
|||
<script setup lang="ts"> |
|||
import { VbenTiptap } from '@vben/plugins/tiptap'; |
|||
import StarterKit from '@tiptap/starter-kit'; |
|||
import Underline from '@tiptap/extension-underline'; |
|||
|
|||
const extensions = [ |
|||
StarterKit, |
|||
Underline, |
|||
// 其他扩展... |
|||
]; |
|||
</script> |
|||
|
|||
<template> |
|||
<VbenTiptap v-model="content" :extensions="extensions" /> |
|||
</template> |
|||
``` |
|||
|
|||
::: warning 自定义扩展注意事项 |
|||
|
|||
使用自定义 `extensions` 时： |
|||
|
|||
- 默认扩展配置将不会生效 |
|||
- 图片上传功能不可用（工具栏不显示上传选项） |
|||
- 需自行配置所需的编辑器功能 |
|||
|
|||
::: |
|||
@ -0,0 +1,102 @@ |
|||
<script lang="ts" setup> |
|||
import { onBeforeUnmount, ref } from 'vue'; |
|||
|
|||
import { VCropper } from '@vben/common-ui'; |
|||
|
|||
const cropperRef = ref<InstanceType<typeof VCropper>>(); |
|||
const aspectRatio = ref('1:1'); |
|||
const imageUrl = ref('https://picsum.photos/seed/cropper-ratio/800/600'); |
|||
const croppedImage = ref(''); |
|||
|
|||
const aspectOptions = [ |
|||
{ label: '1:1 (正方形)', value: '1:1' }, |
|||
{ label: '16:9 (宽屏)', value: '16:9' }, |
|||
{ label: '4:3 (标准)', value: '4:3' }, |
|||
{ label: '3:4 (竖版)', value: '3:4' }, |
|||
{ label: '3:2 (照片)', value: '3:2' }, |
|||
]; |
|||
|
|||
// 释放旧的 object URL 以避免内存泄漏 |
|||
const revokeCroppedImage = () => { |
|||
if (croppedImage.value?.startsWith('blob:')) { |
|||
URL.revokeObjectURL(croppedImage.value); |
|||
} |
|||
}; |
|||
|
|||
const handleCrop = async () => { |
|||
const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob'); |
|||
if (blob instanceof Blob) { |
|||
// 释放旧的 URL |
|||
revokeCroppedImage(); |
|||
croppedImage.value = URL.createObjectURL(blob); |
|||
} |
|||
}; |
|||
|
|||
const handleReset = () => { |
|||
// 释放 URL |
|||
revokeCroppedImage(); |
|||
croppedImage.value = ''; |
|||
imageUrl.value = `https://picsum.photos/seed/cropper-${Date.now()}/800/600`; |
|||
}; |
|||
|
|||
// 组件卸载时清理 |
|||
onBeforeUnmount(() => { |
|||
revokeCroppedImage(); |
|||
}); |
|||
</script> |
|||
|
|||
<template> |
|||
<div> |
|||
<div class="mb-4"> |
|||
<label class="text-sm text-gray-500 mr-2">选择比例:</label> |
|||
<select v-model="aspectRatio" class="px-3 py-1 border rounded text-sm"> |
|||
<option |
|||
v-for="option in aspectOptions" |
|||
:key="option.value" |
|||
:value="option.value" |
|||
> |
|||
{{ option.label }} |
|||
</option> |
|||
</select> |
|||
</div> |
|||
|
|||
<VCropper |
|||
ref="cropperRef" |
|||
:img="imageUrl" |
|||
:width="500" |
|||
:height="300" |
|||
:aspect-ratio="aspectRatio" |
|||
/> |
|||
|
|||
<div class="mt-4 flex gap-2"> |
|||
<button |
|||
class="px-4 py-2 bg-blue-500 rounded hover:bg-blue-600" |
|||
@click="handleCrop" |
|||
> |
|||
裁剪图片 |
|||
</button> |
|||
<button |
|||
class="px-4 py-2 bg-gray-500 rounded hover:bg-gray-600" |
|||
@click="handleReset" |
|||
> |
|||
重置 |
|||
</button> |
|||
</div> |
|||
|
|||
<div v-if="croppedImage" class="mt-4"> |
|||
<p class="text-sm text-gray-500 mb-2"> |
|||
裁剪结果 (比例: {{ aspectRatio }}): |
|||
</p> |
|||
<img :src="croppedImage" class="max-w-full rounded border" /> |
|||
</div> |
|||
|
|||
<div class="mt-4"> |
|||
<p class="text-sm text-gray-500">提示:</p> |
|||
<ul class="mt-2 text-xs text-gray-400 list-disc pl-4"> |
|||
<li>设置固定比例后，裁剪框始终维持该比例</li> |
|||
<li>切换比例会自动重新计算裁剪框大小</li> |
|||
<li>比例格式为 "宽:高"，如 "16:9"</li> |
|||
</ul> |
|||
</div> |
|||
</div> |
|||
</template> |
|||
@ -0,0 +1,70 @@ |
|||
<script lang="ts" setup> |
|||
import { onBeforeUnmount, ref } from 'vue'; |
|||
|
|||
import { VCropper } from '@vben/common-ui'; |
|||
|
|||
const cropperRef = ref<InstanceType<typeof VCropper>>(); |
|||
const imageUrl = ref('https://picsum.photos/seed/cropper-demo/800/600'); |
|||
const croppedImage = ref(''); |
|||
|
|||
// 释放旧的 object URL 以避免内存泄漏 |
|||
const revokeCroppedImage = () => { |
|||
if (croppedImage.value?.startsWith('blob:')) { |
|||
URL.revokeObjectURL(croppedImage.value); |
|||
} |
|||
}; |
|||
|
|||
const handleCrop = async () => { |
|||
const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob'); |
|||
if (blob instanceof Blob) { |
|||
// 释放旧的 URL |
|||
revokeCroppedImage(); |
|||
croppedImage.value = URL.createObjectURL(blob); |
|||
} |
|||
}; |
|||
|
|||
const handleReset = () => { |
|||
// 释放 URL |
|||
revokeCroppedImage(); |
|||
croppedImage.value = ''; |
|||
// 重新加载图片以重置裁剪框 |
|||
imageUrl.value = `https://picsum.photos/seed/cropper-${Date.now()}/800/600`; |
|||
}; |
|||
|
|||
// 组件卸载时清理 |
|||
onBeforeUnmount(() => { |
|||
revokeCroppedImage(); |
|||
}); |
|||
</script> |
|||
|
|||
<template> |
|||
<div> |
|||
<VCropper ref="cropperRef" :img="imageUrl" :width="500" :height="300" /> |
|||
<div class="mt-4 flex gap-2"> |
|||
<button |
|||
class="px-4 py-2 bg-blue-500 rounded hover:bg-blue-600" |
|||
@click="handleCrop" |
|||
> |
|||
裁剪图片 |
|||
</button> |
|||
<button |
|||
class="px-4 py-2 bg-gray-500 rounded hover:bg-gray-600" |
|||
@click="handleReset" |
|||
> |
|||
重置 |
|||
</button> |
|||
</div> |
|||
<div v-if="croppedImage" class="mt-4"> |
|||
<p class="text-sm text-gray-500 mb-2">裁剪结果:</p> |
|||
<img :src="croppedImage" class="max-w-full rounded border" /> |
|||
</div> |
|||
<div class="mt-4"> |
|||
<p class="text-sm text-gray-500">提示:</p> |
|||
<ul class="mt-2 text-xs text-gray-400 list-disc pl-4"> |
|||
<li>拖拽裁剪框中心区域可移动裁剪位置</li> |
|||
<li>拖拽四角或四边可调整裁剪框大小</li> |
|||
<li>默认为自由比例，可调整为任意比例</li> |
|||
</ul> |
|||
</div> |
|||
</div> |
|||
</template> |
|||
@ -0,0 +1,19 @@ |
|||
<script lang="ts" setup> |
|||
import { ref } from 'vue'; |
|||
|
|||
import { VbenTiptap } from '@vben/plugins/tiptap'; |
|||
|
|||
const content = ref('<p>开始编辑你的内容...</p>'); |
|||
</script> |
|||
|
|||
<template> |
|||
<div> |
|||
<VbenTiptap v-model="content" /> |
|||
<div class="mt-4"> |
|||
<p class="text-sm text-gray-500">当前内容:</p> |
|||
<pre class="mt-2 p-2 bg-gray-100 rounded text-xs overflow-auto max-h-40"> |
|||
{{ content }} |
|||
</pre> |
|||
</div> |
|||
</div> |
|||
</template> |
|||
@ -0,0 +1,45 @@ |
|||
<script lang="ts" setup> |
|||
import { ref } from 'vue'; |
|||
|
|||
import { type ImageUploadOptions, VbenTiptap } from '@vben/plugins/tiptap'; |
|||
|
|||
const content = ref(''); |
|||
|
|||
// Mock upload function with progress simulation |
|||
const imageUpload: ImageUploadOptions = { |
|||
accept: 'image/jpeg,image/png,image/gif,image/webp', |
|||
maxSize: 5 * 1024 * 1024, // 5MB |
|||
upload: async (_file, onProgress) => { |
|||
// Simulate upload progress |
|||
for (let i = 0; i <= 100; i += 10) { |
|||
await new Promise((resolve) => setTimeout(resolve, 100)); |
|||
onProgress?.(i); |
|||
} |
|||
|
|||
// Return a mock image URL (using picsum for demo) |
|||
return `https://picsum.photos/seed/${Date.now()}/800/400`; |
|||
}, |
|||
onUploadError: (error) => { |
|||
console.error('Upload error:', error); |
|||
}, |
|||
}; |
|||
</script> |
|||
|
|||
<template> |
|||
<div> |
|||
<VbenTiptap |
|||
v-model="content" |
|||
:image-upload="imageUpload" |
|||
placeholder="尝试拖拽或粘贴图片..." |
|||
/> |
|||
<div class="mt-4"> |
|||
<p class="text-sm text-gray-500">提示:</p> |
|||
<ul class="mt-2 text-xs text-gray-400 list-disc pl-4"> |
|||
<li>点击工具栏图片按钮可选择本地上传或 URL 插入</li> |
|||
<li>拖拽图片到编辑器区域可直接上传</li> |
|||
<li>粘贴图片也会触发上传</li> |
|||
<li>上传过程中会显示进度条</li> |
|||
</ul> |
|||
</div> |
|||
</div> |
|||
</template> |
|||
@ -0,0 +1,159 @@ |
|||
--- |
|||
outline: deep |
|||
--- |
|||
|
|||
# Vben Cropper Image Cropping |
|||
|
|||
`VCropper` is a pure native image cropping component that supports both free and fixed aspect ratio cropping, with method-based access to cropped results. |
|||
|
|||
> If some details are not obvious from the docs, check the live demos as well. |
|||
|
|||
::: info Note |
|||
|
|||
If you feel the current component implementation doesn't meet your needs, you can use native components directly or create your own component. The components provided by the framework are not constraints - use them at your discretion. |
|||
|
|||
::: |
|||
|
|||
## Basic Usage |
|||
|
|||
Basic image cropping with free aspect ratio adjustment. |
|||
|
|||
<DemoPreview dir="demos/vben-cropper/basic" /> |
|||
|
|||
## Fixed Aspect Ratio |
|||
|
|||
Set the cropping ratio via the `aspectRatio` prop. The format is `"width:height"`, e.g. `"1:1"`, `"16:9"`, `"3:4"`. |
|||
|
|||
<DemoPreview dir="demos/vben-cropper/aspect-ratio" /> |
|||
|
|||
## API |
|||
|
|||
### Props |
|||
|
|||
| Property | Description | Type | Default | |
|||
| ------------- | ---------------------------------- | -------- | ------- | |
|||
| `img` | Image URL (required) | `string` | - | |
|||
| `width` | Container width | `number` | `500` | |
|||
| `height` | Container height | `number` | `400` | |
|||
| `aspectRatio` | Crop ratio, e.g. `"1:1"`, `"16:9"` | `string` | - | |
|||
|
|||
### Methods |
|||
|
|||
Call component methods via `ref`: |
|||
|
|||
```vue |
|||
<script setup lang="ts"> |
|||
import { ref } from 'vue'; |
|||
import { VCropper } from '@vben/common-ui'; |
|||
|
|||
const cropperRef = ref<InstanceType<typeof VCropper>>(); |
|||
|
|||
const handleCrop = async () => { |
|||
const result = await cropperRef.value?.getCropImage(); |
|||
// result is a Blob or base64 string |
|||
}; |
|||
</script> |
|||
``` |
|||
|
|||
#### getCropImage |
|||
|
|||
Crop and retrieve the image. |
|||
|
|||
```ts |
|||
getCropImage( |
|||
format?: 'image/jpeg' | 'image/png', |
|||
quality?: number, |
|||
outputType?: 'base64' | 'blob', |
|||
targetWidth?: number, |
|||
targetHeight?: number, |
|||
): Promise<Blob | string | undefined> |
|||
``` |
|||
|
|||
**Parameters:** |
|||
|
|||
| Parameter | Type | Default | Description | |
|||
| --- | --- | --- | --- | |
|||
| `format` | `'image/jpeg' \| 'image/png'` | `'image/png'` | Output image format | |
|||
| `quality` | `number` | `0.92` | Compression quality (0-1), only effective for jpeg | |
|||
| `outputType` | `'base64' \| 'blob'` | `'blob'` | Output type, base64 string or Blob object | |
|||
| `targetWidth` | `number` | - | Target width, defaults to original crop width if omitted | |
|||
| `targetHeight` | `number` | - | Target height, defaults to original crop height if omitted | |
|||
|
|||
## Features |
|||
|
|||
### Cropping Operations |
|||
|
|||
- **Drag to Move** - Drag the center area of the crop box to move its position |
|||
- **Corner Resize** - Drag the four corners to resize the crop box |
|||
- **Edge Resize** - Drag the midpoints of edges to adjust a single side |
|||
|
|||
### Aspect Ratio Control |
|||
|
|||
- **Free Ratio** - Without `aspectRatio`, adjust the crop box to any ratio |
|||
- **Fixed Ratio** - With `aspectRatio` set, the crop box maintains the specified ratio |
|||
|
|||
### HiDPI Support |
|||
|
|||
The component automatically adapts to Retina and other high-DPI screens, ensuring crisp output images. |
|||
|
|||
### Image Fitting |
|||
|
|||
- Images are automatically scaled to fit within the container |
|||
- Supports both local and remote images |
|||
- Remote images require CORS support from the server to export cropped results |
|||
|
|||
## Usage Example |
|||
|
|||
```vue |
|||
<script setup lang="ts"> |
|||
import { ref } from 'vue'; |
|||
import { VCropper } from '@vben/common-ui'; |
|||
|
|||
const cropperRef = ref<InstanceType<typeof VCropper>>(); |
|||
const imageUrl = ref('https://example.com/image.jpg'); |
|||
const croppedImage = ref(''); |
|||
|
|||
// Get cropped Blob |
|||
const handleCropBlob = async () => { |
|||
const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob'); |
|||
if (blob instanceof Blob) { |
|||
// Upload to server or create preview URL |
|||
const url = URL.createObjectURL(blob); |
|||
croppedImage.value = url; |
|||
} |
|||
}; |
|||
|
|||
// Get cropped base64 string |
|||
const handleCropBase64 = async () => { |
|||
const base64 = await cropperRef.value?.getCropImage('image/png', 1, 'base64'); |
|||
if (typeof base64 === 'string') { |
|||
croppedImage.value = base64; |
|||
} |
|||
}; |
|||
|
|||
// Export with specific dimensions |
|||
const handleCropWithSize = async () => { |
|||
const blob = await cropperRef.value?.getCropImage( |
|||
'image/jpeg', |
|||
0.9, |
|||
'blob', |
|||
200, // target width |
|||
200, // target height |
|||
); |
|||
}; |
|||
</script> |
|||
|
|||
<template> |
|||
<div> |
|||
<VCropper |
|||
ref="cropperRef" |
|||
:img="imageUrl" |
|||
:width="500" |
|||
:height="400" |
|||
aspect-ratio="1:1" |
|||
/> |
|||
<button @click="handleCropBlob">Crop</button> |
|||
<img v-if="croppedImage" :src="croppedImage" /> |
|||
</div> |
|||
</template> |
|||
``` |
|||
@ -0,0 +1,199 @@ |
|||
--- |
|||
outline: deep |
|||
--- |
|||
|
|||
# Vben Tiptap Rich Text Editor |
|||
|
|||
A rich text editor component built on [Tiptap](https://tiptap.dev/), supporting rich text formatting, image insertion, and image upload features. |
|||
|
|||
> If some details are not obvious from the docs, check the live demos as well. |
|||
|
|||
::: info Note |
|||
|
|||
If you feel the current component implementation doesn't meet your needs, you can use native components directly or create your own component. The components provided by the framework are not constraints - use them at your discretion. |
|||
|
|||
::: |
|||
|
|||
## Basic Usage |
|||
|
|||
<DemoPreview dir="demos/vben-tiptap/basic" /> |
|||
|
|||
## Component List |
|||
|
|||
### VbenTiptap |
|||
|
|||
Main rich text editor component. |
|||
|
|||
### VbenTiptapPreview |
|||
|
|||
Read-only preview component for displaying editor content. |
|||
|
|||
## API |
|||
|
|||
### Props |
|||
|
|||
| Property | Description | Type | Default | |
|||
| --- | --- | --- | --- | |
|||
| `modelValue` (v-model) | Editor content (HTML string) | `string` | `''` | |
|||
| `editable` | Whether the editor is editable | `boolean` | `true` | |
|||
| `toolbar` | Whether to show the toolbar | `boolean` | `true` | |
|||
| `previewable` | Whether to show the preview button | `boolean` | `true` | |
|||
| `placeholder` | Placeholder text | `string` | - | |
|||
| `minHeight` | Minimum height | `number \| string` | `240` | |
|||
| `maxHeight` | Maximum height | `number \| string` | `400` | |
|||
| `extensions` | Custom Tiptap extensions | `Extensions` | - | |
|||
| `imageUpload` | Image upload configuration | `ImageUploadOptions` | - | |
|||
|
|||
### Events |
|||
|
|||
| Event | Description | Parameters | |
|||
| -------- | ------------------------------ | ----------------------- | |
|||
| `change` | Triggered when content changes | `VbenTiptapChangeEvent` | |
|||
|
|||
#### VbenTiptapChangeEvent |
|||
|
|||
```ts |
|||
interface VbenTiptapChangeEvent { |
|||
html: string; // HTML content |
|||
json: JSONContent; // JSON structure |
|||
text: string; // Plain text content |
|||
} |
|||
``` |
|||
|
|||
### ImageUploadOptions |
|||
|
|||
Image upload configuration: |
|||
|
|||
```ts |
|||
interface ImageUploadOptions { |
|||
/** Allowed file types, default 'image/*' */ |
|||
accept?: string; |
|||
/** Max file size in bytes, default 5MB */ |
|||
maxSize?: number; |
|||
/** Upload error callback, uses alert if not provided */ |
|||
onUploadError?: (error: unknown) => void; |
|||
/** Upload function, returns image URL */ |
|||
upload: ( |
|||
file: File, |
|||
onProgress?: (percent: number) => void, |
|||
) => Promise<string>; |
|||
} |
|||
``` |
|||
|
|||
### VbenTiptapPreview Props |
|||
|
|||
| Property | Description | Type | Default | |
|||
| ----------- | ----------------------- | ------------------ | ------- | |
|||
| `content` | HTML content to preview | `string` | `''` | |
|||
| `minHeight` | Minimum height | `number \| string` | `160` | |
|||
| `class` | Custom class name | `any` | - | |
|||
|
|||
## Toolbar Features |
|||
|
|||
The editor toolbar provides the following features: |
|||
|
|||
### Formatting |
|||
|
|||
- **Undo/Redo** - Undo or redo editing operations |
|||
- **Clear Formatting** - Remove all formatting from selected text |
|||
- **Bold** - Bold text |
|||
- **Italic** - Italic text |
|||
- **Underline** - Underline text |
|||
- **Strikethrough** - Strikethrough text |
|||
- **Inline Code** - Inline code mark |
|||
|
|||
### Structure |
|||
|
|||
- **Headings** - Paragraph, H1-H4 heading switching |
|||
- **Ordered List** - Numbered list |
|||
- **Bullet List** - Bulleted list |
|||
- **Blockquote** - Quote block style |
|||
- **Code Block** - Multi-line code block |
|||
|
|||
### Links & Images |
|||
|
|||
- **Insert Link** - Insert or edit hyperlinks |
|||
- **Remove Link** - Remove link from selected text |
|||
- **Insert Image** - Insert image via URL |
|||
|
|||
### Style |
|||
|
|||
- **Text Color** - Set text color (preset palette) |
|||
- **Highlight Color** - Set text background highlight color |
|||
|
|||
### Alignment |
|||
|
|||
- **Align Left** - Left align text |
|||
- **Align Center** - Center align text |
|||
- **Align Right** - Right align text |
|||
|
|||
### Other |
|||
|
|||
- **Preview** - Preview content in a modal |
|||
|
|||
## Image Upload |
|||
|
|||
<DemoPreview dir="demos/vben-tiptap/image-upload" /> |
|||
|
|||
When `imageUpload` is configured, the toolbar image button becomes a dropdown menu with "Upload" and "URL" options. |
|||
|
|||
### Upload Methods |
|||
|
|||
Three image upload methods are supported: |
|||
|
|||
1. **File Selection** - Click the upload button in toolbar |
|||
2. **Drag & Drop** - Drag images directly into the editor |
|||
3. **Paste** - Paste images into the editor |
|||
|
|||
### Upload Progress Display |
|||
|
|||
During upload: |
|||
|
|||
- **Loading Indicator** - Spinner animation indicating upload in progress |
|||
- **Progress Bar** - Shows progress bar when upload function provides `onProgress` callback |
|||
|
|||
### File Validation |
|||
|
|||
- `accept` - Specify allowed file types (MIME types) |
|||
- `maxSize` - Maximum file size limit (bytes) |
|||
- Validation failure triggers `onUploadError` callback or default alert |
|||
|
|||
::: warning Important Notes |
|||
|
|||
- Only single image upload is supported; multi-image drag/paste will show a prompt and process only the first image |
|||
- Do not save editor content (`getHTML()`) during upload as image URLs are temporary blob URLs |
|||
- When using custom `extensions`, the image upload feature will not be available (toolbar won't show upload option) |
|||
|
|||
::: |
|||
|
|||
## Custom Extensions |
|||
|
|||
Pass custom Tiptap extension configurations via the `extensions` property: |
|||
|
|||
```vue |
|||
<script setup lang="ts"> |
|||
import { VbenTiptap } from '@vben/plugins/tiptap'; |
|||
import StarterKit from '@tiptap/starter-kit'; |
|||
import Underline from '@tiptap/extension-underline'; |
|||
|
|||
const extensions = [ |
|||
StarterKit, |
|||
Underline, |
|||
// Other extensions... |
|||
]; |
|||
</script> |
|||
|
|||
<template> |
|||
<VbenTiptap v-model="content" :extensions="extensions" /> |
|||
</template> |
|||
``` |
|||
|
|||
::: warning Custom Extensions Note |
|||
|
|||
When using custom `extensions`: |
|||
|
|||
- Default extension configuration will not take effect |
|||
- Image upload feature is not available (toolbar won't show upload option) |
|||
- You need to configure all required editor features yourself |
|||
|
|||
::: |
|||
@ -0,0 +1,70 @@ |
|||
import type { Plugin } from 'vite'; |
|||
|
|||
function viteDayjsPlugin(): Plugin { |
|||
return { |
|||
name: 'vite-dayjs-plugin', |
|||
enforce: 'pre', |
|||
async resolveId(source, importer, options) { |
|||
// 1) 已经使用了 dayjs/esm 的不处理
|
|||
if (source.startsWith('dayjs/esm')) return null; |
|||
|
|||
// 2) 根入口：dayjs -> dayjs/esm
|
|||
if (source === 'dayjs') { |
|||
return await this.resolve('dayjs/esm', importer, { |
|||
skipSelf: true, |
|||
...options, |
|||
}); |
|||
} |
|||
|
|||
// 3) 插件入口的多种写法
|
|||
// - dayjs/plugin/xxx.js -> dayjs/esm/plugin/xxx/index.js
|
|||
// - dayjs/plugin/xxx -> dayjs/esm/plugin/xxx
|
|||
const pluginWithJs = source.match(/^dayjs\/plugin\/([^/]+)\.js$/); |
|||
if (pluginWithJs) { |
|||
const target = `dayjs/esm/plugin/${pluginWithJs[1]}/index.js`; |
|||
return await this.resolve(target, importer, { |
|||
skipSelf: true, |
|||
...options, |
|||
}); |
|||
} |
|||
|
|||
const pluginBare = source.match(/^dayjs\/plugin\/([^/]+)$/); |
|||
if (pluginBare) { |
|||
const target = `dayjs/esm/plugin/${pluginBare[1]}`; |
|||
return await this.resolve(target, importer, { |
|||
skipSelf: true, |
|||
...options, |
|||
}); |
|||
} |
|||
|
|||
// 4) 处理多语言包
|
|||
// - dayjs/locale/xxx.js -> dayjs/esm/locale/xxx.js
|
|||
const localeWithJs = source.match(/^dayjs\/locale\/([^/]+)\.js$/); |
|||
if (localeWithJs) { |
|||
const target = `dayjs/esm/locale/${localeWithJs[1]}.js`; |
|||
return await this.resolve(target, importer, { |
|||
skipSelf: true, |
|||
...options, |
|||
}); |
|||
} |
|||
const localeBare = source.match(/^dayjs\/locale\/([^/]+)$/); |
|||
if (localeBare) { |
|||
const target = `dayjs/esm/locale/${localeBare[1]}`; |
|||
return await this.resolve(target, importer, { |
|||
skipSelf: true, |
|||
...options, |
|||
}); |
|||
} |
|||
|
|||
return null; |
|||
}, |
|||
config() { |
|||
return { |
|||
optimizeDeps: { |
|||
exclude: ['dayjs'], |
|||
}, |
|||
}; |
|||
}, |
|||
}; |
|||
} |
|||
export { viteDayjsPlugin }; |
|||
@ -0,0 +1,418 @@ |
|||
# Cache 模块 |
|||
|
|||
基于**策略模式**的异步存储管理方案，支持多种存储后端（localStorage、IndexedDB、Memory），提供统一的 API 接口。 |
|||
|
|||
## 架构设计 |
|||
|
|||
```shell |
|||
┌───────────────────────────────────────────────┐ |
|||
│ StorageManager │ |
|||
│ ┌─────────────┐ ┌───────────────────────┐ │ |
|||
│ │ Prefix 隔离 │ │ TTL 过期管理 │ │ |
|||
│ └─────────────┘ └───────────────────────┘ │ |
|||
├───────────────────────────────────────────────┤ |
|||
│ IStorageDriver │ |
|||
├──────────┬─────────────────┬──────────────────┤ |
|||
│ Local │ IndexedDB │ Memory │ |
|||
│ Storage │ Driver │ Driver │ |
|||
│ Driver │ │ │ |
|||
└──────────┴─────────────────┴──────────────────┘ |
|||
``` |
|||
|
|||
**分层职责：** |
|||
|
|||
| 层级 | 职责 | |
|||
| ---------------- | -------------------------------------------- | |
|||
| `StorageManager` | 命名空间前缀隔离、TTL 过期检查、统一对外 API | |
|||
| `IStorageDriver` | 纯粹的 KV 存取抽象接口 | |
|||
| 各 Driver 实现 | 对接具体存储引擎，不感知前缀和 TTL | |
|||
|
|||
--- |
|||
|
|||
## 快速开始 |
|||
|
|||
### 基本使用（默认 localStorage） |
|||
|
|||
```typescript |
|||
import { StorageManager } from '@vben-core/shared/cache'; |
|||
|
|||
const cache = new StorageManager({ prefix: 'myapp' }); |
|||
// 使用 IndexedDB |
|||
//new StorageManager({ driver: new IndexedDBDriver(), prefix: 'app' }); |
|||
|
|||
// 使用 sessionStorage |
|||
//new StorageManager({ driver: new LocalStorageDriver({ storageType: 'sessionStorage' }), prefix: 'app' }); |
|||
|
|||
// 测试环境 |
|||
//new StorageManager({ driver: new MemoryStorageDriver(), prefix: 'test' }); |
|||
|
|||
// 存储数据 |
|||
await cache.setItem('user', { name: '张三', age: 28 }); |
|||
|
|||
// 读取数据 |
|||
const user = await cache.getItem('user'); |
|||
// => { name: '张三', age: 28 } |
|||
|
|||
// 带默认值读取 |
|||
const settings = await cache.getItem('settings', { theme: 'light' }); |
|||
// 如果不存在，返回 { theme: 'light' } |
|||
|
|||
// 删除数据 |
|||
await cache.removeItem('user'); |
|||
|
|||
// 清除当前前缀下所有数据 |
|||
await cache.clear(); |
|||
``` |
|||
|
|||
### 带 TTL 过期 |
|||
|
|||
```typescript |
|||
const cache = new StorageManager({ prefix: 'session' }); |
|||
|
|||
// 设置 5 分钟后过期（TTL 单位为毫秒） |
|||
await cache.setItem('token', 'abc123', 5 * 60 * 1000); |
|||
|
|||
// 5 分钟内可以正常读取 |
|||
const token = await cache.getItem('token'); |
|||
// => 'abc123' |
|||
|
|||
// 5 分钟后自动返回 null（惰性删除） |
|||
const expiredToken = await cache.getItem('token'); |
|||
// => null |
|||
|
|||
// 主动清理所有过期项 |
|||
await cache.clearExpiredItems(); |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## 存储驱动 |
|||
|
|||
### LocalStorageDriver（默认） |
|||
|
|||
基于浏览器 `localStorage` 或 `sessionStorage`，数据持久化存储。 |
|||
|
|||
```typescript |
|||
import { LocalStorageDriver, StorageManager } from '@vben-core/shared/cache'; |
|||
|
|||
// 使用 localStorage（默认） |
|||
const cache = new StorageManager({ |
|||
driver: new LocalStorageDriver(), |
|||
prefix: 'app', |
|||
}); |
|||
|
|||
// 使用 sessionStorage |
|||
const sessionCache = new StorageManager({ |
|||
driver: new LocalStorageDriver({ storageType: 'sessionStorage' }), |
|||
prefix: 'app', |
|||
}); |
|||
``` |
|||
|
|||
**特点：** |
|||
|
|||
- 同步 API 用 async 包装，保持接口统一 |
|||
- 自动处理 JSON 序列化/反序列化 |
|||
- 数据损坏时自动清除并返回 null |
|||
- 存储上限约 5-10MB（视浏览器而定） |
|||
|
|||
**适用场景：** 用户偏好设置、小型配置数据、Token 存储 |
|||
|
|||
--- |
|||
|
|||
### IndexedDBDriver |
|||
|
|||
基于浏览器 IndexedDB，支持大容量结构化数据存储。 |
|||
|
|||
```typescript |
|||
import {IndexedDBDriver, StorageManager} from '@vben-core/shared/cache'; |
|||
|
|||
const cache = new StorageManager({ |
|||
driver: new IndexedDBDriver({ |
|||
dbName: 'my-app-db', // 数据库名称，默认 'vben-storage' |
|||
dbVersion: 1, // 数据库版本，默认 1 |
|||
storeName: 'cache-store', // 对象存储名称，默认 'kv-store' |
|||
}), |
|||
prefix: 'data', |
|||
}); |
|||
|
|||
// 存储大量数据 |
|||
await cache.setItem('table-data', largeDataArray); |
|||
|
|||
// 存储二进制友好的结构（IndexedDB 原生支持） |
|||
await cache.setItem('config', { |
|||
columns: [...], |
|||
filters: [...], |
|||
pagination: {page: 1, size: 20}, |
|||
}); |
|||
``` |
|||
|
|||
**特点：** |
|||
|
|||
- 懒初始化：首次操作时自动打开数据库，无需手动调用 `init()` |
|||
- 存储容量大（通常数百 MB 到 GB 级别） |
|||
- 支持结构化克隆（可存储 Date、RegExp、Blob 等复杂类型） |
|||
- 天然异步，不阻塞主线程 |
|||
|
|||
**适用场景：** 离线数据缓存、大型表格数据、文件/图片缓存、复杂业务数据 |
|||
|
|||
--- |
|||
|
|||
### MemoryStorageDriver |
|||
|
|||
基于内存 Map，数据不持久化，页面刷新即丢失。 |
|||
|
|||
```typescript |
|||
import { MemoryStorageDriver, StorageManager } from '@vben-core/shared/cache'; |
|||
|
|||
const cache = new StorageManager({ |
|||
driver: new MemoryStorageDriver(), |
|||
prefix: 'test', |
|||
}); |
|||
``` |
|||
|
|||
**特点：** |
|||
|
|||
- 读写速度最快 |
|||
- 无浏览器 API 依赖 |
|||
- 数据随页面生命周期销毁 |
|||
|
|||
**适用场景：** 单元测试、SSR 服务端渲染、临时运行时缓存 |
|||
|
|||
--- |
|||
|
|||
## API 参考 |
|||
|
|||
### StorageManager |
|||
|
|||
#### 构造函数 |
|||
|
|||
```typescript |
|||
new StorageManager(options?: StorageManagerOptions) |
|||
``` |
|||
|
|||
| 参数 | 类型 | 默认值 | 说明 | |
|||
| --- | --- | --- | --- | |
|||
| `driver` | `IStorageDriver` | `new LocalStorageDriver()` | 存储驱动实例 | |
|||
| `prefix` | `string` | `''` | 键前缀，用于命名空间隔离 | |
|||
|
|||
#### 方法 |
|||
|
|||
| 方法 | 签名 | 说明 | |
|||
| --- | --- | --- | |
|||
| `getItem` | `getItem<T>(key: string, defaultValue?: T \| null): Promise<T \| null>` | 获取存储项，过期或不存在返回默认值 | |
|||
| `setItem` | `setItem<T>(key: string, value: T, ttl?: number): Promise<void>` | 设置存储项，可选 TTL（毫秒） | |
|||
| `removeItem` | `removeItem(key: string): Promise<void>` | 删除指定存储项 | |
|||
| `clear` | `clear(): Promise<void>` | 清除当前前缀下所有存储项 | |
|||
| `clearExpiredItems` | `clearExpiredItems(): Promise<void>` | 主动清理所有过期项 | |
|||
|
|||
--- |
|||
|
|||
### IStorageDriver 接口 |
|||
|
|||
自定义驱动需要实现此接口： |
|||
|
|||
```typescript |
|||
interface IStorageDriver { |
|||
clear(): Promise<void>; |
|||
|
|||
getItem<T>(key: string): Promise<null | T>; |
|||
|
|||
keys(): Promise<string[]>; |
|||
|
|||
removeItem(key: string): Promise<void>; |
|||
|
|||
setItem<T>(key: string, value: T): Promise<void>; |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## 高级用法 |
|||
|
|||
### 自定义 Driver |
|||
|
|||
```typescript |
|||
import type { IStorageDriver } from '@vben-core/shared/cache'; |
|||
|
|||
class CookieStorageDriver implements IStorageDriver { |
|||
async getItem<T>(key: string): Promise<null | T> { |
|||
const value = getCookie(key); |
|||
return value ? JSON.parse(value) : null; |
|||
} |
|||
|
|||
async setItem<T>(key: string, value: T): Promise<void> { |
|||
setCookie(key, JSON.stringify(value)); |
|||
} |
|||
|
|||
async removeItem(key: string): Promise<void> { |
|||
deleteCookie(key); |
|||
} |
|||
|
|||
async clear(): Promise<void> { |
|||
clearAllCookies(); |
|||
} |
|||
|
|||
async keys(): Promise<string[]> { |
|||
return getAllCookieNames(); |
|||
} |
|||
} |
|||
|
|||
// 使用自定义 Driver |
|||
const cache = new StorageManager({ |
|||
driver: new CookieStorageDriver(), |
|||
prefix: 'ck', |
|||
}); |
|||
``` |
|||
|
|||
### 根据环境动态选择 Driver |
|||
|
|||
```typescript |
|||
import { |
|||
IndexedDBDriver, |
|||
LocalStorageDriver, |
|||
MemoryStorageDriver, |
|||
StorageManager, |
|||
} from '@vben-core/shared/cache'; |
|||
|
|||
function createStorageManager(prefix: string) { |
|||
// SSR 环境使用内存驱动 |
|||
if (typeof window === 'undefined') { |
|||
return new StorageManager({ |
|||
driver: new MemoryStorageDriver(), |
|||
prefix, |
|||
}); |
|||
} |
|||
|
|||
// 大数据场景使用 IndexedDB |
|||
if (needsLargeStorage()) { |
|||
return new StorageManager({ |
|||
driver: new IndexedDBDriver({ dbName: `${prefix}-db` }), |
|||
prefix, |
|||
}); |
|||
} |
|||
|
|||
// 默认使用 localStorage |
|||
return new StorageManager({ prefix }); |
|||
} |
|||
``` |
|||
|
|||
### 命名空间隔离 |
|||
|
|||
```typescript |
|||
// 不同模块使用不同前缀，互不干扰 |
|||
const userCache = new StorageManager({ prefix: 'user' }); |
|||
const configCache = new StorageManager({ prefix: 'config' }); |
|||
|
|||
await userCache.setItem('profile', { name: '张三' }); |
|||
await configCache.setItem('profile', { theme: 'dark' }); |
|||
|
|||
// 各自独立 |
|||
await userCache.getItem('profile'); // => { name: '张三' } |
|||
await configCache.getItem('profile'); // => { theme: 'dark' } |
|||
|
|||
// 只清除 user 前缀的数据 |
|||
await userCache.clear(); |
|||
await configCache.getItem('profile'); // => { theme: 'dark' }（不受影响） |
|||
``` |
|||
|
|||
### 定时清理过期数据 |
|||
|
|||
```typescript |
|||
const cache = new StorageManager({ prefix: 'app' }); |
|||
|
|||
// 应用启动时清理一次 |
|||
await cache.clearExpiredItems(); |
|||
|
|||
// 或者定时清理（每 10 分钟） |
|||
setInterval( |
|||
async () => { |
|||
await cache.clearExpiredItems(); |
|||
}, |
|||
10 * 60 * 1000, |
|||
); |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## 数据存储格式 |
|||
|
|||
`StorageManager` 在 Driver 层存储的数据结构为： |
|||
|
|||
```typescript |
|||
interface StorageItem<T> { |
|||
expiry?: number; // 过期时间戳（毫秒），undefined 表示永不过期 |
|||
value: T; // 实际业务数据 |
|||
} |
|||
``` |
|||
|
|||
实际存储的 key 格式为：`{prefix}-{key}` |
|||
|
|||
例如 `prefix = 'app'`，`key = 'user'`，则实际存储键为 `app-user`。 |
|||
|
|||
--- |
|||
|
|||
## 过期策略 |
|||
|
|||
采用**惰性删除 + 主动清理**双重策略： |
|||
|
|||
| 策略 | 触发时机 | 说明 | |
|||
| --- | --- | --- | |
|||
| 惰性删除 | 调用 `getItem` 时 | 读取时检查过期，过期则删除并返回默认值 | |
|||
| 主动清理 | 调用 `clearExpiredItems` 时 | 遍历所有带前缀的 key，删除已过期项 | |
|||
|
|||
--- |
|||
|
|||
## 各 Driver 对比 |
|||
|
|||
| 特性 | LocalStorageDriver | IndexedDBDriver | MemoryStorageDriver | |
|||
| ---------- | ------------------- | ---------------- | ------------------- | |
|||
| 持久化 | ✅ | ✅ | ❌ | |
|||
| 容量 | 5-10 MB | 数百 MB+ | 受内存限制 | |
|||
| 速度 | 快（同步） | 中等（异步 I/O） | 最快 | |
|||
| 数据类型 | 仅 JSON 可序列化 | 结构化克隆 | 任意 JS 对象 | |
|||
| 浏览器支持 | 所有现代浏览器 | 所有现代浏览器 | 任意环境 | |
|||
| 阻塞主线程 | 是 | 否 | 否 | |
|||
| 适用场景 | 配置、Token、小数据 | 离线缓存、大数据 | 测试、SSR | |
|||
|
|||
--- |
|||
|
|||
## 在项目中的使用 |
|||
|
|||
本项目中 `StorageManager` 主要被 `PreferenceManager` 消费，用于持久化用户偏好设置： |
|||
|
|||
```typescript |
|||
// packages/@core/preferences/src/preferences.ts |
|||
class PreferenceManager { |
|||
private cache: StorageManager; |
|||
|
|||
constructor() { |
|||
this.cache = new StorageManager(); |
|||
this.state = reactive<Preferences>({ ...defaultPreferences }); |
|||
} |
|||
|
|||
initPreferences = async ({ namespace }) => { |
|||
// 用应用命名空间重新初始化 |
|||
this.cache = new StorageManager({ prefix: namespace }); |
|||
|
|||
// 从缓存加载偏好设置 |
|||
const cached = await this.cache.getItem<Preferences>('preferences'); |
|||
// ... |
|||
}; |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## 注意事项 |
|||
|
|||
1. **所有方法都是异步的** — 即使底层是同步的 localStorage，API 也返回 Promise，确保切换 Driver 时无需改动调用方。 |
|||
|
|||
2. **TTL 单位是毫秒** — `setItem('key', value, 60000)` 表示 60 秒后过期。 |
|||
|
|||
3. **IndexedDB 懒初始化** — 不需要手动调用 `init()` 或 `open()`，首次操作时自动打开数据库连接并复用。 |
|||
|
|||
4. **前缀隔离是逻辑隔离** — `clear()` 只清除当前前缀下的数据，不影响其他前缀或无前缀的数据。 |
|||
|
|||
5. **错误处理** — LocalStorageDriver 在 JSON 解析失败时自动清除损坏数据； `PreferenceManager.saveToCache` 内部 try-catch 防止未捕获异常。 |
|||
|
|||
6. **IndexedDB 版本升级** — 如果需要修改 objectStore 结构，需要递增 `dbVersion`。当前实现在 `upgradeneeded` 事件中自动创建 objectStore。 |
|||
@ -1 +1,5 @@ |
|||
export * from './indexeddb-driver'; |
|||
export * from './local-storage-driver'; |
|||
export * from './memory-storage-driver'; |
|||
export * from './storage-manager'; |
|||
export type * from './types'; |
|||
|
|||
@ -0,0 +1,137 @@ |
|||
import type { IStorageDriver } from './types'; |
|||
|
|||
interface IndexedDBDriverOptions { |
|||
/** 数据库名称 */ |
|||
dbName?: string; |
|||
/** 数据库版本 */ |
|||
dbVersion?: number; |
|||
/** 对象存储名称 */ |
|||
storeName?: string; |
|||
} |
|||
|
|||
/** |
|||
* IndexedDB 驱动 |
|||
* 采用懒初始化模式，首次操作时自动打开数据库 |
|||
*/ |
|||
class IndexedDBDriver implements IStorageDriver { |
|||
private dbName: string; |
|||
private dbPromise: null | Promise<IDBDatabase> = null; |
|||
private dbVersion: number; |
|||
private storeName: string; |
|||
|
|||
constructor({ |
|||
dbName = 'vben-storage', |
|||
dbVersion = 1, |
|||
storeName = 'kv-store', |
|||
}: IndexedDBDriverOptions = {}) { |
|||
this.dbName = dbName; |
|||
this.dbVersion = dbVersion; |
|||
this.storeName = storeName; |
|||
} |
|||
|
|||
async clear(): Promise<void> { |
|||
const db = await this.getDB(); |
|||
return new Promise((resolve, reject) => { |
|||
const tx = db.transaction(this.storeName, 'readwrite'); |
|||
const store = tx.objectStore(this.storeName); |
|||
store.clear(); |
|||
|
|||
tx.addEventListener('complete', () => resolve()); |
|||
tx.addEventListener('error', () => reject(tx.error)); |
|||
tx.addEventListener('abort', () => |
|||
reject(tx.error ?? new Error('Transaction aborted')), |
|||
); |
|||
}); |
|||
} |
|||
|
|||
async getItem<T>(key: string): Promise<null | T> { |
|||
const db = await this.getDB(); |
|||
return new Promise((resolve, reject) => { |
|||
const tx = db.transaction(this.storeName, 'readonly'); |
|||
const store = tx.objectStore(this.storeName); |
|||
const request = store.get(key); |
|||
|
|||
request.addEventListener('success', () => |
|||
resolve(request.result ?? null), |
|||
); |
|||
request.addEventListener('error', () => reject(request.error)); |
|||
}); |
|||
} |
|||
|
|||
async keys(): Promise<string[]> { |
|||
const db = await this.getDB(); |
|||
return new Promise((resolve, reject) => { |
|||
const tx = db.transaction(this.storeName, 'readonly'); |
|||
const store = tx.objectStore(this.storeName); |
|||
const request = store.getAllKeys(); |
|||
|
|||
request.addEventListener('success', () => |
|||
resolve(request.result.map(String)), |
|||
); |
|||
request.addEventListener('error', () => reject(request.error)); |
|||
}); |
|||
} |
|||
|
|||
async removeItem(key: string): Promise<void> { |
|||
const db = await this.getDB(); |
|||
return new Promise((resolve, reject) => { |
|||
const tx = db.transaction(this.storeName, 'readwrite'); |
|||
const store = tx.objectStore(this.storeName); |
|||
store.delete(key); |
|||
|
|||
tx.addEventListener('complete', () => resolve()); |
|||
tx.addEventListener('error', () => reject(tx.error)); |
|||
tx.addEventListener('abort', () => |
|||
reject(tx.error ?? new Error('Transaction aborted')), |
|||
); |
|||
}); |
|||
} |
|||
|
|||
async setItem(key: string, value: unknown): Promise<void> { |
|||
const db = await this.getDB(); |
|||
return new Promise((resolve, reject) => { |
|||
const tx = db.transaction(this.storeName, 'readwrite'); |
|||
const store = tx.objectStore(this.storeName); |
|||
store.put(value, key); |
|||
|
|||
tx.addEventListener('complete', () => resolve()); |
|||
tx.addEventListener('error', () => reject(tx.error)); |
|||
tx.addEventListener('abort', () => |
|||
reject(tx.error ?? new Error('Transaction aborted')), |
|||
); |
|||
}); |
|||
} |
|||
|
|||
/** |
|||
* 懒初始化：首次调用时打开数据库，后续复用同一个 Promise |
|||
*/ |
|||
private getDB(): Promise<IDBDatabase> { |
|||
if (!this.dbPromise) { |
|||
this.dbPromise = this.openDB().catch((error) => { |
|||
// allow retry on next call
|
|||
this.dbPromise = null; |
|||
throw error; |
|||
}); |
|||
} |
|||
return this.dbPromise; |
|||
} |
|||
|
|||
private openDB(): Promise<IDBDatabase> { |
|||
return new Promise((resolve, reject) => { |
|||
const request = indexedDB.open(this.dbName, this.dbVersion); |
|||
|
|||
request.addEventListener('upgradeneeded', () => { |
|||
const db = request.result; |
|||
if (!db.objectStoreNames.contains(this.storeName)) { |
|||
db.createObjectStore(this.storeName); |
|||
} |
|||
}); |
|||
|
|||
request.addEventListener('success', () => resolve(request.result)); |
|||
request.addEventListener('error', () => reject(request.error)); |
|||
}); |
|||
} |
|||
} |
|||
|
|||
export { IndexedDBDriver }; |
|||
export type { IndexedDBDriverOptions }; |
|||
@ -0,0 +1,71 @@ |
|||
import type { IStorageDriver } from './types'; |
|||
|
|||
type StorageType = 'localStorage' | 'sessionStorage'; |
|||
|
|||
interface LocalStorageDriverOptions { |
|||
/** 使用 localStorage 还是 sessionStorage */ |
|||
storageType?: StorageType; |
|||
} |
|||
|
|||
/** |
|||
* LocalStorage / SessionStorage 驱动 |
|||
* 用 async 包装同步 API，保持接口统一 |
|||
*/ |
|||
class LocalStorageDriver implements IStorageDriver { |
|||
private storage: Storage; |
|||
|
|||
constructor({ |
|||
storageType = 'localStorage', |
|||
}: LocalStorageDriverOptions = {}) { |
|||
if (typeof window === 'undefined') { |
|||
// eslint-disable-next-line unicorn/prefer-type-error -- not a type check, it's an environment check
|
|||
throw new Error( |
|||
'LocalStorageDriver is not available in non-browser environments. Use MemoryStorageDriver instead.', |
|||
); |
|||
} |
|||
this.storage = |
|||
storageType === 'localStorage' |
|||
? window.localStorage |
|||
: window.sessionStorage; |
|||
} |
|||
|
|||
async clear(): Promise<void> { |
|||
this.storage.clear(); |
|||
} |
|||
|
|||
async getItem<T>(key: string): Promise<null | T> { |
|||
const raw = this.storage.getItem(key); |
|||
if (raw === null) { |
|||
return null; |
|||
} |
|||
try { |
|||
return JSON.parse(raw) as T; |
|||
} catch { |
|||
// 数据损坏，清除并返回 null
|
|||
this.storage.removeItem(key); |
|||
return null; |
|||
} |
|||
} |
|||
|
|||
async keys(): Promise<string[]> { |
|||
const result: string[] = []; |
|||
for (let i = 0; i < this.storage.length; i++) { |
|||
const key = this.storage.key(i); |
|||
if (key !== null) { |
|||
result.push(key); |
|||
} |
|||
} |
|||
return result; |
|||
} |
|||
|
|||
async removeItem(key: string): Promise<void> { |
|||
this.storage.removeItem(key); |
|||
} |
|||
|
|||
async setItem(key: string, value: unknown): Promise<void> { |
|||
this.storage.setItem(key, JSON.stringify(value)); |
|||
} |
|||
} |
|||
|
|||
export { LocalStorageDriver }; |
|||
export type { LocalStorageDriverOptions }; |
|||
@ -0,0 +1,32 @@ |
|||
import type { IStorageDriver } from './types'; |
|||
|
|||
/** |
|||
* 内存存储驱动 |
|||
* 适用于测试环境和 SSR 场景，数据不持久化 |
|||
*/ |
|||
class MemoryStorageDriver implements IStorageDriver { |
|||
private store = new Map<string, unknown>(); |
|||
|
|||
async clear(): Promise<void> { |
|||
this.store.clear(); |
|||
} |
|||
|
|||
async getItem<T>(key: string): Promise<null | T> { |
|||
const value = this.store.get(key); |
|||
return (value as T) ?? null; |
|||
} |
|||
|
|||
async keys(): Promise<string[]> { |
|||
return [...this.store.keys()]; |
|||
} |
|||
|
|||
async removeItem(key: string): Promise<void> { |
|||
this.store.delete(key); |
|||
} |
|||
|
|||
async setItem(key: string, value: unknown): Promise<void> { |
|||
this.store.set(key, value); |
|||
} |
|||
} |
|||
|
|||
export { MemoryStorageDriver }; |
|||
@ -1,17 +1,39 @@ |
|||
type StorageType = 'localStorage' | 'sessionStorage'; |
|||
/** |
|||
* 存储驱动接口（策略模式核心抽象） |
|||
* 所有存储实现（localStorage、IndexedDB、Memory 等）都需要实现此接口 |
|||
* Driver 层只负责纯粹的 KV 存取，不感知 TTL 和前缀 |
|||
*/ |
|||
interface IStorageDriver { |
|||
/** 清除所有存储项 */ |
|||
clear(): Promise<void>; |
|||
|
|||
interface StorageValue<T> { |
|||
data: T; |
|||
expiry: null | number; |
|||
/** 获取存储项 */ |
|||
getItem<T>(key: string): Promise<null | T>; |
|||
|
|||
/** 获取所有 key */ |
|||
keys(): Promise<string[]>; |
|||
|
|||
/** 移除存储项 */ |
|||
removeItem(key: string): Promise<void>; |
|||
|
|||
/** 设置存储项 */ |
|||
setItem(key: string, value: unknown): Promise<void>; |
|||
} |
|||
|
|||
/** |
|||
* 带 TTL 的存储项包装结构 |
|||
* TTL 逻辑由 StorageManager 统一管理，Driver 层不感知 |
|||
*/ |
|||
interface StorageItem<T> { |
|||
expiry?: number; |
|||
value: T; |
|||
} |
|||
|
|||
interface IStorageCache { |
|||
clear(): void; |
|||
getItem<T>(key: string): null | T; |
|||
key(index: number): null | string; |
|||
length(): number; |
|||
removeItem(key: string): void; |
|||
setItem<T>(key: string, value: T, expiryInMinutes?: number): void; |
|||
interface StorageManagerOptions { |
|||
/** 存储驱动实例 */ |
|||
driver?: IStorageDriver; |
|||
/** 键前缀，用于命名空间隔离 */ |
|||
prefix?: string; |
|||
} |
|||
|
|||
export type { IStorageCache, StorageType, StorageValue }; |
|||
export type { IStorageDriver, StorageItem, StorageManagerOptions }; |
|||
|
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue