# 变更记录
| 产品版本 | 更新内容 | 更新日期 |
| --- | --- | --- |
| V6.0.9 | 完善了PC端长日期范围控件，支持二开参数配置开始日期和结束日期的默认时分秒，满足用户使用需求 | 2024-04-10 |
| V7.0.1 | 完善了短日期范围字段，支持格式化为yyyy或yyyy-MM，以满足选择年份范围或月份范围的场景 | 2024-10-24 |
# 1 功能介绍
用于选择日期范围的控件。结合 *字段布局面板 *控件使用，布局体验最佳。
# 2 控件对象
`kd.bos.form.field.DateRangeEdit`
# 3 视觉展示
* 选择短日期范围（默认态）
* 选择长日期范围（默认态）
* 选择月份范围（区域格式为短日期，格式化设置yyyy-MM）
* 选择年份范围（区域格式为短日期，格式化设置yyyy）
# 4 属性说明
## 4.1 通用属性
>通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976)
## 4.2 样式属性
>样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336)
## 4.3 业务属性
| 属性名 | 类型 | 默认值 | 说明 | 支持版本 |
| --- | --- | --- | --- | --- |
| 缺省值 | 日期范围选择 | - | 设置默认展示的日期范围 | |
| 开始标识 | 文本 | - | 开始日期标识 | |
| 结束标识 | 文本 | - | 结束日期标识 | |
| 开始字段名 | 文本 | - | 开始日期数据库字段名 | |
| 结束字段名 | 文本 | - | 结束日期数据库字段名 | |
| 区域类型 | 下拉 | 短日期 | 控制日期范围字段显示为短日期格式或者长日期格式，1为短日期，2为长日期 | |
| 为空提示信息 | 文本 | - | 当字段内容为空时，输入框内显示的信息 | |
| 格式化 | 文本 | - | 当区域类型为短日期时，可通过该属性设置日期选择面板的交互形态，如年份范围，月份范围等 | V7.0.1 |
### 4.3.1 默认时刻
6.0.9版本新增 `defaultTime` 属性，二开可通过插件进行长日期范围字段的默认时分秒属性设置：
```
// 单头、卡片字段
this.getView().updateControlMetadata('kdtest_daterangefield', { defaultTime: ["10:10:10", "10:10:59"]})
// 分录字段
var clientViewProxy = this.getView().getClientProxy()
clientViewProxy.invokeControlMethod('entryentity', 'setColEditorProp', ['kdtest_daterangefield1', 'defaultTime', ["10:10:10", "10:10:59"]])
```
# 5 插件示例
## 5.1 控件编程模型
### 5.1.1 控件编程模型定义
日期范围字段的控件编程模型是DateRangeEdit，派生自字段基类的控件编程模型FieldEdit：
```java
package kd.bos.form.field;
public class DateRangeEdit extends FieldEdit implements ICloseCallBack {
```
### 5.1.2 控件方法清单
DateRangeEdit重写、新增的方法：
| 方法 | 来源 | 说明 |
| --- | --- | --- |
| bindData | 重写 | 系统刷新界面数据时，调用此方法生成绑定到前端的日期范围值（包括开始日期、结束日期） |
| closedCallBack | 新增 | 日期范围浮层录入结束后调用，获取用户录入的日期范围，填写到数据模型中 |
| focus | 新增 | 前端日期范围获取焦点时调用，显示日期范围录入浮层 |
| getBindingValue | 新增 | 输出开始日期或结束日期的值 |
| getDefaultFilters | 重写 | 系统构建单据过滤字段时调用，生成日期范围过滤字段（包括开始日期、结束日期） |
| getEndDateFieldKey | 新增 | 结束日期标识，默认为日期范围标识 + _enddate |
| getStartDateFieldKey | 新增 | 开始日期标识，默认为日期范围标识 + _startdate |
| postBack | 重写 | 用户在前端录入日期返回后调用， 接收用户录入的日期，填写到数据模型中 |
| setEndDateFieldKey | 新增 | |
| setStartDateFieldKey | 新增 | |
## 5.2 数据模型
日期范围字段运行时，表单主实体模型会创建两个属性对象，分别存储开始时间、结束时间。属性对象的类型为DateTimeProp，与长日期字段的属性对象类型相同。
* 开始时间标识，默认为日期范围+”_startdate”;
* 结束时间标识，默认为日期范围+”_enddate”；
可以在设计时，手工指定。
日期范围字段运行时，可以通过控件编程模型 DateRageEdit 的 getStartDateFieldKey() 方法，获取开始时间标识；通过 getEndDateFieldKey() 方法，获取结束时间标识。
开始时间、结束时间的值均为Date类型，带时分秒。
如下示例代码，演示如何存取单据头日期范围字段的值：
```java
/**
* 演示如何存取字段值，只演示了存取单据头字段值
*/
private void demoFieldValue(){
// 需要通过如下方式，获取日期范围字段，开始、结束属性对象的标识
DateRangeEdit headFieldEdit = this.getView().getControl(KEY_HEADDATERANGE);
String key_headdatestart = headFieldEdit.getStartDateFieldKey();
String key_headdateend = headFieldEdit.getEndDateFieldKey();
// 获取单据头日期范围，开始时间、结束时间
Date headdatestart = (Date) this.getModel().getValue(key_headdatestart);
Date headdateend = (Date) this.getModel().getValue(key_headdateend);
// 赋值
this.getModel().setValue(key_headdatestart, headdatestart);
this.getModel().setValue(key_headdateend, headdateend);
}
```
### 5.3 插件事件
日期范围字段包括开始日期、结束日期两个属性，修改字段值时，会触发两次值改变事件。
除了值改变事件，未再提供其他插件事件。
| 事件 | 触发时机 |
| --- | --- |
| beforePropertyChanged | 修改字段值之前触发；
例外：界面数据初始时，不触发此事件，即在afterCreateNewData事件中，修改字段值，不会触发此事件 |
| propertyChanged | 修改字段值之后触发；
例外：界面数据初始时，不触发此事件，即在afterCreateNewData事件中，修改字段值，不会触发此事件 |
### 5.3.1 beforePropertyChanged 事件
事件的触发时机及案例，参阅[beforePropertyChanged事件介绍](https://vip.kingdee.com/article/228912833495534592)
代码模板需要区分开始日期、结束日期：
```java
package kd.bos.plugin.sample.dynamicform.pcform.field.template;
import kd.bos.dataentity.utils.StringUtils;
import kd.bos.entity.datamodel.events.PropertyChangedArgs;
import kd.bos.form.plugin.AbstractFormPlugin;
public class DateRangePropertyChanged extends AbstractFormPlugin{
private final static String KEY_STARTDATE1 = "startdate1";
private final static String KEY_ENDDATE1 = "enddate1";
@Override
public void propertyChanged(PropertyChangedArgs e) {
String fieldKey = e.getProperty().getName();
if (StringUtils.equals(KEY_STARTDATE1, fieldKey)){
// 开始日期值改变
// TODO 在此添加业务逻辑
}
else if (StringUtils.equals(KEY_ENDDATE1, fieldKey)){
// 结束日期值改变
// TODO 在此添加业务逻辑
}
}
}
```
### 5.3.2 propertyChanged 事件
事件的触发时机及案例，参阅[propertyChanged事件介绍](https://vip.kingdee.com/article/228917111786574080)
代码模板需要区分开始日期、结束日期：
```java
package kd.bos.plugin.sample.dynamicform.pcform.field.template;
import kd.bos.dataentity.utils.StringUtils;
import kd.bos.entity.datamodel.events.PropertyChangedArgs;
import kd.bos.form.plugin.AbstractFormPlugin;
public class DateRangeBeforePropertyChanged extends AbstractFormPlugin {
private final static String KEY_STARTDATE1 = "startdate1";
private final static String KEY_ENDDATE1 = "enddate1";
@Override
public void beforePropertyChanged(PropertyChangedArgs e) {
String fieldKey = e.getProperty().getName();
if (StringUtils.equals(KEY_STARTDATE1, fieldKey)){
// 开始日期值改变
// TODO 在此添加业务逻辑
}
else if (StringUtils.equals(KEY_ENDDATE1, fieldKey)){
// 结束日期值改变
// TODO 在此添加业务逻辑
}
}
}
```
