3.5.2.1.5. 日历控件

在线示例

API 文档

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

gui calendar 1

该组件的 XML 名称是: calendar

以下为界面中日历组件定义的示例:

  1. <calendar id="calendar"
  2. captionProperty="caption"
  3. startDate="2016-10-01"
  4. endDate="2016-10-31"
  5. height="100%"
  6. width="100%"/>

该组件在界面上的外观取决于日历的日期范围,日期范围由开始日期和结束日期定义。默认外观为周视图,对应的日期范围上限是一周七天。如果需要按天展示则把日期范围定义为一天以内。如果日期范围在七天以上,该组件将以月视图展示。

用来将日历控件往前或往后调一周的导航按钮默认不可见。可以通过设置属性 navigationButtonsVisible 使导航按钮可见(在周视图中):

  1. <calendar width="100%"
  2. height="100%"
  3. navigationButtonsVisible="true"/>

gui calendar 2

calendar 日历控件的属性:

  • endDate - 日期范围中的结束日期。
  • endDateProperty - 包含结束日期的实体属性名称。
  • descriptionProperty - 包含事件描述的实体属性名称。
  • isAllDayProperty - 标识是否为全天事件的实体属性名称。
  • startDate - 日期范围中的开始日期。
  • startDateProperty - 包含开始时间的是实体属性名称。
  • stylenameProperty - 标识事件样式名称的实体属性名称。
  • timeFormat - 时间格式: 12H 或 24H。

    如何使用日历事件:

    需要在日历控件单元格中显示事件时,可以通过 addEvent() 方法添加一个事件到 Calendar 对象;也可以使用 CalendarEventProvider 接口操作。 直接添加事件到对象的示例:

    1. @Inject
    2. private Calendar calendar;
    3. public void generateEvent(String caption, String description, Date start, Date end, boolean isAllDay, String stylename) {
    4. SimpleCalendarEvent calendarEvent = new SimpleCalendarEvent();
    5. calendarEvent.setCaption(caption);
    6. calendarEvent.setDescription(description);
    7. calendarEvent.setStart(start);
    8. calendarEvent.setEnd(end);
    9. calendarEvent.setAllDay(isAllDay);
    10. calendarEvent.setStyleName(stylename);
    11. calendar.getEventProvider().addEvent(calendarEvent);
    12. }

    CalendarEventProvider 接口的 removeEvent() 方法可以通过指定索引删除事件:

    1. CalendarEventProvider eventProvider = calendar.getEventProvider();
    2. List<CalendarEvent> events = new ArrayList<>(eventProvider.getEvents());
    3. eventProvider.removeEvent(events.get(events.size()-1));

    removeAllEvents 方法依次删除所有事件:

    1. CalendarEventProvider eventProvider = calendar.getEventProvider();
    2. eventProvider.removeAllEvents();

    有两个给日历控件添加事件数据的接口:ListCalendarEventProvider (默认创建) 和 EntityCalendarEventProvider

    ListCalendarEventProvideraddEvent() 方法需要 CalendarEvent 对象做为输入参数:

    1. @Inject
    2. private Calendar calendar;
    3. public void addEvents() {
    4. ListCalendarEventProvider listCalendarEventProvider = new ListCalendarEventProvider();
    5. calendar.setEventProvider(listCalendarEventProvider);
    6. listCalendarEventProvider.addEvent(generateEvent(
    7. "Training", "Student training", "2016-10-17 09:00", "2016-10-17 14:00", false, "event-blue"));
    8. listCalendarEventProvider.addEvent(generateEvent(
    9. "Development", "Platform development", "2016-10-17 15:00", "2016-10-17 18:00", false, "event-red"));
    10. listCalendarEventProvider.addEvent(generateEvent(
    11. "Party", "Party with friends", "2016-10-22 13:00", "2016-10-22 18:00", false, "event-yellow"));
    12. }
    13. private SimpleCalendarEvent generateEvent(String caption, String description, String start, String end, Boolean allDay, String style) {
    14. SimpleCalendarEvent calendarEvent = new SimpleCalendarEvent();
    15. SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm");
    16. calendarEvent.setCaption(caption);
    17. calendarEvent.setDescription(description);
    18. calendarEvent.setStart(df.parse(start));
    19. calendarEvent.setEnd(df.parse(end));
    20. calendarEvent.setAllDay(allDay);
    21. calendarEvent.setStyleName(style);
    22. return calendarEvent;
    23. }

    EntityCalendarEventProvider 可以直接将事件实体对象添加为日历的事件。事件实体对象必须 至少 包含事件开始日期(DateTime 类型)、事件结束日期(DateTime 类型)和事件标题(String 类型)。

    以下示例中假设事件数据源包含了所有需要的属性: eventCaptioneventDescriptioneventStartDateeventEndDateeventStylename, 他们的值将会设置到 calendar 组件的属性中:

    1. <calendar id="calendar"
    2. datasource="calendarEventsDs"
    3. width="100%"
    4. height="100%"
    5. startDate="2016-10-01"
    6. endDate="2016-10-31"
    7. captionProperty="eventCaption"
    8. descriptionProperty="eventDescription"
    9. startDateProperty="eventStartDate"
    10. endDateProperty="eventEndDate"
    11. stylenameProperty="eventStylename"/>

Calendar 组件支持几个用来响应用户交互事件的监听器,比如日期、周标题,日期/事件范围选择,事件拖拽或者事件大小调整,往前或往后调日期的导航按钮。以下是监听器列表:

  • addDateClickListener(CalendarDateClickListener listener); - 日期点击监听器:

    1. calendar.addDateClickListener(
    2. calendarDateClickEvent ->
    3. notifications.create()
    4. .withCaption(String.format("Date clicked: %s", calendarDateClickEvent.getDate().toString()))
    5. .show());
  • addWeekClickListener() - 周点击监听器。
  • addEventClickListener() - 日历事件点击监听器。
  • addEventResizeListener() - 日历事件大小调整监听器。
  • addEventMoveListener() - 事件拖拽、释放监听器。
  • addForwardClickListener() - 往前调日期导航钮的监听器。
  • addBackwardClickListener() - 往后调日期导航钮的监听器。
  • addRangeSelectListener() - 日历日期范围选择监听器。

日历事件可以通过 CSS 配置样式。需要配置 CSS 的样式时,创建一个样式名字,然后在 .scss 文件中设置需要的参数。例如,需要配置事件的背景颜色时:

  1. .v-calendar-event.event-green {
  2. background-color: #c8f4c9;
  3. color: #00e026;
  4. }

然后通过事件的 setStyleName 方法设置样式名字:

  1. calendarEvent.setStyleName("event-green");

然后,事件的背景会被设置为绿色:

gui calendar 3

如果需要改变 Calendar 日历控件上日期和月份的名称,可以通过方法 setDayNames()setMonthNames() 实现,传入带新名称的 map 即可:

  1. Map<DayOfWeek, String> days = new HashMap<>(7);
  2. days.put(DayOfWeek.MONDAY,"Heavens and earth");
  3. days.put(DayOfWeek.TUESDAY,"Sky");
  4. days.put(DayOfWeek.WEDNESDAY,"Dry land");
  5. days.put(DayOfWeek.THURSDAY,"Stars");
  6. days.put(DayOfWeek.FRIDAY,"Fish and birds");
  7. days.put(DayOfWeek.SATURDAY,"Animals and man");
  8. days.put(DayOfWeek.SUNDAY,"Rest");
  9. calendar.setDayNames(days);

Calendar 日历控件的属性列表

caption - captionAsHtml - captionProperty - colspan - datasource - contextHelpText - contextHelpTextHtmlEnabled - css - description - descriptionAsHtml - descriptionProperty - endDateProperty - endDate - box.expandRatio - height - icon - id - isAllDayProperty - rowspan - startDate - startDateProperty - stylename - stylenameProperty - timeFormat - visible - width

API

addEvent - removeAllEvents - removeEvent - setEventProvider - setDayNames

监听器

CalendarBackwardClickListener - CalendarDateClickListener - CalendarEventClickListener - CalendarEventMoveListener - CalendarEventResizeListener - CalendarForwardClickListener - CalendarRangeSelectListener - CalendarWeekClickListener