102 lines
5.5 KiB
Markdown
102 lines
5.5 KiB
Markdown
|
---
|
|||
|
|
name: jjb-image-uploader
|
|||
|
|
description: 定义 JJB 图片上传组件使用规范。在使用 ImageUploader、getValueProps、getValueFromEvent 或 Form.Item 集成时使用。必须参考 MD/d.ts 文档。
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 通用业务组件使用规范
|
|||
|
|
|
|||
|
|
## 图片上传组件
|
|||
|
|
|
|||
|
|
> **⚠️ 重要约束**：本章节所有组件必须严格参考 node_modules 中对应依赖包的 MD 文档或 d.ts 文件！不得猜测组件属性！
|
|||
|
|
|
|||
|
|
## 使用
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
import ImageUploader, {
|
|||
|
|
getValueProps,
|
|||
|
|
getValueFromEvent,
|
|||
|
|
} from '@cqsjjb/jjb-react-admin-component/ImageUploader'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 集成规范
|
|||
|
|
|
|||
|
|
必须通过 `Form.Item` 的 `getValueProps` 与 `getValueFromEvent` 属性实现数据的双向绑定与转换。
|
|||
|
|
|
|||
|
|
## 实现逻辑
|
|||
|
|
|
|||
|
|
- `getValueProps`：将表单内部的图片 URL 转换为组件所需的格式。
|
|||
|
|
- `getValueFromEvent`：拦截组件的上传事件，提取接口返回的图片地址并同步至表单状态。
|
|||
|
|
|
|||
|
|
## 代码演示
|
|||
|
|
|
|||
|
|
```jsx
|
|||
|
|
import { useState } from 'react';
|
|||
|
|
import { Button, Form } from 'antd';
|
|||
|
|
import ImageUploader, { getValueProps, getValueFromEvent } from '@cqsjjb/jjb-react-admin-component/ImageUploader';
|
|||
|
|
|
|||
|
|
function App() {
|
|||
|
|
const [ form ] = Form.useForm();
|
|||
|
|
return (
|
|||
|
|
<Form>
|
|||
|
|
<Form.Item
|
|||
|
|
label="上传图片"
|
|||
|
|
name="imageUrl"
|
|||
|
|
getValueProps={getValueProps}
|
|||
|
|
getValueFromEvent={getValueFromEvent}
|
|||
|
|
>
|
|||
|
|
<ImageUploader action={`${window.process.env.app.API_HOST}/attachment/files/upload-speed-simple`} />
|
|||
|
|
</Form.Item>
|
|||
|
|
</Form>
|
|||
|
|
);
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API
|
|||
|
|
|
|||
|
|
| 属性 | 说明 | 类型 | 默认值 |
|
|||
|
|
|-----------------|:-----------------------------|:-------------------------------------------------------------------|:------|
|
|||
|
|
| wh | 宽高比 | `string` | 50*50 |
|
|||
|
|
| tip | 提示文本 | `string` | 点击上传 |
|
|||
|
|
| size | 文件大小，单位：KB | `number` | 5120 |
|
|||
|
|
| data | 额外的数据 | `Record<string, any>` | - |
|
|||
|
|
| value | 值，受控 | `any` | - |
|
|||
|
|
| width | 组件宽度 | `number` | 120 |
|
|||
|
|
| height | 组件高度 | `number` | 120 |
|
|||
|
|
| action | 上传地址 | `string` | - |
|
|||
|
|
| preview | 是否支持预览 | `boolean` | true |
|
|||
|
|
| disabled | 是否禁用 | `boolean` | false |
|
|||
|
|
| fieldName | 上传文件的字段名 | `string` | file |
|
|||
|
|
| borderStyle | 边框样式 | `string` | dashed |
|
|||
|
|
| borderColor | 边框颜色 | `string` | #d9d9d9 |
|
|||
|
|
| borderWidth | 边框宽度 | `number` | 1 |
|
|||
|
|
| borderRadius | 边框圆角 | `number` | 2 |
|
|||
|
|
| cropper | 是否开启裁剪 | `boolean` | false |
|
|||
|
|
| cropperConfig | 裁剪配置，`cropper`为`true`时有效 | `CropperConfig` | - |
|
|||
|
|
| backgroundColor | 背景颜色 | `string` | #fafafa |
|
|||
|
|
| customRequest | 自定义请求 | `(res: {data: any}) => void \| Promise<{fileId: string, fileUrl: string}>` | - |
|
|||
|
|
| onChange | 受控值改变回调 | `(value: any) => void` | - |
|
|||
|
|
| compression | 是否支持压缩 | `boolean` | false |
|
|||
|
|
| compressionConfig | 压缩配置，`compression`为`true`时有效 | `CompressionConfig` | - |
|
|||
|
|
| needToken | 是否需要token | `boolean` | true |
|
|||
|
|
|
|||
|
|
## CropperConfig 裁剪配置
|
|||
|
|
|
|||
|
|
| 属性 | 说明 | 类型 | 默认值 |
|
|||
|
|
|------|:----------|:--------|:------|
|
|||
|
|
| width | 宽度 | `number` | 400 |
|
|||
|
|
| height | 高度 | `number` | 400 |
|
|||
|
|
| locked | 锁定不可缩放裁剪框 | `boolean` | false |
|
|||
|
|
| aspect | 宽高比 | `number` | 16 / 9 |
|
|||
|
|
|
|||
|
|
## CompressionConfig 压缩配置
|
|||
|
|
|
|||
|
|
| 属性 | 说明 | 类型 | 默认值 |
|
|||
|
|
|---------|:-----|:----------------------|:----|
|
|||
|
|
| quality | 压缩质量 | `number` | 0.6 |
|
|||
|
|
| backType | 压缩类型 | `file` \| `base64` | file |
|
|||
|
|
|
|||
|
|
## Form表单辅助
|
|||
|
|
|
|||
|
|
- `getValueFromEvent`
|
|||
|
|
- `getValueProps`
|