# 变更记录 | 产品版本 | 更新内容 | 更新日期 | | --- | --- | --- | | V7.0.1 | 增加了图片裁剪尺寸功能，适用于对头像等图片有固定比例要求的使用场景，提升用户体验 | 2024-10-24 | # 1 功能介绍 此字段用于上传单张图片，结合 字段布局面板 控件使用可以得到最佳的布局体验。 # 2 控件对象 `kd.bos.form.field.PictureEdit` # 3 视觉展示 * 默认  * 高或宽小于56px  * 开启 允许裁剪 属性后  # 4 属性说明 ## 4.1 通用属性 >通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976) ## 4.2 样式属性 >样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336) ## 4.3 业务属性 | 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | 默认显示缩略图 | 下拉 | - | | | 放大镜 | 复选框 | false | 鼠标悬停时，局部放大图片细节 | | 缩略图参数 | 弹框选择 | | 设置图片上传后的缩略参数 | | 背景图片 | 弹框选择 | - | 设置图片的背景图片，详见4.3.1 | | 默认图片 | 弹框选择 | - | 设置图片的默认图片，详见4.3.2 | | 最大图片大小 | 整数 | - | 设置可上传的最大图片的大小，默认单位为Mb | | 锁定预览 | 复选框 | true | 设置图片在锁定状态下是否可以点击预览 | | 允许裁剪 | 复选框 | false | 设置图片是否允许裁剪，详见4.3.3 | | 裁剪比例 | 下拉 | - | 开启允许裁剪后，设置对图片的裁剪比例 | | 加密存储 | 复选框 | false | 设置文本是否加密存储 | ### 4.3.1 背景图片 用于设置图片字段的背景图片 ### 4.3.2 默认图片 设置默认的图片，在进入表单后，如果图片字段无内容，则会显示该图片。 与背景图片的区别在于，设置默认图片后，鼠标移动到字段上时，会添加图片的蒙层。 ### 4.3.3 允许裁剪 设置图片是否允许裁剪，启用允许裁剪的话，则在图片上传前会弹出裁剪框，进行图片编辑。 ### 4.4 允许上传的图片格式 默认情况下，图片字段允许上传格式为: .webp,.webp,.webp,.webp,.webp # 5 图片接口介绍 ## 5.1 控件编程模型 ### 5.1.1 控件编程模型定义 图片字段的控件编程模型PictureEdit，派生自字段控件编程模型基类FieldEdit： ```java package kd.bos.form.field; public class PictureEdit extends FieldEdit implements ISuportClick { ``` ### 5.1.2 控件方法清单 PictureEdit重写、新增的方法： | 方法 | 来源 | 说明 | | --- | --- | --- | | addClickListener | 新增 | 监听图片点击事件 | | addItemClickListener | 新增 | 监听图片子菜单点击事件 | | click | 新增 | 用户点击前端图片时，系统调用此方法：
触发图片点击插件事件 | | getOperationKey | 新增 | 暂未使用 | | getOriginalPictrue | 新增 | 输出默认图片，在用户未设置图片时显示 | | getThumbnailsParams | 新增 | 缩略图配置 | | getThumbnailsURLs | 新增 | 缩略图配置 | | setOperationKey | 新增 | | | showPic | 新增 | 字段已经设置好了图片，用户点击时，调用此方法：
显示图片查看界面，查看原图 | ## 5.2 数据模型 图片字段的属性对象是PictureProp类型，派生自基类FieldProp，存储图片在文件服务器上地址，String类型： ```java package kd.bos.entity.property; public class PictureProp extends FieldProp { ``` ## 5.3 插件事件 单据头上的图片字段，除了标准字段的值改变事件，未提供其他插件事件： | 事件 | 触发时机 | | --- | --- | | beforePropertyChanged | 修改字段值之前触发；
例外：界面数据初始时，不触发此事件，即在afterCreateNewData事件中，修改字段值，不会触发此事件 | | propertyChanged | 修改字段值之后触发；
例外：界面数据初始时，不触发此事件，即在afterCreateNewData事件中，修改字段值，不会触发此事件 | 放在单据体中的图片，则还提供了点击事件，供插件显示图片上传界面： | 事件 | 触发时机 | | --- | --- | | beforeClick | 用户点击文本字段的按钮时，触发此事件 | | click | 用户点击文本字段的按钮时，触发此事件 | ### 5.3.1 beforeClick 事件 事件详情可查看[beforeClick事件](https://vip.kingdee.com/article/228984722725409536)。 * 事件触发时机 用户点击单据体上的图片时，触发此事件。插件可以在此事件取消后续点击处理。 * 代码模板 ```java package kd.bos.plugin.sample.dynamicform.pcform.field.template; import java.util.EventObject; import kd.bos.dataentity.utils.StringUtils; import kd.bos.form.control.Control; import kd.bos.form.control.events.BeforeClickEvent; import kd.bos.form.plugin.AbstractFormPlugin; public class PictureFieldBeforeClick extends AbstractFormPlugin { private final static String KEY_PICTUREFIELD1 = "picturefield1"; @Override public void registerListener(EventObject e) { super.registerListener(e); // 侦听单据体图片字段点击事件 this.addClickListeners(KEY_PICTUREFIELD1); } @Override public void beforeClick(BeforeClickEvent evt) { super.beforeClick(evt); Control source = (Control)evt.getSource(); if (StringUtils.equals(KEY_PICTUREFIELD1, source.getKey())){ // TODO 在此添加业务逻辑 } } } ``` * 事件参数 ```java public class BeforeClickEvent extends ClickEvent： public Object getSource()：事件源，字段的控件编程模型实例； public void setCancel(boolean cancel)：取消后续处理。 ``` ### 5.3.2 click 事件 事件详情可查看[click事件](https://vip.kingdee.com/article/228985226008129024)。 * 事件触发时机 用户点击单据体上的图片时，触发此事件。插件可以在此响应点击事件，打开自定义的图片、选择上传界面。 * 代码模板 ```java package kd.bos.plugin.sample.dynamicform.pcform.field.template; import java.util.EventObject; import kd.bos.dataentity.utils.StringUtils; import kd.bos.form.control.Control; import kd.bos.form.plugin.AbstractFormPlugin; public class PictureFieldClick extends AbstractFormPlugin { private final static String KEY_PICTUREFIELD1 = "picturefield1"; @Override public void registerListener(EventObject e) { super.registerListener(e); // 侦听单据体图片点击事件 this.addClickListeners(KEY_PICTUREFIELD1); } @Override public void click(EventObject evt) { super.click(evt); Control source = (Control)evt.getSource(); if (StringUtils.equals(KEY_PICTUREFIELD1, source.getKey())){ // TODO 在此添加业务逻辑 } } } ``` * 事件参数 ```java public class EventObject implements java.io.Serializable： public Object getSource()：事件源，字段的控件编程模型实例。 ``` ### 5.3.3 应用示例 1）案例说明：单据体上的图片字段，实现图片的选择、存储； 2）实现方案： 侦听、响应图片字段的click事件，弹出图片选择对话框； 响应子界面回调事件closedCallBack，接收返回的图片地址，填写到数据模型中； 如图：单据体中的图标字段，支持选择图片存入  3）实例代码： ```java package kd.bos.plugin.sample.dynamicform.pcform.field.bizcase; import java.util.EventObject; import java.util.Map; import kd.bos.dataentity.utils.StringUtils; import kd.bos.form.CloseCallBack; import kd.bos.form.FormShowParameter; import kd.bos.form.ShowType; import kd.bos.form.control.AbstractGrid; import kd.bos.form.control.Control; import kd.bos.form.events.ClosedCallBackEvent; import kd.bos.form.plugin.AbstractFormPlugin; public class PictureFieldClickSample extends AbstractFormPlugin { private final static String KEY_ENTRYENTITY = "entryentity"; private final static String KEY_PICTUREFIELD1 = "picturefield2"; @Override public void registerListener(EventObject e) { super.registerListener(e); // 侦听单据体图片字段点击事件 this.addClickListeners(KEY_PICTUREFIELD1); } @Override public void click(EventObject evt) { String key =((Control)evt.getSource()).getKey().toLowerCase(); if (StringUtils.equals(key, KEY_PICTUREFIELD1)){ // 响应单据体图片字段点击事件：显示图片选择器 this.showImageSelector(evt); } } /** * 图片选择器入口 * @param evt 点击事件 */ private void showImageSelector(EventObject evt) { FormShowParameter parameter=new FormShowParameter(); parameter.getOpenStyle().setShowType(ShowType.Modal); parameter.setFormId("ide_pictureselector"); parameter.setCloseCallBack(new CloseCallBack(this,KEY_PICTUREFIELD1)); this.getView().showForm(parameter); } /** * 返回选中的图片信息 */ @SuppressWarnings("unchecked") @Override public void closedCallBack(ClosedCallBackEvent evt) { if(evt.getReturnData()==null) return; // 未选择图片 if(StringUtils.equals(KEY_PICTUREFIELD1, evt.getActionId())){ // 获取单据体焦点行 AbstractGrid grid = this.getView().getControl(KEY_ENTRYENTITY); int row = grid.getEntryState().getFocusRow(); // 填写单据体图片字段值，要指定行号 Map<String, Object> imgData = (Map<String, Object>) evt.getReturnData(); this.getModel().setValue(KEY_PICTUREFIELD1, imgData.get("value"), row); } } } ```