# 变更记录 | **产品版本** | **更新内容** | **更新日期** | | --- | --- | --- | | V5.0.011 | 移动端图片支持裁剪，交互优化 | 2023-02-24 | | V6.0.1 | 移动列表图片字段支持点击预览 | 2023-10-18 | | V6.0.1 | 移动端图片字段添加标题行与帮助信息 | 2023-10-18 | # 1 功能介绍 1、用来上传图片的字段，只能上传一张图片。 2、只支持上传.webp、 .webp、.webp、 .webp、 .webp格式的图片。 # 2 控件对象 ``` kd.bos.form.field.PictureEdit ``` # 3 视觉展示 * 默认  * 开启 允许裁剪 属性后  # 4 属性说明 ## 4.1 通用属性 通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976) ## 4.2 样式属性 样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336) ## 4.3 业务属性 | **属性名** | **类型** | **默认值** | **说明** | 版本要求 | | --- | --- | --- | --- | --- | | 默认显示缩略图 | 下拉 | - | | | | 缩略图参数 | 弹框选择 | | 设置图片上传后的缩略参数 | | | 背景图片 | 弹框选择 | - | 设置图片的背景图片，详见4.3.1 | | | 默认图片 | 弹框选择 | - | 设置图片的默认图片，详见4.3.2 | | | 最大图片大小 | 整数 | - | 设置可上传的最大图片的大小，默认单位为Mb | | | 锁定预览 | 复选框 | true | 设置图片在锁定状态下是否可以点击预览 | | | 允许裁剪 | 复选框 | false | 设置图片是否允许裁剪，详见4.3.3 | v5.0.011 | | 加密存储 | 复选框 | false | 设置文本是否加密存储 | | | 显示标题 | 复现框 | false | 设置图片是否显示标题 | v6.0.1 | ### 4.3.1 背景图片 设置图片字段的背景图片：  ### 4.3.2 默认图片 设置默认的图片，在进入表单后，如果图片字段无内容的话，则会显示该图片：  ### 4.3.3 允许裁剪 设置图片是否允许裁剪，启用允许裁剪的话，则在图片上传前会弹出裁剪框，进行图片编辑：  ### 4.3.4 允许上传 卡片分录中，图片字段开启“允许上传”属性后即可上传图片，该属性默认开启 # 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); } } }