# 1 功能介绍
用于选择时间范的控件。结合 *字段布局面板 *控件使用，布局体验最佳。
# 2 控件对象
`kd.bos.form.field.TimeRangeEdit`
# 3 视觉展示
# 4 属性说明
## 4.1 通用属性
>通用属性包含字段和控件的一些公有的属性，如宽高，帮助文本等。请参考[通用属性](https://vip.kingdee.com/article/215559076720798976)
## 4.2 样式属性
>样式属性是每个控件在设计器右侧样式栏可以设置的属性，请参考[样式属性](https://vip.kingdee.com/article/252017936767406336)
## 4.3 业务属性
| 属性名 | 类型 | 默认值 | 说明 | |
| --- | --- | --- | --- | --- |
| 开始标识 | 文本 | - | 开始日期标识 | |
| 结束标识 | 文本 | - | 结束日期标识 | |
| 开始字段名 | 文本 | - | 开始日期数据库字段名 | |
| 结束字段名 | 文本 | - | 结束日期数据库字段名 | |
| 为空提示信息 | 文本 | - | 当字段内容为空时，输入框内显示的信息 | |
###
# 5 时间范围接口介绍
## 5.1 控件编程模型
时间范围字段的控件编程模型是TimeRangeEdit，派生自字段基类的控件编程模型FieldEdit：
```java
package kd.bos.form.field;
public class TimeRangeEdit extends FieldEdit {
```
TimeRangeEdit重写、新增的方法：
| 方法 | 来源 | 说明 |
| --- | --- | --- |
| getStartDateFieldKey | 新增 | 获取起始时间字段标识 |
| getEndDateFieldKey | 新增 | 获取结束时间字段标识 |
| getProperty | 重写 | 获取控件绑定的实体信息（优先返回起始时间字段实体属性，不存在时返回结束时间字段属性） |
## 5.2 数据模型
时间范围字段运行时，表单主实体模型会创建两个属性对象，分别存储开始时间、结束时间。属性对象的类型为TimeProp，与时间字段的属性对象类型相同。
开始时间标识、结束时间标识需要在设计器中手工输入。
日期范围字段运行时，可以通过控件编程模型TimeRangeEdit的getStartDateFieldKey()方法，获取开始时间标识；通过getEndDateFieldKey()方法，获取结束时间标识。
开始时间、结束时间的值均为int类型，其数值为当天零点（00:00:00）至已选时间所经过的秒数。若字段为空（即未填写），则使用-1表示。
如下示例代码，演示如何存取单据头时间范围字段的值：
```java
/**
* 演示如何存取字段值，只演示了单据头字段值
*/
private void setFieldValueDemo(){
//获取开始、结束字段属性的标识
TimeRangeEdit edit = this.getView().getControl("timerangefield");
String key_startTime = edit.getStartDateFieldKey();
String key_endTime = edit.getEndDateFieldKey();
int startValue = 3*60*60 + 3*60 + 3; // -> 03:03:03
int endValue = 4*60*60 + 4*60 +0;// -> 04:04:00
// 赋值
this.getModel().setValue(key_startTime, startValue);
this.getModel().setValue(key_endTime, endValue);
}
```
## 5.3 插件事件
时间范围字段包括开始时间、结束时间两个属性，修改字段值时，会触发两次值改变事件。
除了值改变事件，未再提供其他插件事件。
| 事件 | 触发时机 |
| --- | --- |
| beforePropertyChanged | 修改字段值之前触发；
例外：界面数据初始时，不触发此事件；即在afterCreateNewData事件中，修改字段值，不会触发此事件 |
| propertyChanged | 修改字段值之后触发；
例外：界面数据初始时，不触发此事件；即在afterCreateNewData事件中，修改字段值，不会触发此事件 |
### 5.3.1 beforePropertyChanged/PropertyChanged 事件
事件的触发时机及案例，参阅[beforePropertyChanged事件介绍](https://vip.kingdee.com/article/228912833495534592)、[propertyChanged事件介绍](https://vip.kingdee.com/article/228917111786574080)
代码模板，需要区分开始时间、结束时间：
```java
public class TimeRangePropertyChanged extends AbstractFormPlugin{
private final static String KEY_STARTTIME = "timerange_s";
private final static String KEY_ENDTIME = "timerange_e";
@Override
public void propertyChanged(PropertyChangedArgs e) {
String fieldKey = e.getProperty().getName();
if (StringUtils.equals(KEY_STARTTIME, fieldKey)){
// 开始时间值改变
// TODO 在此添加业务逻辑
}
else if (StringUtils.equals(KEY_ENDTIME, fieldKey)){
// 结束时间值改变
// TODO 在此添加业务逻辑
}
}
@Override
public void beforePropertyChanged(PropertyChangedArgs e) {
String fieldKey = e.getProperty().getName();
if (StringUtils.equals(KEY_STARTTIME, fieldKey)){
// 开始时间值改变
// TODO 在此添加业务逻辑
}
else if (StringUtils.equals(KEY_ENDTIME, fieldKey)){
// 结束时间值改变
// TODO 在此添加业务逻辑
}
}
}
```
