---
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`