При разработке и поддержке проектов на платформе 1С-Битрикс критически важно использовать современные стандарты D7 API. В этом руководстве мы детально изучим тему «Обзор компонента: Подробное руководство», разберем архитектурные особенности и предоставим готовые к интеграции примеры кода.

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

[TOC]

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

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

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

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

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

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

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

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

$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' => '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/"'
		],
	],
]

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

Существует несколько способов отобразить стандартную постраничную навигацию:
1. Передача строки с готовой версткой постраничной навигацией через параметр компонента NAV_STRING
2. Передача объекта NAV_OBJECT (наследника \Bitrix\Main\UI\PageNavigation)
3. Передача объекта 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, 
	]
);