Calendar

Calendar - 日历 组件用来组织和展示日历事件。

calendar week

组件的 XML 名称:calendar

视图模式

日历组件有三种查看模式,根据 calendar 展示日期的范围自动选择,日期范围由 startDateendDate 属性定义:

  1. 月视图 - 当日历范围大于 7 天时。

    <calendar id="monthlyView"
              captionProperty="caption"
              startDate="2021-05-01"
              endDate="2021-05-17"
              height="100%"
              width="100%"
              lastVisibleDayOfWeek="5"/>
    calendar monthly view
  2. 周视图 - 当日历范围大于 1 天,小于 7 天时。

    <calendar id="weeklyView"
              captionProperty="caption"
              startDate="2021-05-01"
              endDate="2021-05-07"
              height="100%"
              width="100%"/>
    calendar weekly view
  3. 日视图 - 当日历范围小于 1 天时。

    <calendar id="singleDay"
              captionProperty="caption"
              startDate="2021-05-01"
              endDate="2021-05-01"
              height="100%"
              width="100%"/>
    calendar single day view

自定义

默认情况下,calendar 展示一周 7 天,每天 24 个小时。如需修改,有以下属性可以配置:

  • firstVisibleDayOfWeeklastVisibleDayOfWeek - 取值范围 1 ~ 71 表示星期日,7 表示星期六。

  • firstVisibleHourOfDaylastVisibleHourOfDay - 取值范围 1 ~ 231 表示 01:00 am,23 表示 23:00 pm。

例如,我们可以这样自定义:

  1. 当日历以日视图打开时,只展示每天的前半天。

  2. 当日历以月视图打开时,每周只展示周二和周三。

<calendar id="customized"
          captionProperty="caption"
          startDate="2021-05-01"
          endDate="2021-05-30"
          firstVisibleHourOfDay="6"
          lastVisibleHourOfDay="12"
          firstVisibleDayOfWeek="3"
          lastVisibleDayOfWeek="4"
          height="400px"
          width="500px"
          navigationButtonsVisible="true"/>
calendar customized

还可以使用 weeklyCaptionFormat 修改一周每天的标题。SimpleDateFormat 类的规则定义 weeklyCaptionFormat 值的格式。

如需修改时间格式,可以使用 timeFormat 属性:

  • 24H

  • 12H - 默认值。

如需修改星期和月的名称,则用 setDayNames()setMonthNames() 方法,传入新值的映射:

@Autowired
private Calendar<Date> customizedCalendar;

@Subscribe
public void onInit(InitEvent event) {
    Map<DayOfWeek, String> days = new HashMap<>(7);
    days.put(DayOfWeek.MONDAY,"Moon");
    days.put(DayOfWeek.TUESDAY,"Mars");
    days.put(DayOfWeek.WEDNESDAY,"Mercury");
    days.put(DayOfWeek.THURSDAY,"Jupiter");
    days.put(DayOfWeek.FRIDAY,"Venus");
    days.put(DayOfWeek.SATURDAY,"Saturn");
    days.put(DayOfWeek.SUNDAY,"Sun");
    customizedCalendar.setDayNames(days);
}
calendar customized captions

日历事件

编程式创建事件

  1. 如需展示日历事件,可以用 CalendarEventProvider 接口的 addEvent() 方法为日历添加 SimpleCalendarEvent

    @Autowired
    private Calendar<Date> calendar;
    
    @Subscribe
    public void onInit(InitEvent event) {
        SimpleCalendarEvent<Date> simpleCalendarEvent = new SimpleCalendarEvent<>();
    
        SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm");
    
        simpleCalendarEvent.setCaption("Development");
        simpleCalendarEvent.setDescription("Platform development");
        simpleCalendarEvent.setStart(simpleDateFormat.parse("2021-05-26 15:00", new ParsePosition(0)));
        simpleCalendarEvent.setEnd(simpleDateFormat.parse("2021-05-26 19:00", new ParsePosition(0)));
        simpleCalendarEvent.setAllDay(false);
    
        calendar.getEventProvider().addEvent(simpleCalendarEvent);
    }
  2. 还可以使用 setEventProvider() 方法为日历添加 SimpleCalendarEvent 对象列表,该方法接收 ListCalendarEventProvider 对象作为参数。

  3. 如需删除事件,可以用 CalendarEventProvider 接口的 removeEvent()removeAllEvents() 方法。

数据感知事件

CalendarEventProvider 接口有一个实现是 ContainerCalendarEventProvider,通过这个实现可以用数据模型实体填充日历事件。

使用 ContainerCalendarEventProvider 时,事件实体对象必须至少包含两个属性(数据类型为 date 类型 之一)映射至日历的 startDatePropertyendDateProperty 属性,以及一个 String 类型的属性映射至 captionProperty 属性:

@JmixEntity
@Table(name = "UIEX1_CUSTOM_CALENDAR_EVENT")
@Entity(name = "uiex1_CustomCalendarEvent")
public class CustomCalendarEvent {
    @JmixGeneratedValue
    @Column(name = "ID", nullable = false)
    @Id
    private UUID id;

    @Column(name = "EVENT_CAPTION")
    private String eventCaption;

    @Column(name = "EVENT_START_DATE")
    @Temporal(TemporalType.TIMESTAMP)
    private Date eventStartDate;

    @Column(name = "EVENT_END_DATE")
    @Temporal(TemporalType.TIMESTAMP)
    private Date eventEndDate;

}

此外,也可以为 String 类型的 descriptionPropertystylenameProperty 以及 Boolean 类型的 isAllDayProperty 属性定义映射属性。

示例:

<data readOnly="true">
    <collection id="customCalendarEventsDc"
                class="ui.ex1.entity.CustomCalendarEvent">
        <fetchPlan extends="_base"/>
        <loader id="customCalendarEventsDl">
            <query>
                <![CDATA[select e from uiex1_CustomCalendarEvent e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <calendar dataContainer="customCalendarEventsDc"
              width="800px"
              height="400px"
              firstVisibleHourOfDay="8"
              firstVisibleDayOfWeek="2"
              lastVisibleDayOfWeek="6"
              lastVisibleHourOfDay="20"
              captionProperty="eventCaption"
              startDateProperty="eventStartDate"
              endDateProperty="eventEndDate"
              weeklyCaptionFormat="yyyy-dd-MM"/>
</layout>
calendar data aware

事件和处理器

如需使用 Jmix Studio 生成处理器的桩代码,需要在界面 XML 描述或者 Component Hierarchy 面板选中该组件,然后用 Component Inspector 面板的 Handlers 标签页生成。

或者可以使用界面控制器顶部面板的 Generate Handler 按钮。

ContextHelpIconClickEvent

编程式使用:调用 setContextHelpIconClickHandler() 组件方法。

CalendarDateClickEvent

当用户点击月中一天时会触发此事件。

编程方式注册该事件监听器,请使用 addDateClickListener() 组件方法。

CalendarEventClickEvent

当用户点击日历事件时会触发此事件。=

编程方式注册该事件监听器,请使用 addEventClickListener() 组件方法。

CalendarEventResizeEvent

当用户调整日历事件大小时会触发此事件。

编程方式注册该事件监听器,请使用 addEventResizeListener() 组件方法。

CalendarEventMoveEvent

当用户移动日历事件时会触发此事件。

编程方式注册该事件监听器,请使用 addEventMoveListener() 组件方法。

CalendarWeekClickEvent

当用户点击星期数字时时会触发此事件。

编程方式注册该事件监听器,请使用 addWeekClickListener() 组件方法。

CalendarForwardClickEvent

当用户点击前进导航按钮时会触发此事件。

编程方式注册该事件监听器,请使用 addForwardClickListener() 组件方法。

CalendarBackwardClickEvent

当用户后退导航按钮时会触发此事件。

编程方式注册该事件监听器,请使用 addBackwardClickListener() 组件方法。

CalendarRangeSelectEvent

当用户按下鼠标拖拽选择一个时间范围时会触发此事件。

编程方式注册该事件监听器,请使用 addRangeSelectListener() 组件方法。

CalendarDayClickEvent

当用户点击一天内的空闲时间时会触发此事件。

编程方式注册该事件监听器,请使用 addDayClickListener() 组件方法。

样式

可以用 CSS 设置日历事件的样式。创建一个 自定义主题,然后在 SCSS 文件中按需定义样式名称和参数,示例:

.v-calendar-event.event-red {
  background-color: #f4c8c8;
  color: #e00000;
}

然后可以在界面控制器中编程式的设置上面创建的样式了:

simpleCalendarEvent.setStyleName("event-red");

或者用 stylenameProperty 属性,在实体中指定一个字段包含创建的样式名作为该属性的映射。