SAP UI5应用DatePicker控件的设计明细

Recently in order to resolve customer incidents, I need to study more details about DatePicker control. I share what I have learned in this blog.

What does DatePicker look like

There is a small window icon, by clicking it, you can choose any date from popped up calendar.

How to define DatePicker in xml view

<caui:DatePicker id="td"
          value="{path: 'vm>/ToDate', type:'sap.ui.model.type.Date', formatOptions: { style: 'long'}}"
          change="onToDateChanged"></caui:DatePicker>

– namespace for caui: xmlns:caui=”sap.ca.ui” – onToDateChanged is event handler defined in application ( consumer ). The event name is: “change”.

Implementation of DatePicker.js

You can find source code via the path: sap/ca/ui/DatePicker.js.

By reading the source code, here are some keynotes:

(1) The DatePicker is a composite control, which holds a calendar control internally. This could be known by line 38 ( reference this._oCalendar points to the internal calendar control ).

(2) The DatePicker has sap.m.InputBase as its prototype ( line 34 ). (3) The DatePicker has two properties defined in metadata. To be exactly, there are three. The third is “Value” which comes from the prototype “sap.m.InputBase”.

properties: {
            "firstDayOffset": {
                type: "int",
                group: "Data",
                defaultValue: 0
            },
            "dateValue": {
                type: "string",
                group: "Misc",
                defaultValue: null
            }
} 

(4) Whenever there is selection change in DatePicker, it will call fireChange and finally event “change” is issued. This is reason why you have to bind your event listener to “change” event in xml view. You can also find that two values ( newValue, newYyyymmdd) are passed to event listener as parameters. We will debug it later.

sap.ca.ui.DatePicker.prototype.fireChange = function(u) {
    if (!this._dateType) {
        this._setUpDateType();
    }
    var c = this.getValue();
    var t = this._validateDate(c);
    if (u || u === undefined) {
        this.dateObj = t;
    }
    this.setDateValue(t);
    var d = null ;
    if (t) {
        d = this._toDateStringYYYYMMDD(t);
    }
    this.fireEvent("change", {
        newValue: c,
        newYyyymmdd: d,
        invalidValue: t ? false : true
    });
    return this;
}

Implementation of Calendar.js

Do Element inspection via Chrome development tool, for example inspect the UI area for Oct-16, you can find the area actually consists of a span node with value 16 and another hidden input with content “Fri Oct 16 2015”.

Scroll down and you can find more divs which represent the corresponding date in UI.

When and where are these divs generated?

(1) In the init function of DatePicker, it fetches the prefix for each day which is used to render the content of hidden input element as introduced before.

The same logic for month abbreviation name:

(2) When you click the small icon of DatePicker, the calendar is to be rendered. Thus the render function of CalendarRender.js is called. Here below is the logic to populate span node and hidden input node.

event design in Calendar.js

Source code of Calendar.js could be found here. There is event tapOnDate defined in its metadata, with one parameter “date”.

Event delegation in the runtime

(1) When a given date is selected by end user, a jQuery event is issued: The below screenshot indicates that I have selected “Oct-15”.

The private function _gestureSelect of Calendar.js is called: Inside this function, the selected date is returned:

And then raise the UI5 event “TapOnDate” with selected date:

(2) The event handler defined during the creation of internal Calendar control is called now. The passed in raw date “Thu Oct 15 2015” is formatted to “Oct 15 2015”, and then assigned to property “DateValue”.

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-z6gKUsYF-1596955587956)(https://upload-images.jianshu.io/upload_images/2085791-0d151a0bedc1b6cd.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)]

Do you still remember another property “Value”? It will be filld by line 48: this.setProperty(“value”, t): Its value comes from the format result of date object:

after line 20 is executed, the formatted date is “October 15, 2015”:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-QIQgIchW-1596955587961)(https://upload-images.jianshu.io/upload_images/2085791-15e4870bec63f65d.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)] [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-SQschacM-1596955587963)(https://upload-images.jianshu.io/upload_images/2085791-6ab573dc6d401e97.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)]

So which exactly line of code triggers the change of the DatePicker control display, from previous date to the selected date? For example, I have selected Oct-15 in UI, and after line 2732 below is executed, the field of DatePicker in UI will refresh correspondingly to October 15, 2015.

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-oVKNxPzQ-1596955587964)(https://upload-images.jianshu.io/upload_images/2085791-d01a794d4baa2079.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)]

Internally, it is because setValue of DatePicker is called:

The call is further delegated to prototype sap.m.InputBase:

Here the Dom value is changed, so UI is refreshed accordingly.

Then DatePicker.js again raises its change event to application ( consumer ) with the two parameters:

(3) Then the event handler defined in application xml view is called:

When does the formatOptions set in XML view take effect? In xml view, we have defined style long for DatePicker’s formatOptions.

In the runtime, this binding information is represented by an instance of PropertyBinding. The path, type and formatOptions configured in xml view become corresponding attributes of the instance as displayed below.

The date object “Thu Oct 15 2015 00:00:00 GMT+0800 (China Standard)” is converted to String “October 15, 2015” by line 20, which is the final content you see in UI.