Обзор компонента

Обзор компонента
- Параметры компонента
- Пример компонента

Системный компонент bitrix:main.ui.grid обеспечивает отображение табличного представления данных на странице и отвечает за работу вспомогательных возможностей (изменения порядка и отображения столбцов, обработку панель действий и других). Для более углубленного изучения, его можно найти в директории bitrix/components/bitrix/main.ui.grid/ вашего проекта.

Немного терминологии:

Грид - табличное представление отображаемое на странице
Бургер (кнопка действия, actions) - контекстное меню строки, позволяющее выполнять различные действия
Пресет - персональные настройки пользователя, отвечающие за отображение грида (порядок столбцов, их ширина)

Параметры компонента

Обязательные параметры компонента:

Параметр	Описание
`GRID_ID` (string)	Идентификатор грида
`HEADERS` / `COLUMNS` (array)	Набор мета-описаний столбцов. Подробнее в главе Описание столбцов
`ROWS` (array)	Набор данных для отображения строк. Подробнее в главе Строки

Другие параметры компонента:

Параметр	Описание
`TOTAL_ROWS_COUNT` (int)	Число, которое используется для отображения общего количества записей. См. примечание для поля `FOOTER`
`AJAX_ID` (string)	Уникальный идентификатор грида. Обычно генерируется через код `\CAjax::GetComponentID('bitrix:main.ui.grid', '', '')`
`NAV_PARAM_NAME` (string)	Символьный код параметра, отвечающего за наличие в url номера страницы для постраничной навигации
`CURRENT_PAGE` (int)	Номер текущей страницы (используется для постраничной навигации)
`NAV_STRING` (string)	HTML фрагмент постраничной навигации. Один из параметров, который может быть передан в комплексном поле `FOOTER` (см. примечание этого поля) или вычислен на основании параметров навигации (см. параметры навигации)
`ACTIONS_LIST` (array)	Набор действий, доступных для отображения в гриде. Подробнее в Панель действий
`PAGE_SIZES` (array)	Набор значений, используемых для вывода допустимых размеров постраничной навигации. Состоит из структур вида: `['NAME' => "5", 'VALUE' => '5'],`
`DEFAULT_PAGE_SIZE` (int)	Количество строк, отображаемых на странице. По-умолчанию: 20
`ALLOW_INLINE_EDIT` (bool)	Разрешить редактирование на странице. Алиас для значения `EDITABLE`
`SHOW_ROW_ACTIONS_MENU` (bool)	Отображать кнопку действия над строками. Алиас для значения `ROW_ACTIONS`
`SHOW_ROW_CHECKBOXES` (bool)	Отображать чек-боксы для строк
`SHOW_NAVIGATION_PANEL` (bool)	Отображать навигационную панель
`ALLOW_GROUP_ACTIONS` (bool)	Отображать панель групповых действий. Алиас для `ACTION_ALL_ROWS`
`SHOW_CHECK_ALL_CHECKBOXES` (bool)	Отображать чек-бокс для выбор всех элементов
`ALLOW_CONTEXT_MENU` (bool)	Включить поведение отображения контекстного меню для строки, по клику правой кнопкой мышки
`SHOW_GRID_SETTINGS_MENU` (bool)	Отображать шестеренку с возможностью конфигурировать грид
`SHOW_MORE_BUTTON` (bool)	Отображать кнопку “Загрузить еще”
`SHOW_PAGINATION` (bool)	Отображать постраничную навигацию
`SHOW_PAGESIZE` (bool)	Отображать переключатель количества строк на странице
`SHOW_SELECTED_COUNTER` (bool)	Отображать количество выделенных элементов на странице
`SHOW_TOTAL_COUNTER` (bool)	Отображать количество элементов на странице
`TOTAL_ROWS_COUNT_HTML` (string)	HTML для отображения количества элементов. Подробнее в главе “Количество строк”
`ALLOW_COLUMNS_SORT` (bool)	Разрешить менять столбцы местами
`ALLOW_ROWS_SORT` (bool)	Разрешить менять местами строки.
`ALLOW_ROWS_SORT_IN_EDIT_MODE` (bool)	Разрешить менять местами строки в режиме редактирования.
`ALLOW_ROWS_SORT_INSTANT_SAVE` (bool)	Немедленное сохранение при изменении порядка.
`ALLOW_HORIZONTAL_SCROLL` (bool)	Разрешить горизонтальную прокрутку таблицы
`ALLOW_PIN_HEADER` (bool)	Разрешает закреплять панель с заголовками вверху таблицы при вертикальной прокрутке
`ALLOW_SORT` (bool)	Разрешить пользователям изменять сортировку данных по тем столбцам, которые разрешены для изменения сортировки. Персональная настройка.
`ALLOW_COLUMNS_RESIZE` (bool)	Разрешить пользователям изменять ширину столбцов, для тех столбцов у которых разрешено растягивание. Персональная настройка. Алиас для `ALLOW_COLUMN_RESIZE`
`COLS_RESIZE_META` (array)	Структура описывающая ширину строк
`ENABLE_FIELDS_SEARCH` (char)	В случае если содержится значение `Y`, в списке столбцов доступен поиск
`SHOW_ACTION_PANEL` (bool)	Нужно ли отображать панель действий
`ENABLE_COLLAPSIBLE_ROWS` (bool)	Разрешить сворачивание (схлопывание) строк. Подробнее в главе Сворачивание строк
`TOP_ACTION_PANEL_RENDER_TO` (string)	Идентификатор DOM-элемента, куда будет осуществляться отрисовка панели действий
`TOP_ACTION_PANEL_PINNED_MODE` (bool)	В случае `true` прикрепляет панель действий к указанной DOM Node
`TOP_ACTION_PANEL_CLASS` (string)	Дополнительный класс к панели действий
`ADVANCED_EDIT_MODE` (bool)	Один из флагов отвечающий за возможность редактировать строки. Либо должен быть установлен флаг, либо в списке должен присутствовать хотя бы одна строка с признаком редактируемой.
`ALLOW_EDIT_SELECTION` (bool)	Если установлен, добавляет чек-боксы к строкам и разрешает выбирать строки
`ALLOW_STICKED_COLUMNS` (bool)	Если установлен в `true`, разрешает “липучие” колонки - зафиксированные при горизонтальной прокрутке.
`SETTINGS_WINDOW_TITLE` (string)	Строка, отвечающая за название поп-апа формы настроек
`HIDE_TOP_BORDER_RADIUS` (bool)	Если установлен, скрывает округление верхней части таблицы
`HIDE_BOTTOM_BORDER_RADIUS` (bool)	Если установлен, скрывает округление нижней части таблицы
`ACTIONS` (array)	Набор действий, который на момент описания включает в себя структуру вида `["list" => <data>]`, где `<data>` - содержимое `ACTIONS_LIST`
`FOOTER` (array)	Опциональный параметр, который используется для логической группировки параметров `TOTAL_ROWS_COUNT` и `NAV_STRING`. Это значит, что указанные параметры можно передавать как явно в параметрах компонента, так и через массив используя ключ `FOOTER`

Не обязательно указывать все ключи, многие из них имеют поведения по-умолчанию или перекрываются другими комбинациями ключей

Пример минимальной конфигурации

$APPLICATION->IncludeComponent(
	'bitrix:main.ui.grid',
	'',
	[
		'GRID_ID'             => 'MY_GRID_ID',
		'COLUMNS'             => $columns,
		'ROWS'                => $rows,
		'AJAX_MODE'           => 'Y',
		'AJAX_OPTION_JUMP'    => 'N',
		'AJAX_OPTION_HISTORY' => 'N',
	]
);

Описание столбцов (колонок)

Описание столбцов можно передавать любым из указанных ключей: HEADERS или COLUMNS. На текущий момент ключ HEADERS является устаревшим и используется в гридах как наследие.

Минимальный рекомендуемый набор полей для описания столбцов грида:

Параметр	Описание
`id` (string)	Уникальный идентификатор строки
`name` (string)	Отображаемое название столбца
`sort` (string)	Идентификатор поля, по которому должна производиться сортировка
`default` (bool)	Определяет должна ли отображаться колонка по умолчанию в гриде. По умолчанию колонки не отображаются

Дополнительные параметры, которые так же могут быть полезны к использованию:

Параметр	Описание
`first_order` (string)	Направление первой сортировки колонки. Возможные значения: `asc` или `desc`
`align` (string)	Выравнивание содержимого столбцов. Допустимы `center`, `left`, `right`, `justify`
`title` (string)	Текст подсказки, возникающей при наведении на заголовок столбца
`showname` (char)	В случае если значение `N` - название столбца не будет отображаться
`class` (string)	Строка с дополнительными css-классами
`width` (int)	Ширина столбца в пикселях
`editable` (bool)	Разрешено ли редактировать строчку на странице
`type` (string)	Тип данных, содержащихся в строке (доступные типы в `/modules/main/lib/grid/types.php`)
`prevent_default` (bool)	Отменяет выделение строки при клике на ячейку колонки. Может быть полезно, когда в ячейку выводится какой-то интерактивный контент.
`sticked` (bool)	Закрепляет колонку слева, при горизонтальной прокрутке.
`color` (string)	В случае если значение начинается с `#`, `rgb` или `hsl` будет добавлено как css-свойство `background-color` к ячейке, в других случаях как часть класса
`iconUrl` (string)	URL-ссылка на иконку
`iconTitle` (string)	Текст, отображаемый при наведении на иконку
`section_id` (string)	Код раздела, для группировки полей в окне выбора отображаемых полей
`hint` (string)	Текст подсказки, возникающей при наведении на значок ? в заголовке столбца таблицы
`hintInteractivity` (bool)	если true, то с подсказкой можно взаимодействовать (выделять текст, нажимать кнопки)
`hintHtml` (bool)	Если `true`, то текст подсказки интерпретируется как html

Описание строк

Строки грида формируются как набор структур с параметрами:

Параметр	Описание
`id` (string)	Уникальный идентификатор строки
`columns` (array)	Ассоциативный список Колонка => Отображаемое значение
`data` (array)	Данные для инлайн-редактирования. Например, если в columns мы можем передать данные для ячейки в том виде, в котором они должны отобразиться, то в data мы можем передать исходные данные которые нужны для редактирования.
`editableColumns` (array)	Определяет возможности редактирования ячеек колонки на уровне строки. Например, если колонка редактируемая, но для конкретной строки нужно запретить редактирование ячейки этой колонки, то в editableColumns можно указать идентификатор колонки со значением false.
`actions` (array)	Определяет действия над строкой.

Пример описания строки:

[
	'id' => 'r1',
	'columns' => [
		'HREF' => '<a href="/my/url">My url</a>',
	],
	'data' => [
		'HREF' => '/my/url',
	],
	'editableColumns' => [
		'HREF' => false,
	],
	'actions' => [
		[
			'text'    => 'Перейти к просмотру',
			'onclick' => 'document.location.href="/detail_page_view/"'
		],
		['delimiter' => true ]
		[
			'text'    => 'Редактировать',
			'onclick' => 'document.location.href="/detal_page_edit/edit/"'
		],
	],
]

Параметры навигации

Существует несколько способов отобразить стандартную постраничную навигацию:

Передача строки с готовой версткой постраничной навигацией через параметр компонента NAV_STRING
Передача объекта NAV_OBJECT (наследника \Bitrix\Main\UI\PageNavigation)
Передача объекта NAV_OBJECT (наследника CDBResult). Навигация будет осуществляться через метод GetPageNavStringEx с учетом параметров компонента из ~NAV_PARAMS

Дополнительно существует возможность использовать “ленивую загрузку” - на страницу загружается лишь то количество элементов, которое нужно при первоначальной отрисовки. Затем, в случае наличия следующих страниц, выводится кнопка для загрузки следующих. Для работы необходимо передавать следующие параметры компонента:

SHOW_MORE_BUTTON (bool) - true, в случае, если хотите использовать кнопку ленивой загрузки
ENABLE_NEXT_PAGE (bool) - true, в случае если присутствуют другие страницы
NAV_PARAM_NAME (string) - название параметра, используемого для хранения номера страницы
CURRENT_PAGE (int) - номер текущей страницы

Ленивая загрузка не отменяет действия постраничной навигации - их можно использовать одновременно

Количество строк

В случае отображения панели (SHOW_NAVIGATION_PANEL = true) есть несколько возможностей отобразить количество существующих записей (SHOW_TOTAL_COUNTER = true). Причем сделать это можно двумя способами.

С одной стороны, можно указать параметр TOTAL_ROWS_COUNT - число, которое будет отображаться как количество записей. Но не всегда есть возможность посчитать количество элементов, доступных по фильтру и отобразить - иногда эта операция является трудозатратной.

Для реализации ленивой загрузки данных, можно воспользоваться произвольным HTML-кодом, который бы в фоновом режиме опрашивал источник и подсчитывал значения или делал это по требованию пользователя.

Такой html можно установить через параметр компонента - TOTAL_ROWS_COUNT_HTML.

Сворачивание строк

При наличии опции ENABLE_COLLAPSIBLE_ROWS компонент допускает сворачивание строк (вложенные строки), однако на практике работа с подобными строками вызывает большие сложности в постраничной навигации. Мы рекомендуем избегать этой возможности и использовать другие механизмы (например используя aclips/bitrix-ui.ui-grid-collapse), поэтому в данной главе мы будем рассматривать исключительно в ознакомительных целях.

Технически, строки таблицы являются набором (перечислением строк), не имеющим явной иерархии, поэтому выстраивать последовательность необходимо самостоятельно на основе порядка следования родительских разделов. Для этого к каждой родительской строке добавляются аттрибуты:

shift (bool) - наличие сдвига у строки (должно быть true для первой строки)
expand (bool) - флаг состояния (true - раскрыт, false - закрыт)
has_child (bool) - флаг наличия вложенных строк

К каждой дочерней строке добавляются параметры:

shift (bool) - наличие сдвига у строки
depth (int) - глубина сдвига (в единицах). Величина сдвига будет рассчитана как 20px умноженное на глубину сдвига
parent_id (string) - идентификатор строки родителя

Пример компонента

use \Bitrix\Main\Grid\Options;
use \Bitrix\Main\UI\PageNavigation;

$gridId = 'our_custom_grid_id';

$gridOptions = new Options($gridId);

$sort = $gridOptions->GetSorting([
	'sort' => ['ID' => 'DESC'],
	'vars' => ['by' => 'by', 'order' => 'order']
]);
$navOption = $gridOptions->GetNavParams();

$pageSizes = [ 
	['NAME' => "5", 'VALUE' => '5'], 
	['NAME' => '10', 'VALUE' => '10'], 
	['NAME' => '20', 'VALUE' => '20'], 
	['NAME' => '50', 'VALUE' => '50'], 
	['NAME' => '100', 'VALUE' => '100'] 
];

$nav = (new PageNavigation('our_custom_grid_nav'))
	->allowAllRecords(false)
	->setPageSize($navOption['nPageSize'])
	->setPageSizes($pageSizes)
	;

$nav->initFromUri();

$columns = [
	['id' => 'ID', 'name' => 'ID', 'sort' => 'ID', 'default' => true], 
	['id' => 'DATE', 'name' => 'Дата', 'sort' => 'DATE', 'default' => true], 
	['id' => 'AMOUNT', 'name' => 'Сумма', 'sort' => 'AMOUNT', 'default' => true], 
	['id' => 'PAYER_INN', 'name' => 'ИНН Плательщика', 'sort' => 'PAYER_INN', 'default' => true], 
	['id' => 'PAYER_NAME', 'name' => 'Плательщик', 'sort' => 'PAYER_NAME', 'default' => true], 
	['id' => 'IS_SPEND', 'name' => 'Тип операции', 'sort' => 'IS_SPEND', 'default' => true], 
];

$list = [
	[
		'id'   => 'unique_row_id_1',
		'data' => [
			'ID'          => '1',
			'DATE'        => '',
			'~DATE'       => '',
			'AMOUNT'      => '1200 руб.',
			'~AMOUNT'     => '1200|RUB',
			'PAYER_INN'   => '12345678',
			'~PAYER_INN'  => '12345678',
			'PAYER_NAME'  => 'Иванов Иван',
			'~PAYER_NAME' => '123',
			'IS_SPEND'    => 'Да',
			'~IS_SPEND'   => 'Y',
		],
		'actions' => [
			[
				'text'    => 'Редактировать',
				'onclick' => 'document.location.href="/accountant/reports/1/edit/"'
			],
			[
				'text'    => 'Удалить',
				'onclick' => 'document.location.href="/accountant/reports/1/delete/"'
			]
		],
	],
];

$APPLICATION->IncludeComponent(
	'bitrix:main.ui.grid',
	'',
	[
		'GRID_ID'    => $gridId,
		'COLUMNS'    => $columns, 
		'ROWS'       => $list,
		'NAV_OBJECT' => $nav, 
		'PAGE_SIZES' => $pageSizes,

		'AJAX_MODE' => 'Y', 
		'AJAX_ID'   => \CAjax::getComponentID('bitrix:main.ui.grid', '.default', ''), 
		'AJAX_OPTION_JUMP'          => 'N', 
		'AJAX_OPTION_HISTORY'       => 'N' ,

		'SHOW_ROW_CHECKBOXES' => false, 
		'SHOW_CHECK_ALL_CHECKBOXES' => false, 
		'SHOW_ROW_ACTIONS_MENU'     => true, 
		'SHOW_GRID_SETTINGS_MENU'   => true, 
		'SHOW_NAVIGATION_PANEL'     => true, 
		'SHOW_PAGINATION'           => true, 

		'SHOW_SELECTED_COUNTER'     => false, 
		'SHOW_TOTAL_COUNTER'        => true, 
		'SHOW_PAGESIZE'             => true, 
		'ALLOW_COLUMNS_SORT'        => true, 
		'ALLOW_COLUMNS_RESIZE'      => true, 
		'ALLOW_HORIZONTAL_SCROLL'   => true, 
		'ALLOW_SORT'                => true, 
		'ALLOW_PIN_HEADER'          => true, 
	]
);

Разработка > UI > Таблицы > Обзор

Обзор компонента

Table of Contents

Параметры компонента

Описание столбцов (колонок)

Описание строк

Параметры навигации

Количество строк

Сворачивание строк

Пример компонента

Разработка > UI > Таблицы > Обзор

#Обзор компонента

Table of Contents

#Параметры компонента

#Описание столбцов (колонок)

#Описание строк

#Параметры навигации

#Количество строк

#Сворачивание строк

#Пример компонента

Обзор компонента

Параметры компонента

Описание столбцов (колонок)

Описание строк

Параметры навигации

Количество строк

Сворачивание строк

Пример компонента