DataTable

DataTable показывает данные строками и колонками — списки сотрудников, товарные остатки, заказы, отчёты.

Таблицу можно разбить на страницы, включить сортировку и поиск, разрешить выбор строк и горизонтальную прокрутку на узких экранах.

Как добавить

1. Откройте Widget Palette и найдите DataTable во вкладке Layout Elements.
2. Перетащите виджет на холст или вставьте в дерево виджетов.
3. Внутри лежат две заготовки:
   • DataTableHeader — заголовок колонки. Название меняется во вложенном Text.
   • DataTableCell — ячейка строки. По умолчанию внутри Text, но можно положить любой виджет.
4. Число колонок задаётся полем Paginated Data Table Properties > Number of Columns.

Как заполнить данными

Разберём на списке сотрудников из Firestore:

1. Получите записи: добавьте Query Collection на родительский виджет — страницу или колонку. Другой вариант — выполнить действие Query Collection при загрузке страницы и сохранить результат в состояние страницы.
2. Выделите DataTable и сгенерируйте динамических потомков из полученного списка.
3. В каждой DataTableCell > Text подставьте нужное поле текущей записи.

Поиск

Искать по уже загруженным записям умеет Simple Search:

1. Добавьте TextField, куда пользователь введёт запрос.
2. Повесьте действие Simple Search на подходящее событие поля — On Changed или On Submit.
3. Выберите Documents как тип поиска, а источником укажите полный список записей.
4. Search Term возьмите из состояния поля ввода и отметьте, по каким полям искать.
5. Результат сохраните в состояние страницы.
6. При генерации строк таблицы используйте значение по условию: запрос пустой — показываем полный список, иначе найденный.
7. Когда пользователь очистит поле, сбросьте сохранённый результат поиска, чтобы таблица снова показала всё.

Выбор строк

Строки отмечают галочками, когда с выбранным нужно что-то сделать — отредактировать, удалить, выгрузить.

1. Создайте переменную состояния страницы под список выбранных записей.
2. Выделите DataTable и включите Paginated Data Table Properties > Selectable.
3. На кнопке, которая обрабатывает выбор, добавьте действие Update Page State.
4. Индексы выбранных строк лежат в Widget State > DataTable Selected Rows. Передайте их вместе со списком, из которого сгенерированы строки, в собственную функцию. Если таблица отфильтрована или отсортирована, передавать нужно именно этот список, а не исходный.

Функция ниже возвращает записи сотрудников по выбранным индексам:

List<EmployeesRecord> getSelectedEmployees(
  List<EmployeesRecord> employees,
  List<int> selectedIndices,
) {
  /// MODIFY CODE ONLY BELOW THIS LINE

  return selectedIndices
      .where((index) => index >= 0 && index < employees.length)
      .map((index) => employees[index])
      .toList();

  /// MODIFY CODE ONLY ABOVE THIS LINE
}

События

Действия на события таблицы добавляются во вкладке Actions панели свойств.

On Sort Changed

On Sort Changed срабатывает, когда пользователь щёлкает по заголовку сортируемой колонки. Событие отдаёт два значения:

• Sorted Column Index — номер колонки, нумерация с нуля: 0 — первая.
• Is Ascending — направление сортировки: по возрастанию или нет.

Чтобы включить сортировку:

1. Выделите каждый DataTableHeader, по которому разрешено сортировать, и включите Sortable.
2. Выделите DataTable и добавьте действие на On Sort Changed.
3. Передайте Sorted Column Index, Is Ascending и список, из которого сгенерированы строки, в собственную функцию.
4. Результатом функции обновите переменную состояния страницы, из которой строится таблица.

Пример: функция сортирует копию списка, не трогая исходный.

List<EmployeesRecord> sortEmployees(
  List<EmployeesRecord> employees,
  bool isAscending,
  int sortColumnIndex,
) {
  /// MODIFY CODE ONLY BELOW THIS LINE

  final sortedEmployees = List<EmployeesRecord>.from(employees);

  switch (sortColumnIndex) {
    case 0:
      sortedEmployees.sort((a, b) => a.name.compareTo(b.name));
      break;
    case 1:
      sortedEmployees.sort((a, b) => a.age.compareTo(b.age));
      break;
    case 2:
      sortedEmployees.sort((a, b) => a.position.compareTo(b.position));
      break;
  }

  return isAscending
      ? sortedEmployees
      : sortedEmployees.reversed.toList();

  /// MODIFY CODE ONLY ABOVE THIS LINE
}

On Page Changed

On Page Changed срабатывает при переходе на другую страницу таблицы. Событие отдаёт Current Row Index — номер первой строки новой страницы, нумерация с нуля. Если на странице по 25 строк, вторая начнётся с индекса 25.

Для API с постраничной выдачей по смещению:

1. Добавьте вызов API на On Page Changed.
2. Передайте Current Row Index в параметр offset.
3. Передайте настроенное число строк на странице в параметр limit.
4. Результатом обновите список, из которого строится таблица.

Как передавать динамические значения в вызов API — в разделе про параметры запроса.

On Rows Per Page Changed

On Rows Per Page Changed срабатывает, когда пользователь меняет число строк на странице.

Если данные приходят из API:

1. Выделите DataTable и добавьте действие на On Rows Per Page Changed.
2. Новым числом строк обновите параметр limit или соответствующую переменную состояния.
3. Сбросьте сохранённое смещение в 0.
4. Вызовите API заново и обновите список, из которого строится таблица.

Настройки

Выделите DataTable — всё настраивается в панели свойств.

Пагинация

• Number of Columns — число колонок.
• Number of Rows (Optional) — общее число строк. Оставьте пустым, чтобы считалось по сгенерированным строкам.
• UI Builder Number of Rows (Optional) — сколько строк-заглушек показывать на холсте при вёрстке. На готовое приложение не влияет.
• Paginated — разбить строки на страницы. Выключите, чтобы получить обычную таблицу без листания.
  • Hide Paginator — спрятать переключатель страниц.
  • Show First And Last Buttons — добавить кнопки перехода на первую и последнюю страницу.
• Selectable — разрешить отмечать строки.
  • Rebuild Page on Select — появляется при включённом Selectable. Перестраивает страницу при каждом изменении выбора, чтобы связанные с ним виджеты обновлялись сразу.

Размеры

• Table Width и Table Height — габариты таблицы в пикселях или процентах.
• Header Row Height — высота строки заголовков.
• Data Row Height — высота остальных строк.
• Column Spacing — расстояние между колонками.

Минимальная ширина

Layout Properties > Min Width задаёт минимальную ширину таблицы — в пикселях или процентах.

Если она больше доступной ширины экрана, таблица начинает прокручиваться вбок. Иначе колонки сжимаются, а текст в ячейках переносится по одному слову.

Цвета

• Header Row Color — фон строки заголовков.
• Row Color — фон строк.
• Alternate Row Color — фон чётных строк; чередование заметно облегчает чтение широких таблиц.
• Sort Icon Color — цвет значка на сортируемых колонках.
• Border Radius — скругление углов: одно значение на все четыре или каждый угол отдельно.

Разделители

• Hide Default Dividers убирает линии между строками, которые таблица рисует сама.
• Add Horizontal Dividers и Add Vertical Dividers добавляют собственные разделители между строками и колонками. Для каждого настраиваются Color и Thickness.

Цвета флажков

Когда включён Selectable, у флажка настраиваются:

• Selected Fill Color — заливка отмеченного;
• Unselected Fill Color — заливка неотмеченного;
• Selected Border Color — рамка отмеченного;
• Unselected Border Color — рамка неотмеченного;
• Check Color — цвет самой галочки.

Что учесть

• Заголовки колонок держите короткими и понятными.
• Числа выравнивайте одинаково — так их проще сравнивать глазами.
• На узких экранах не показывайте много колонок сразу. Для сложного мобильного макета лучше выводить каждую запись карточкой в ListView или Card.
• Число строк на странице подбирайте так, чтобы таблица оставалась читаемой, но и листать не приходилось без конца.