Skip to content

Commit a3c7094

Browse files
Update DataTable documentation (#151356)
This PR resolves [some problems I was having with `DataTable`](flutter/flutter#151005), based on advice from the style guide: > ### Answer your own questions straight away > If you find yourself asking a question about our systems, please place whatever answer you subsequently discover into the documentation in the same place where you first looked for the answer. That way, the documentation will consist of answers to real questions, where people would look to find them. The `DataTable` documentation now specifies that the widget is based on the Material 2 spec, and it offers a list of useful alternatives. <br> Additionally, an item in the "See also" section was updated to use a reliable Go link: ```diff - /// * <https://material.io/design/components/data-tables.html> + /// * <https://material.io/go/design-data-tables> ```
1 parent e1a6f76 commit a3c7094

File tree

2 files changed

+28
-18
lines changed

2 files changed

+28
-18
lines changed

packages/flutter/lib/src/material/data_table.dart

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -349,27 +349,29 @@ class DataCell {
349349
onTapCancel != null;
350350
}
351351

352-
/// A Material Design data table.
352+
/// A data table that follows the
353+
/// [Material 2](https://material.io/go/design-data-tables)
354+
/// design specification.
353355
///
354356
/// {@youtube 560 315 https://www.youtube.com/watch?v=ktTajqbhIcY}
355357
///
356-
/// Displaying data in a table is expensive, because to lay out the
357-
/// table all the data must be measured twice, once to negotiate the
358-
/// dimensions to use for each column, and once to actually lay out
359-
/// the table given the results of the negotiation.
358+
/// ## Performance considerations
360359
///
361-
/// For this reason, if you have a lot of data (say, more than a dozen
362-
/// rows with a dozen columns, though the precise limits depend on the
363-
/// target device), it is suggested that you use a
364-
/// [PaginatedDataTable] which automatically splits the data into
365-
/// multiple pages.
360+
/// Columns are sized automatically based on the table's contents.
361+
/// It's expensive to display large amounts of data with this widget,
362+
/// since it must be measured twice: once to negotiate each column's
363+
/// dimensions, and again when the table is laid out.
366364
///
367-
/// ## Performance considerations when wrapping [DataTable] with [SingleChildScrollView]
365+
/// A [SingleChildScrollView] mounts and paints the entire child, even
366+
/// when only some of it is visible. For a table that effectively handles
367+
/// large amounts of data, here are some other options to consider:
368368
///
369-
/// Wrapping a [DataTable] with [SingleChildScrollView] is expensive as [SingleChildScrollView]
370-
/// mounts and paints the entire [DataTable] even when only some rows are visible. If scrolling in
371-
/// one direction is necessary, then consider using a [CustomScrollView], otherwise use [PaginatedDataTable]
372-
/// to split the data into smaller pages.
369+
/// * `TableView`, a widget from the
370+
/// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables)
371+
/// package.
372+
/// * [PaginatedDataTable], which automatically splits the data into
373+
/// multiple pages.
374+
/// * [CustomScrollView], for greater control over scrolling effects.
373375
///
374376
/// {@tool dartpad}
375377
/// This sample shows how to display a [DataTable] with three columns: name, age, and
@@ -402,7 +404,10 @@ class DataCell {
402404
/// * [DataCell], which contains the data for a single cell in the data table.
403405
/// * [PaginatedDataTable], which shows part of the data in a data table and
404406
/// provides controls for paging through the remainder of the data.
405-
/// * <https://material.io/design/components/data-tables.html>
407+
/// * `TableView` from the
408+
/// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables)
409+
/// package, for displaying large amounts of data without pagination.
410+
/// * <https://material.io/go/design-data-tables>
406411
class DataTable extends StatelessWidget {
407412
/// Creates a widget describing a data table.
408413
///

packages/flutter/lib/src/material/paginated_data_table.dart

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@ import 'material_state.dart';
2121
import 'progress_indicator.dart';
2222
import 'theme.dart';
2323

24-
/// A Material Design data table that shows data using multiple pages.
24+
/// A table that follows the
25+
/// [Material 2](https://material.io/go/design-data-tables)
26+
/// design specification, using multiple pages to display data.
2527
///
2628
/// A paginated data table shows [rowsPerPage] rows of data per page and
2729
/// provides controls for showing other pages.
@@ -52,7 +54,10 @@ import 'theme.dart';
5254
/// See also:
5355
///
5456
/// * [DataTable], which is not paginated.
55-
/// * <https://material.io/go/design-data-tables#data-tables-tables-within-cards>
57+
/// * `TableView` from the
58+
/// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables)
59+
/// package, for displaying large amounts of data without pagination.
60+
/// * <https://material.io/go/design-data-tables>
5661
class PaginatedDataTable extends StatefulWidget {
5762
/// Creates a widget describing a paginated [DataTable] on a [Card].
5863
///

0 commit comments

Comments
 (0)