Skip to content

Commit 9fba981

Browse files
[material_ui] Add day and weekday builders to CalendarDatePicker and showDatePicker (flutter#12587)
`CalendarDatePicker` does not provide a way to customize individual day cells or weekday headers while retaining the default picker behavior. This PR adds `dayBuilder` and `weekdayBuilder` callbacks for customizing individual day cells and weekday headers. The callbacks are exposed through `CalendarDatePicker`, `DatePickerDialog`, and `showDatePicker`. The day builder receives the current widget states while the picker retains its semantics, focus, and tap handling. Tests cover customized days and weekday headers, day widget states, and `showDatePicker` parameter forwarding. Fixes flutter#68106 ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent db55a59 commit 9fba981

5 files changed

Lines changed: 447 additions & 17 deletions

File tree

‎packages/material_ui/lib/src/calendar_date_picker.dart‎

Lines changed: 170 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,60 @@ const double _kDayPickerGridLandscapeMaxScaleFactor = 1.5;
7171
// 14 is a common font size used to compute the effective text scale.
7272
const double _fontSizeToScale = 14.0;
7373

74+
/// The signature of a function that builds a widget for a day in a
75+
/// [CalendarDatePicker].
76+
///
77+
/// The [details] contain the date, its current [WidgetState]s, and the default
78+
/// widget built by the date picker.
79+
///
80+
/// The date picker's semantics, focus, and tap handling are applied to the
81+
/// widget returned by this function.
82+
typedef CalendarDatePickerDayBuilder = Widget Function(
83+
BuildContext context,
84+
CalendarDatePickerDayDetails details,
85+
);
86+
87+
/// Details for building a day in a [CalendarDatePickerDayBuilder].
88+
final class CalendarDatePickerDayDetails {
89+
const CalendarDatePickerDayDetails._({
90+
required this.day,
91+
required this.states,
92+
required this.child,
93+
});
94+
95+
/// The date represented by the widget.
96+
final DateTime day;
97+
98+
/// An unmodifiable snapshot of the current states of the day, such as
99+
/// [WidgetState.disabled], [WidgetState.selected], or [WidgetState.hovered].
100+
final Set<WidgetState> states;
101+
102+
/// The default widget built by the date picker.
103+
final Widget child;
104+
}
105+
106+
/// The signature of a function that builds a weekday header in a
107+
/// [CalendarDatePicker].
108+
///
109+
/// The [details] contain the weekday and the default localized weekday header
110+
/// built by the date picker.
111+
typedef CalendarDatePickerWeekdayBuilder = Widget Function(
112+
BuildContext context,
113+
CalendarDatePickerWeekdayDetails details,
114+
);
115+
116+
/// Details for building a weekday header in a [CalendarDatePickerWeekdayBuilder].
117+
final class CalendarDatePickerWeekdayDetails {
118+
const CalendarDatePickerWeekdayDetails._({required this.weekday, required this.child});
119+
120+
/// The weekday, using the same numbering as [DateTime.weekday], from
121+
/// [DateTime.monday] through [DateTime.sunday].
122+
final int weekday;
123+
124+
/// The default localized weekday header built by the date picker.
125+
final Widget child;
126+
}
127+
74128
/// Displays a grid of days for a given month and allows the user to select a
75129
/// date.
76130
///
@@ -117,6 +171,10 @@ class CalendarDatePicker extends StatefulWidget {
117171
/// If [selectableDayPredicate] and [initialDate] are both non-null,
118172
/// [selectableDayPredicate] must return `true` for the [initialDate].
119173
///
174+
/// The [dayBuilder] and [weekdayBuilder] can be used to customize the days and
175+
/// weekday headers in the calendar's day grid. They are only used when the
176+
/// picker is displaying the day selection interface.
177+
///
120178
/// {@template material_ui.calendar_date_picker.calendarDelegate}
121179
/// The [calendarDelegate] controls date interpretation, formatting, and
122180
/// navigation within the picker. By providing a custom implementation,
@@ -133,6 +191,8 @@ class CalendarDatePicker extends StatefulWidget {
133191
this.onDisplayedMonthChanged,
134192
this.initialCalendarMode = DatePickerMode.day,
135193
this.selectableDayPredicate,
194+
this.dayBuilder,
195+
this.weekdayBuilder,
136196
this.calendarDelegate = const GregorianCalendarDelegate(),
137197
}) : initialDate = initialDate == null ? null : calendarDelegate.dateOnly(initialDate),
138198
firstDate = calendarDelegate.dateOnly(firstDate),
@@ -192,6 +252,18 @@ class CalendarDatePicker extends StatefulWidget {
192252
/// Function to provide full control over which dates in the calendar can be selected.
193253
final SelectableDayPredicate? selectableDayPredicate;
194254

255+
/// An optional builder for the individual days in the calendar's day grid.
256+
///
257+
/// The builder is only used when the picker is displaying the day selection
258+
/// interface.
259+
final CalendarDatePickerDayBuilder? dayBuilder;
260+
261+
/// An optional builder for the weekday headers in the calendar's day grid.
262+
///
263+
/// The builder is only used when the picker is displaying the day selection
264+
/// interface.
265+
final CalendarDatePickerWeekdayBuilder? weekdayBuilder;
266+
195267
/// {@macro material_ui.calendar_date_picker.calendarDelegate}
196268
final CalendarDelegate<DateTime> calendarDelegate;
197269

@@ -359,6 +431,8 @@ class _CalendarDatePickerState extends State<CalendarDatePicker> {
359431
onChanged: _handleDayChanged,
360432
onDisplayedMonthChanged: _handleMonthChanged,
361433
selectableDayPredicate: widget.selectableDayPredicate,
434+
dayBuilder: widget.dayBuilder,
435+
weekdayBuilder: widget.weekdayBuilder,
362436
);
363437
case DatePickerMode.year:
364438
return Padding(
@@ -570,6 +644,8 @@ class _MonthPicker extends StatefulWidget {
570644
required this.onDisplayedMonthChanged,
571645
required this.calendarDelegate,
572646
this.selectableDayPredicate,
647+
this.dayBuilder,
648+
this.weekdayBuilder,
573649
}) : assert(!firstDate.isAfter(lastDate)),
574650
assert(selectedDate == null || !selectedDate.isBefore(firstDate)),
575651
assert(selectedDate == null || !selectedDate.isAfter(lastDate));
@@ -611,6 +687,12 @@ class _MonthPicker extends StatefulWidget {
611687
/// Optional user supplied predicate function to customize selectable days.
612688
final SelectableDayPredicate? selectableDayPredicate;
613689

690+
/// An optional builder for the individual days in the calendar's day grid.
691+
final CalendarDatePickerDayBuilder? dayBuilder;
692+
693+
/// An optional builder for the weekday headers in the calendar's day grid.
694+
final CalendarDatePickerWeekdayBuilder? weekdayBuilder;
695+
614696
/// {@macro material_ui.calendar_date_picker.calendarDelegate}
615697
final CalendarDelegate<DateTime> calendarDelegate;
616698

@@ -882,6 +964,8 @@ class _MonthPickerState extends State<_MonthPicker> {
882964
lastDate: widget.lastDate,
883965
displayedMonth: month,
884966
selectableDayPredicate: widget.selectableDayPredicate,
967+
dayBuilder: widget.dayBuilder,
968+
weekdayBuilder: widget.weekdayBuilder,
885969
);
886970
}
887971

@@ -1003,6 +1087,8 @@ class _DayPicker extends StatefulWidget {
10031087
required this.onChanged,
10041088
required this.calendarDelegate,
10051089
this.selectableDayPredicate,
1090+
this.dayBuilder,
1091+
this.weekdayBuilder,
10061092
}) : assert(!firstDate.isAfter(lastDate)),
10071093
assert(selectedDate == null || !selectedDate.isBefore(firstDate)),
10081094
assert(selectedDate == null || !selectedDate.isAfter(lastDate));
@@ -1034,6 +1120,12 @@ class _DayPicker extends StatefulWidget {
10341120
/// Optional user supplied predicate function to customize selectable days.
10351121
final SelectableDayPredicate? selectableDayPredicate;
10361122

1123+
/// An optional builder for the individual days in the calendar's day grid.
1124+
final CalendarDatePickerDayBuilder? dayBuilder;
1125+
1126+
/// An optional builder for the weekday headers in the calendar's day grid.
1127+
final CalendarDatePickerWeekdayBuilder? weekdayBuilder;
1128+
10371129
/// {@macro material_ui.calendar_date_picker.calendarDelegate}
10381130
final CalendarDelegate<DateTime> calendarDelegate;
10391131

@@ -1094,19 +1186,40 @@ class _DayPickerState extends State<_DayPicker> {
10941186
/// _ _ _ _ 1 2 3
10951187
/// 4 5 6 7 8 9 10
10961188
///
1097-
List<Widget> _dayHeaders(TextStyle? headerStyle, MaterialLocalizations localizations) {
1189+
List<Widget> _dayHeaders(
1190+
BuildContext context,
1191+
TextStyle? headerStyle,
1192+
MaterialLocalizations localizations,
1193+
) {
10981194
final result = <Widget>[];
10991195
for (
11001196
int i = localizations.firstDayOfWeekIndex;
11011197
result.length < DateTime.daysPerWeek;
11021198
i = (i + 1) % DateTime.daysPerWeek
11031199
) {
11041200
final String weekday = localizations.narrowWeekdays[i];
1105-
result.add(
1106-
ExcludeSemantics(
1107-
child: Center(child: Text(weekday, style: headerStyle)),
1108-
),
1109-
);
1201+
if (widget.weekdayBuilder != null) {
1202+
final int dateTimeWeekday = (i == 0 ? DateTime.sunday : i);
1203+
final Widget weekdayWidget = widget.weekdayBuilder!(
1204+
context,
1205+
CalendarDatePickerWeekdayDetails._(
1206+
weekday: dateTimeWeekday,
1207+
child: ExcludeSemantics(child: Text(weekday)),
1208+
),
1209+
);
1210+
result.add(
1211+
DefaultTextStyle.merge(
1212+
style: headerStyle,
1213+
child: Center(child: weekdayWidget),
1214+
),
1215+
);
1216+
} else {
1217+
result.add(
1218+
ExcludeSemantics(
1219+
child: Center(child: Text(weekday, style: headerStyle)),
1220+
),
1221+
);
1222+
}
11101223
}
11111224
return result;
11121225
}
@@ -1127,7 +1240,7 @@ class _DayPickerState extends State<_DayPicker> {
11271240
final int daysInMonth = widget.calendarDelegate.getDaysInMonth(year, month);
11281241
final int dayOffset = widget.calendarDelegate.firstDayOffset(year, month, localizations);
11291242

1130-
final List<Widget> dayItems = _dayHeaders(weekdayStyle, localizations);
1243+
final List<Widget> dayItems = _dayHeaders(context, weekdayStyle, localizations);
11311244
// 1-based day of month, e.g. 1-31 for January, and 1-29 for February on
11321245
// a leap year.
11331246
int day = -dayOffset;
@@ -1157,6 +1270,7 @@ class _DayPickerState extends State<_DayPicker> {
11571270
onChanged: widget.onChanged,
11581271
focusNode: _dayFocusNodes[day - 1],
11591272
calendarDelegate: widget.calendarDelegate,
1273+
dayBuilder: widget.dayBuilder,
11601274
),
11611275
);
11621276
}
@@ -1192,6 +1306,7 @@ class _Day extends StatefulWidget {
11921306
required this.onChanged,
11931307
required this.focusNode,
11941308
required this.calendarDelegate,
1309+
this.dayBuilder,
11951310
});
11961311

11971312
final DateTime day;
@@ -1201,6 +1316,7 @@ class _Day extends StatefulWidget {
12011316
final ValueChanged<DateTime> onChanged;
12021317
final FocusNode focusNode;
12031318
final CalendarDelegate<DateTime> calendarDelegate;
1319+
final CalendarDatePickerDayBuilder? dayBuilder;
12041320

12051321
@override
12061322
State<_Day> createState() => _DayState();
@@ -1235,7 +1351,15 @@ class _DayState extends State<_Day> {
12351351
if (widget.isSelectedDay) WidgetState.selected,
12361352
};
12371353

1238-
_statesController.value = states;
1354+
// Preserve interaction states managed by InkResponse across rebuilds.
1355+
final Set<WidgetState> interactionStates = widget.isDisabled
1356+
? <WidgetState>{}
1357+
: _statesController.value.difference(<WidgetState>{
1358+
WidgetState.disabled,
1359+
WidgetState.selected,
1360+
});
1361+
1362+
_statesController.value = <WidgetState>{...states, ...interactionStates};
12391363

12401364
final Color? dayForegroundColor = resolve<Color?>(
12411365
(DatePickerThemeData? theme) =>
@@ -1269,15 +1393,45 @@ class _DayState extends State<_Day> {
12691393
)
12701394
: ShapeDecoration(color: dayBackgroundColor, shape: dayShape);
12711395

1272-
Widget dayWidget = Ink(
1273-
decoration: decoration,
1274-
child: Center(
1275-
child: Text(
1276-
localizations.formatDecimal(widget.day.day),
1277-
style: dayStyle?.apply(color: dayForegroundColor),
1396+
Widget dayWidget;
1397+
if (widget.dayBuilder != null) {
1398+
dayWidget = Ink(
1399+
decoration: decoration,
1400+
child: Center(
1401+
child: ExcludeSemantics(child: Text(localizations.formatDecimal(widget.day.day))),
12781402
),
1279-
),
1280-
);
1403+
);
1404+
dayWidget = ListenableBuilder(
1405+
listenable: _statesController,
1406+
builder: (BuildContext context, Widget? child) {
1407+
return widget.dayBuilder!(
1408+
context,
1409+
CalendarDatePickerDayDetails._(
1410+
day: widget.day,
1411+
states: Set<WidgetState>.unmodifiable(_statesController.value),
1412+
child: child!,
1413+
),
1414+
);
1415+
},
1416+
child: dayWidget,
1417+
);
1418+
dayWidget = DefaultTextStyle.merge(
1419+
style: dayStyle?.apply(color: dayForegroundColor),
1420+
child: dayWidget,
1421+
);
1422+
} else {
1423+
dayWidget = Ink(
1424+
decoration: decoration,
1425+
child: Center(
1426+
child: ExcludeSemantics(
1427+
child: Text(
1428+
localizations.formatDecimal(widget.day.day),
1429+
style: dayStyle?.apply(color: dayForegroundColor),
1430+
),
1431+
),
1432+
),
1433+
);
1434+
}
12811435

12821436
// Adds padding as per M3 guidelines for portrait mode. Not applied in landscape
12831437
// mode currently due to unclear specifications.
@@ -1298,7 +1452,6 @@ class _DayState extends State<_Day> {
12981452
button: true,
12991453
selected: widget.isSelectedDay,
13001454
enabled: !widget.isDisabled,
1301-
excludeSemantics: true,
13021455
child: dayWidget,
13031456
);
13041457

‎packages/material_ui/lib/src/date_picker.dart‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,10 @@ const double _fontSizeToScale = 14.0;
123123
/// this can be used to only allow weekdays for selection. If provided, it must
124124
/// return true for [initialDate].
125125
///
126+
/// The [dayBuilder] and [weekdayBuilder] can be used to customize the days and
127+
/// weekday headers in the calendar's day grid. They are only used when the
128+
/// picker is displaying the day selection interface.
129+
///
126130
/// {@macro material_ui.calendar_date_picker.calendarDelegate}
127131
///
128132
/// Use a custom [CalendarDelegate.keyboardInputFormatters] to customize
@@ -251,6 +255,8 @@ Future<DateTime?> showDatePicker({
251255
ValueChanged<DatePickerEntryMode>? onDatePickerModeChange,
252256
Icon? switchToInputEntryModeIcon,
253257
Icon? switchToCalendarEntryModeIcon,
258+
CalendarDatePickerDayBuilder? dayBuilder,
259+
CalendarDatePickerWeekdayBuilder? weekdayBuilder,
254260
CalendarDelegate<DateTime> calendarDelegate = const GregorianCalendarDelegate(),
255261
}) async {
256262
initialDate = initialDate == null ? null : calendarDelegate.dateOnly(initialDate);
@@ -293,6 +299,8 @@ Future<DateTime?> showDatePicker({
293299
onDatePickerModeChange: onDatePickerModeChange,
294300
switchToInputEntryModeIcon: switchToInputEntryModeIcon,
295301
switchToCalendarEntryModeIcon: switchToCalendarEntryModeIcon,
302+
dayBuilder: dayBuilder,
303+
weekdayBuilder: weekdayBuilder,
296304
calendarDelegate: calendarDelegate,
297305
);
298306

@@ -360,6 +368,8 @@ class DatePickerDialog extends StatefulWidget {
360368
this.switchToInputEntryModeIcon,
361369
this.switchToCalendarEntryModeIcon,
362370
this.insetPadding = const EdgeInsets.symmetric(horizontal: 16.0, vertical: 24.0),
371+
this.dayBuilder,
372+
this.weekdayBuilder,
363373
this.calendarDelegate = const GregorianCalendarDelegate(),
364374
}) : initialDate = initialDate == null ? null : calendarDelegate.dateOnly(initialDate),
365375
firstDate = calendarDelegate.dateOnly(firstDate),
@@ -486,6 +496,18 @@ class DatePickerDialog extends StatefulWidget {
486496
/// Defaults to `EdgeInsets.symmetric(horizontal: 16.0, vertical: 24.0)`.
487497
final EdgeInsets insetPadding;
488498

499+
/// An optional builder for the individual days in the calendar's day grid.
500+
///
501+
/// The builder is only used when the picker is displaying the day selection
502+
/// interface.
503+
final CalendarDatePickerDayBuilder? dayBuilder;
504+
505+
/// An optional builder for the weekday headers in the calendar's day grid.
506+
///
507+
/// The builder is only used when the picker is displaying the day selection
508+
/// interface.
509+
final CalendarDatePickerWeekdayBuilder? weekdayBuilder;
510+
489511
/// {@macro material_ui.calendar_date_picker.calendarDelegate}
490512
final CalendarDelegate<DateTime> calendarDelegate;
491513

@@ -668,6 +690,8 @@ class _DatePickerDialogState extends State<DatePickerDialog> with RestorationMix
668690
onDateChanged: _handleDateChanged,
669691
selectableDayPredicate: widget.selectableDayPredicate,
670692
initialCalendarMode: widget.initialCalendarMode,
693+
dayBuilder: widget.dayBuilder,
694+
weekdayBuilder: widget.weekdayBuilder,
671695
);
672696
}
673697

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
changelog: |
2+
- Adds `dayBuilder` and `weekdayBuilder` callbacks to `CalendarDatePicker`, `DatePickerDialog`, and `showDatePicker`.
3+
- Adds `CalendarDatePickerDayDetails` and `CalendarDatePickerWeekdayDetails` to provide metadata and default widgets to the builders.
4+
version: minor

0 commit comments

Comments
 (0)