Skip to content

Commit c41644a

Browse files
[material_ui] Add sortIconBuilder to DataTable, PaginatedDataTable, and DataTableThemeData (flutter#12645)
*This PR ports flutter#188729 from flutter/flutter to flutter/packages* Fixes: flutter#91801 ## 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 f96bdf5 commit c41644a

7 files changed

Lines changed: 195 additions & 6 deletions

File tree

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

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -508,6 +508,7 @@ class DataTable extends StatelessWidget {
508508
this.checkboxHorizontalMargin,
509509
this.border,
510510
this.clipBehavior = Clip.none,
511+
this.sortIconBuilder,
511512
}) : assert(columns.isNotEmpty),
512513
assert(
513514
sortColumnIndex == null || (sortColumnIndex >= 0 && sortColumnIndex < columns.length),
@@ -562,6 +563,27 @@ class DataTable extends StatelessWidget {
562563
/// Ascending order is represented by an upwards-facing arrow.
563564
final bool sortAscending;
564565

566+
/// {@template flutter.material.dataTable.sortIconBuilder}
567+
/// A builder function that returns a widget to use as the sorting indicator
568+
/// icon for the table's header cells.
569+
///
570+
/// When providing a custom sort icon via this builder, the default sort arrow's
571+
/// automatic rotation and opacity transitions are omitted. To achieve animated
572+
/// transitions for custom icons, wrap the returned widget in explicit
573+
/// transition widgets such as [AnimatedRotation] or [AnimatedOpacity].
574+
///
575+
/// Custom icons should target a size of approximately 18.0 logical pixels or
576+
/// be wrapped in a fixed-size container to maintain visually balanced header
577+
/// labels. For columns where [DataColumn.numeric] is true, [DataTable] adds
578+
/// a leading 20.0 logical pixel spacer to mirror the space occupied by the
579+
/// sort icon and its padding, ensuring centered column labels remain properly
580+
/// aligned.
581+
///
582+
/// If null, [DataTableThemeData.sortIconBuilder] is used. If that is also null,
583+
/// the default Material design sort arrow animation is used.
584+
/// {@endtemplate}
585+
final DataTableSortIconBuilder? sortIconBuilder;
586+
565587
/// Invoked when the user selects or unselects every row, using the
566588
/// checkbox in the heading row.
567589
///
@@ -903,6 +925,9 @@ class DataTable extends StatelessWidget {
903925
}) {
904926
final ThemeData themeData = Theme.of(context);
905927
final DataTableThemeData dataTableTheme = DataTableTheme.of(context);
928+
final DataTableSortIconBuilder? effectiveSortIconBuilder =
929+
sortIconBuilder ?? dataTableTheme.sortIconBuilder;
930+
906931
label = Semantics(
907932
role: SemanticsRole.columnHeader,
908933
child: Row(
@@ -913,11 +938,14 @@ class DataTable extends StatelessWidget {
913938
const SizedBox(width: _SortArrowState._arrowIconSize + _sortArrowPadding),
914939
label,
915940
if (onSort != null) ...<Widget>[
916-
_SortArrow(
917-
visible: sorted,
918-
up: sorted ? ascending : null,
919-
duration: _sortArrowAnimationDuration,
920-
),
941+
if (effectiveSortIconBuilder != null)
942+
effectiveSortIconBuilder(context, sorted, ascending)
943+
else
944+
_SortArrow(
945+
visible: sorted,
946+
up: sorted ? ascending : null,
947+
duration: _sortArrowAnimationDuration,
948+
),
921949
const SizedBox(width: _sortArrowPadding),
922950
],
923951
],

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

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,16 @@ import 'theme.dart';
1515
// Examples can assume:
1616
// late BuildContext context;
1717

18+
/// Signature for a builder function that returns a widget to use as a sorting
19+
/// indicator icon in a [DataTable] header cell.
20+
///
21+
/// The [visible] parameter indicates whether the sort icon should be visible
22+
/// (i.e. whether the column is the active sort column).
23+
///
24+
/// The [ascending] parameter indicates whether the sort order is ascending.
25+
typedef DataTableSortIconBuilder =
26+
Widget Function(BuildContext context, bool visible, bool ascending);
27+
1828
/// Defines default property values for descendant [DataTable]
1929
/// widgets.
2030
///
@@ -59,6 +69,7 @@ class DataTableThemeData with Diagnosticable {
5969
this.headingCellCursor,
6070
this.dataRowCursor,
6171
this.headingRowAlignment,
72+
this.sortIconBuilder,
6273
}) : assert(
6374
dataRowMinHeight == null ||
6475
dataRowMaxHeight == null ||
@@ -125,6 +136,9 @@ class DataTableThemeData with Diagnosticable {
125136
/// If specified, overrides the default value of [DataColumn.headingRowAlignment].
126137
final MainAxisAlignment? headingRowAlignment;
127138

139+
/// {@macro flutter.material.dataTable.sortIconBuilder}
140+
final DataTableSortIconBuilder? sortIconBuilder;
141+
128142
/// Creates a copy of this object but with the given fields replaced with the
129143
/// new values.
130144
DataTableThemeData copyWith({
@@ -148,6 +162,7 @@ class DataTableThemeData with Diagnosticable {
148162
WidgetStateProperty<MouseCursor?>? headingCellCursor,
149163
WidgetStateProperty<MouseCursor?>? dataRowCursor,
150164
MainAxisAlignment? headingRowAlignment,
165+
DataTableSortIconBuilder? sortIconBuilder,
151166
}) {
152167
assert(
153168
dataRowHeight == null || (dataRowMinHeight == null && dataRowMaxHeight == null),
@@ -172,6 +187,7 @@ class DataTableThemeData with Diagnosticable {
172187
headingCellCursor: headingCellCursor ?? this.headingCellCursor,
173188
dataRowCursor: dataRowCursor ?? this.dataRowCursor,
174189
headingRowAlignment: headingRowAlignment ?? this.headingRowAlignment,
190+
sortIconBuilder: sortIconBuilder ?? this.sortIconBuilder,
175191
);
176192
}
177193

@@ -207,6 +223,7 @@ class DataTableThemeData with Diagnosticable {
207223
headingCellCursor: t < 0.5 ? a.headingCellCursor : b.headingCellCursor,
208224
dataRowCursor: t < 0.5 ? a.dataRowCursor : b.dataRowCursor,
209225
headingRowAlignment: t < 0.5 ? a.headingRowAlignment : b.headingRowAlignment,
226+
sortIconBuilder: t < 0.5 ? a.sortIconBuilder : b.sortIconBuilder,
210227
);
211228
}
212229

@@ -227,6 +244,7 @@ class DataTableThemeData with Diagnosticable {
227244
headingCellCursor,
228245
dataRowCursor,
229246
headingRowAlignment,
247+
sortIconBuilder,
230248
);
231249

232250
@override
@@ -252,7 +270,8 @@ class DataTableThemeData with Diagnosticable {
252270
other.checkboxHorizontalMargin == checkboxHorizontalMargin &&
253271
other.headingCellCursor == headingCellCursor &&
254272
other.dataRowCursor == dataRowCursor &&
255-
other.headingRowAlignment == headingRowAlignment;
273+
other.headingRowAlignment == headingRowAlignment &&
274+
other.sortIconBuilder == sortIconBuilder;
256275
}
257276

258277
@override
@@ -309,6 +328,9 @@ class DataTableThemeData with Diagnosticable {
309328
defaultValue: null,
310329
),
311330
);
331+
properties.add(
332+
ObjectFlagProperty<DataTableSortIconBuilder>.has('sortIconBuilder', sortIconBuilder),
333+
);
312334
}
313335
}
314336

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import 'card.dart';
1616
import 'constants.dart';
1717
import 'data_table.dart';
1818
import 'data_table_source.dart';
19+
import 'data_table_theme.dart';
1920
import 'debug.dart';
2021
import 'dropdown.dart';
2122
import 'icon_button.dart';
@@ -140,6 +141,7 @@ class PaginatedDataTable extends StatefulWidget {
140141
this.headingRowColor,
141142
this.dividerThickness,
142143
this.showEmptyRows = true,
144+
this.sortIconBuilder,
143145
}) : assert(actions == null || (header != null)),
144146
assert(columns.isNotEmpty),
145147
assert(
@@ -372,6 +374,9 @@ class PaginatedDataTable extends StatefulWidget {
372374
/// When set to `false`, empty rows will not be created.
373375
final bool showEmptyRows;
374376

377+
/// {@macro flutter.material.dataTable.sortIconBuilder}
378+
final DataTableSortIconBuilder? sortIconBuilder;
379+
375380
@override
376381
PaginatedDataTableState createState() => PaginatedDataTableState();
377382
}
@@ -692,6 +697,7 @@ class PaginatedDataTableState extends State<PaginatedDataTable> {
692697
showBottomBorder: true,
693698
rows: _getRows(_firstRowIndex, widget.rowsPerPage),
694699
headingRowColor: widget.headingRowColor,
700+
sortIconBuilder: widget.sortIconBuilder,
695701
),
696702
),
697703
),
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds sortIconBuilder parameter to DataTable, PaginatedDataTable, and DataTableThemeData for custom sorting indicators.
3+
version: minor

‎packages/material_ui/test/data_table_test.dart‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -432,6 +432,107 @@ void main() {
432432
expect(transformOfArrow.transform.getRotation(), equals(Matrix3.rotationZ(math.pi)));
433433
});
434434

435+
testWidgets('DataTable custom sortIconBuilder test', (WidgetTester tester) async {
436+
Widget buildTable({
437+
DataTableSortIconBuilder? sortIconBuilder,
438+
DataTableThemeData? themeData,
439+
int? sortColumnIndex = 0,
440+
bool sortAscending = true,
441+
}) {
442+
final Widget table = DataTable(
443+
sortColumnIndex: sortColumnIndex,
444+
sortAscending: sortAscending,
445+
sortIconBuilder: sortIconBuilder,
446+
columns: <DataColumn>[
447+
DataColumn(label: const Text('Name'), onSort: (int columnIndex, bool ascending) {}),
448+
DataColumn(label: const Text('Calories'), onSort: (int columnIndex, bool ascending) {}),
449+
],
450+
rows: kDesserts.map<DataRow>((Dessert dessert) {
451+
return DataRow(
452+
cells: <DataCell>[DataCell(Text(dessert.name)), DataCell(Text('${dessert.calories}'))],
453+
);
454+
}).toList(),
455+
);
456+
457+
return MaterialApp(
458+
home: Material(
459+
child: themeData != null ? DataTableTheme(data: themeData, child: table) : table,
460+
),
461+
);
462+
}
463+
464+
// Default (null sortIconBuilder): uses standard Icon(Icons.arrow_upward).
465+
await tester.pumpWidget(buildTable());
466+
final Finder defaultIconFinder = find.descendant(
467+
of: find.byType(DataTable),
468+
matching: find.byIcon(Icons.arrow_upward),
469+
);
470+
expect(defaultIconFinder, findsNWidgets(2));
471+
472+
// Custom sortIconBuilder on DataTable.
473+
await tester.pumpWidget(
474+
buildTable(
475+
sortIconBuilder: (BuildContext context, bool visible, bool ascending) {
476+
return Text(visible ? (ascending ? 'ASC' : 'DESC') : 'INACTIVE');
477+
},
478+
),
479+
);
480+
expect(find.text('ASC'), findsOneWidget);
481+
expect(find.text('INACTIVE'), findsOneWidget);
482+
483+
// Verify sortAscending = false passes ascending = false.
484+
await tester.pumpWidget(
485+
buildTable(
486+
sortAscending: false,
487+
sortIconBuilder: (BuildContext context, bool visible, bool ascending) {
488+
return Text(visible ? (ascending ? 'ASC' : 'DESC') : 'INACTIVE');
489+
},
490+
),
491+
);
492+
expect(find.text('DESC'), findsOneWidget);
493+
expect(find.text('INACTIVE'), findsOneWidget);
494+
495+
// Verify sorted column index change passes updated visible flags.
496+
await tester.pumpWidget(
497+
buildTable(
498+
sortColumnIndex: 1,
499+
sortIconBuilder: (BuildContext context, bool visible, bool ascending) {
500+
return Text(visible ? 'SORTED_COL1' : 'UNSORTED_COL0');
501+
},
502+
),
503+
);
504+
expect(find.text('SORTED_COL1'), findsOneWidget);
505+
expect(find.text('UNSORTED_COL0'), findsOneWidget);
506+
507+
// Verify DataTableThemeData.sortIconBuilder theme resolution.
508+
await tester.pumpWidget(
509+
buildTable(
510+
themeData: DataTableThemeData(
511+
sortIconBuilder: (BuildContext context, bool visible, bool ascending) {
512+
return const Text('THEME_BUILDER');
513+
},
514+
),
515+
),
516+
);
517+
expect(find.text('THEME_BUILDER'), findsNWidgets(2));
518+
519+
// Verify DataTable.sortIconBuilder overrides DataTableThemeData.sortIconBuilder.
520+
await tester.pumpWidget(
521+
buildTable(
522+
sortIconBuilder: (BuildContext context, bool visible, bool ascending) {
523+
return const Text('WIDGET_BUILDER');
524+
},
525+
themeData: DataTableThemeData(
526+
sortIconBuilder: (BuildContext context, bool visible, bool ascending) {
527+
return const Text('THEME_BUILDER');
528+
},
529+
),
530+
),
531+
);
532+
expect(find.text('WIDGET_BUILDER'), findsNWidgets(2));
533+
expect(find.text('THEME_BUILDER'), findsNothing);
534+
});
535+
435536
testWidgets('DataTable sort indicator orientation does not change on state update', (
436537
WidgetTester tester,
437538
) async {

‎packages/material_ui/test/data_table_theme_test.dart‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ void main() {
4545
expect(themeData.headingCellCursor, null);
4646
expect(themeData.dataRowCursor, null);
4747
expect(themeData.headingRowAlignment, null);
48+
expect(themeData.sortIconBuilder, null);
4849

4950
const theme = DataTableTheme(data: DataTableThemeData(), child: SizedBox());
5051
expect(theme.data.decoration, null);
@@ -63,6 +64,7 @@ void main() {
6364
expect(theme.data.headingCellCursor, null);
6465
expect(theme.data.dataRowCursor, null);
6566
expect(theme.data.headingRowAlignment, null);
67+
expect(theme.data.sortIconBuilder, null);
6668
});
6769

6870
testWidgets('Default DataTableThemeData debugFillProperties', (WidgetTester tester) async {
@@ -99,6 +101,7 @@ void main() {
99101
headingCellCursor: const MaterialStatePropertyAll<MouseCursor>(SystemMouseCursors.grab),
100102
dataRowCursor: const MaterialStatePropertyAll<MouseCursor>(SystemMouseCursors.forbidden),
101103
headingRowAlignment: MainAxisAlignment.center,
104+
sortIconBuilder: (BuildContext context, bool visible, bool ascending) => const SizedBox(),
102105
).debugFillProperties(builder);
103106

104107
final List<String> description = builder.properties
@@ -121,6 +124,7 @@ void main() {
121124
expect(description[12], 'headingCellCursor: WidgetStatePropertyAll(SystemMouseCursor(grab))');
122125
expect(description[13], 'dataRowCursor: WidgetStatePropertyAll(SystemMouseCursor(forbidden))');
123126
expect(description[14], 'headingRowAlignment: center');
127+
expect(description[15], 'has sortIconBuilder');
124128
});
125129

126130
testWidgets('DataTable is themeable', (WidgetTester tester) async {

‎packages/material_ui/test/paginated_data_table_test.dart‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1535,4 +1535,29 @@ void main() {
15351535
);
15361536
expect(tester.getSize(find.byType(PaginatedDataTable)), Size.zero);
15371537
});
1538+
1539+
testWidgets('PaginatedDataTable custom sortIconBuilder test', (WidgetTester tester) async {
1540+
await tester.pumpWidget(
1541+
MaterialApp(
1542+
home: PaginatedDataTable(
1543+
sortColumnIndex: 0,
1544+
sortIconBuilder: (BuildContext context, bool visible, bool ascending) {
1545+
return Text(
1546+
visible ? (ascending ? 'PAGINATED_ASC' : 'PAGINATED_DESC') : 'PAGINATED_INACTIVE',
1547+
);
1548+
},
1549+
header: const Text('Test Table'),
1550+
rowsPerPage: 2,
1551+
columns: <DataColumn>[
1552+
DataColumn(label: const Text('Name'), onSort: (int columnIndex, bool ascending) {}),
1553+
const DataColumn(label: Text('Calories'), numeric: true),
1554+
const DataColumn(label: Text('Generation')),
1555+
],
1556+
source: source,
1557+
),
1558+
),
1559+
);
1560+
1561+
expect(find.text('PAGINATED_ASC'), findsOneWidget);
1562+
});
15381563
}

0 commit comments

Comments
 (0)