Customize date/time picker

2025-04-11 03:20

The super app can customize the appearance of the date/time picker within mini programs to ensure a consistent user interface. The picker appears when mini programs invoke the my.datePicker JSAPI, allowing users to provide date/time inputs more efficiently. It is rendered in one of the following five modes on iOS:

Time picker: Enables users to select the hour and minute.
Date picker: Enables users to select the year, month, and day.
Date and time picker: Enables users to select the year, month, day, hour, and minute.
Year and month picker: Enables users to select the year and month.
Year picker: Enables users to select the year.

Default user interface

The default pickers use a scrollable spinner format. Refer to the following table for default UI examples of different pickers:

Time picker	Date picker	Date and time picker	Year and month picker	Year picker

Before you begin

To customize the user interface for a date/time picker, ensure that the integrated iOS IAPMiniProgram SDK is version 2.65.0 or later. For more information, see SDK release notes.

Procedure

To customize the date picker, take the following two steps:

Step 1: Implement `GRVDatePickerDelegate`

Define a class that implements the GRVDatePickerDelegate protocol. Within the class, implement the showDatePicker method to customize a date/time picker. Refer to the following code for a sample implementation. For more information about the protocol and its defined method, refer to GRVDatePickerDelegate.

copy
class DemoDatePickerImpl: NSObject, GRVDatePickerDelegate {
    func showDatePicker(with param: GRVDatePickerParam, finishHandler: @escaping (Date) -> Void, cancelHandler: @escaping () -> Void) {
        // Implement the logic to define a custom date/time picker. Remember to:
        // - (Recommended) Use param.datePickerMode to provide different UIs based on modes
        // - Use param.currentDate as the initial selection
        // - Apply param.startDate/param.endDate as constraints when the SDK passes its values
        // - Call finishHandler or cancelHandler based on user operation
    }
}

Step 2: Configure `datePickerDelegate`

After the SDK is initialized, create an instance of GRVExtensionDelegate and assign the implementation (for example, DemoDatePickerImpl in the sample) to the datePickerDelegate property of the delegate's uiProvider. Refer to the following sample configuration code:

copy
// Replace DemoDatePickerImpl with your class name
let extensionDelegate = GRVExtensionDelegate()
extensionDelegate.uiProvider.datePickerDelegate = DemoDatePickerImpl()

Protocol

GRVDatePickerDelegate

The GRVDatePickerDelegate protocol defines a method for the super app to customize a date/time picker, which the SDK then calls to render the custom picker. Refer to the following code for the protocol definition:

copy
@protocol GRVDatePickerDelegate <NSObject>

- (void)showDatePickerWithParam:(GRVDatePickerParam *)param
                  finishHandler:(void(^)(NSDate *selectedDate))finishHandler
                  cancelHandler:(void(^)(void))cancelHandler;

@end

The following table lists the details of the defined method:

Method	Required	Description
showDatePickerWithParam:finishHandler:cancelHandler:	Yes	Called by the SDK to render a custom date/time picker. For more information, refer to `showDatePickerWithParam:finishHandler:cancelHandler:`.

showDatePickerWithParam:finishHandler:cancelHandler:

The showDatePickerWithParam:finishHandler:cancelHandler: method has the following input parameters whose values are passed by the SDK:

Parameter	Data type	Required	Description
param	GRVDatePickerParam object	Yes	An object that contains the configuration for the custom date/time picker. For more information, refer to `GRVDatePickerParam`.
finishHandler	Function	Yes	A callback that returns the selected date or time when the user completes a selection. For more information about the return value, refer to `finishHandler`.
cancelHandler	Function	Yes	A callback that is triggered when the user cancels a date or time selection.

GRVDatePickerParam

The definition of the GRVDatePickerParam object is as follows:

copy
typedef NS_ENUM(NSUInteger, GRVDatePickerMode) {
    GRVDatePickerModeTime,          // HH:mm
    GRVDatePickerModeDate,          // yyyy-MM-dd
    GRVDatePickerModeDateAndTime,   // yyyy-MM-dd HH:mm
    GRVDatePickerModeYearAndMonth,  // yyyy-MM
    GRVDatePickerModeYear           // yyyy
};

@interface GRVDatePickerParam : NSObject
@property (nonatomic, weak) UIViewController *currentViewController;
@property (nonatomic, assign) GRVDatePickerMode datePickerMode;
@property (nonatomic, copy) NSDate *currentDate;
@property (nonatomic, copy, nullable) NSDate *startDate;
@property (nonatomic, copy, nullable) NSDate *endDate;

@end

The following table lists the parameter details of this object:

Parameter	Data type	Required	Description
currentViewController	UIViewController	No	A weak reference to the view controller that displays and manages the date picker. The SDK typically passes this controller, but it might become deallocated.
datePickerMode	GRVDatePickerMode	Yes	The picker mode, which corresponds to the requested time format by mini programs. To enhance user experience, it is recommended that the super app use this value to customize mode-specific pickers. Valid values are: `time`: A time picker, which corresponds to the `HH:mm` format. `date`: A date picker, which corresponds to the `yyyy-MM-dd` format. If the mini program does not specify its desired time format, the SDK passes this value by default. `dateAndTime`: A date and time picker, which corresponds to the `yyyy-MM-dd HH:mm` format. `yearAndMonth`: A year and month picker, which corresponds to the `yyyy-MM` format. `year`: A year picker, which corresponds to the `yyyy` format.
currentDate	NSDate	Yes	The pre-selected date or time on the picker. The value is either of the following: Date/time passed by the mini program: This value is applied if the passed date or time matches its requested time format. Current date/time: This value is applied if the mini program does not pass a date or time, or passes one that mismatches its requested time format.
startDate	NSDate	No	The earliest selectable date or time on the picker. Only specified when the mini program provides a valid date or time.
endDate	NSDate	No	The latest selectable date or time on the picker. Only specified when the mini program provides a valid date or time.

finishHandler

Parameter	Data type	Required	Description
selectedDate	NSDate	Yes	The date or time selected by the user. The SDK formats this value based on the param.datePickerMode value before returning it to the mini program.