safety-eval-service-frontend/.cursor/skills/specs/10-通用业务组件使用规范/02-图片上传组件/SKILL.md

name	description
jjb-image-uploader	定义 JJB 图片上传组件使用规范。在使用 ImageUploader、getValueProps、getValueFromEvent 或 Form.Item 集成时使用。必须参考 MD/d.ts 文档。

通用业务组件使用规范

图片上传组件

⚠️ 重要约束：本章节所有组件必须严格参考 node_modules 中对应依赖包的 MD 文档或 d.ts 文件！不得猜测组件属性！

使用

import ImageUploader, {
  getValueProps,
  getValueFromEvent,
} from '@cqsjjb/jjb-react-admin-component/ImageUploader'

集成规范

必须通过 Form.Item 的 getValueProps 与 getValueFromEvent 属性实现数据的双向绑定与转换。

实现逻辑

• getValueProps：将表单内部的图片 URL 转换为组件所需的格式。
• getValueFromEvent：拦截组件的上传事件，提取接口返回的图片地址并同步至表单状态。

代码演示

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