docs(@vben/docs): 添加 VCropper 图片裁剪组件文档 (#7904)
* docs(@vben/docs): 添加 VCropper 图片裁剪组件文档 - 新增中文文档 docs/src/components/common-ui/vben-cropper.md - 新增英文文档 docs/src/en/components/common-ui/vben-cropper.md - 新增基础用法示例 demos/vben-cropper/basic - 新增固定比例裁剪示例 demos/vben-cropper/aspect-ratio - 更新侧边栏配置添加 Cropper 入口 * fix: 更正跨域图片描述并修复 demo 内存泄漏 - 文档更正：网络图片导出裁剪结果需服务端 CORS 支持 - 修复 URL.createObjectURL 内存泄漏：添加 revokeObjectURL 释放
This commit is contained in:
JyQAQ
172
docs/src/components/common-ui/vben-cropper.md
Normal file
172
docs/src/components/common-ui/vben-cropper.md
Normal file
@@ -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>
|
||||
```
|
||||
Reference in New Issue
Block a user