diff --git a/packages/flutter/lib/src/material/data_table.dart b/packages/flutter/lib/src/material/data_table.dart index 95bf05640a0..c32bbb3c30f 100644 --- a/packages/flutter/lib/src/material/data_table.dart +++ b/packages/flutter/lib/src/material/data_table.dart @@ -349,27 +349,29 @@ class DataCell { onTapCancel != null; } -/// A Material Design data table. +/// A data table that follows the +/// [Material 2](https://material.io/go/design-data-tables) +/// design specification. /// /// {@youtube 560 315 https://www.youtube.com/watch?v=ktTajqbhIcY} /// -/// Displaying data in a table is expensive, because to lay out the -/// table all the data must be measured twice, once to negotiate the -/// dimensions to use for each column, and once to actually lay out -/// the table given the results of the negotiation. +/// ## Performance considerations /// -/// For this reason, if you have a lot of data (say, more than a dozen -/// rows with a dozen columns, though the precise limits depend on the -/// target device), it is suggested that you use a -/// [PaginatedDataTable] which automatically splits the data into -/// multiple pages. +/// Columns are sized automatically based on the table's contents. +/// It's expensive to display large amounts of data with this widget, +/// since it must be measured twice: once to negotiate each column's +/// dimensions, and again when the table is laid out. /// -/// ## Performance considerations when wrapping [DataTable] with [SingleChildScrollView] +/// A [SingleChildScrollView] mounts and paints the entire child, even +/// when only some of it is visible. For a table that effectively handles +/// large amounts of data, here are some other options to consider: /// -/// Wrapping a [DataTable] with [SingleChildScrollView] is expensive as [SingleChildScrollView] -/// mounts and paints the entire [DataTable] even when only some rows are visible. If scrolling in -/// one direction is necessary, then consider using a [CustomScrollView], otherwise use [PaginatedDataTable] -/// to split the data into smaller pages. +/// * `TableView`, a widget from the +/// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables) +/// package. +/// * [PaginatedDataTable], which automatically splits the data into +/// multiple pages. +/// * [CustomScrollView], for greater control over scrolling effects. /// /// {@tool dartpad} /// This sample shows how to display a [DataTable] with three columns: name, age, and @@ -402,7 +404,10 @@ class DataCell { /// * [DataCell], which contains the data for a single cell in the data table. /// * [PaginatedDataTable], which shows part of the data in a data table and /// provides controls for paging through the remainder of the data. -/// * +/// * `TableView` from the +/// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables) +/// package, for displaying large amounts of data without pagination. +/// * class DataTable extends StatelessWidget { /// Creates a widget describing a data table. /// diff --git a/packages/flutter/lib/src/material/paginated_data_table.dart b/packages/flutter/lib/src/material/paginated_data_table.dart index 6bcdbc770c6..2d32a64060d 100644 --- a/packages/flutter/lib/src/material/paginated_data_table.dart +++ b/packages/flutter/lib/src/material/paginated_data_table.dart @@ -21,7 +21,9 @@ import 'material_state.dart'; import 'progress_indicator.dart'; import 'theme.dart'; -/// A Material Design data table that shows data using multiple pages. +/// A table that follows the +/// [Material 2](https://material.io/go/design-data-tables) +/// design specification, using multiple pages to display data. /// /// A paginated data table shows [rowsPerPage] rows of data per page and /// provides controls for showing other pages. @@ -52,7 +54,10 @@ import 'theme.dart'; /// See also: /// /// * [DataTable], which is not paginated. -/// * +/// * `TableView` from the +/// [two_dimensional_scrollables](https://pub.dev/packages/two_dimensional_scrollables) +/// package, for displaying large amounts of data without pagination. +/// * class PaginatedDataTable extends StatefulWidget { /// Creates a widget describing a paginated [DataTable] on a [Card]. ///