Справочник по методу CIBlockSection::GetList() в 1С-Битрикс

1С-Битрикс предоставляет множество встроенных классов и методов для работы с информационными блоками и их элементами. Одним из важных и часто используемых инструментов является метод CIBlockSection::GetList(), который служит для выборки и отображения разделов инфоблока. В данном материале мы подробно рассмотрим синтаксис метода, его параметры и несколько практических примеров.

Описание метода

CIBlockSection::GetList(
    array arOrder = array("SORT"=>"ASC"),
    array arFilter = array(),
    bool bIncCnt = false,
    array Select = array(),
    array NavStartParams = false
);

Назначение
CIBlockSection::GetList() — метод класса CIBlockSection, возвращающий список разделов информационного блока по заданному фильтру и в требуемом порядке сортировки. Данный метод не является статическим, то есть к нему обращаются через создание объекта класса CIBlockSection либо напрямую через вызов CIBlockSection::GetList().

Возвращаемое значение
Метод возвращает объект класса CIBlockResult. Это специальный объект, реализующий интерфейс для последующей итерации по результату выборки. С ним можно работать, как с любым другим результатом запроса, используя стандартные методы вроде Fetch() или GetNext() для получения строк.

Параметры

arOrder (массив)
Массив для определения порядка сортировки записей. Формат:
```
array("поле_сортировки" => "ASC|DESC", ...)
```
По умолчанию: array("SORT" => "ASC").
- Пример: array("NAME" => "ASC") — сортировать по названию раздела по возрастанию.
- Можно указывать несколько критериев сортировки. Например:
```
array("SORT" => "ASC", "NAME" => "DESC")
```
arFilter (массив)
Массив для фильтрации разделов. Формат:
```
array("поле_фильтра" => "значение", ...)
```
- Пример: array("IBLOCK_ID" => 1, "ACTIVE" => "Y") — выбирать только активные разделы из инфоблока с ID=1.
- Фильтр может включать в себя множество условий — например, поиск по ID родительского раздела, по XML_ID и т. д.
bIncCnt (логический параметр)
Отвечает за подсчет количества элементов в каждом разделе. По умолчанию имеет значение false.
- Если установить в true, в каждом разделе к результатам добавится поле ELEMENT_CNT, указывающее количество элементов, входящих в этот раздел.
Select (массив)
Позволяет указывать, какие дополнительные поля необходимо выбрать, помимо основных (таких как ID, NAME, CODE и т. д.). По умолчанию — пустой массив.
- Пример: array("UF_*") — выбрать все пользовательские поля (UF_*).
- Пример: array("PICTURE", "DESCRIPTION") — добавить поля PICTURE и DESCRIPTION к стандартному набору.
NavStartParams (массив или false)
Параметры для постраничной навигации. Если передать false, то постраничная навигация не используется, и вернутся все подходящие разделы.
- Пример:
```
array(
          "nPageSize" => 10,  // количество выводимых разделов на одной странице
          "iNumPage"  => 2    // номер текущей страницы
        )
```
- Другие варианты: array("nTopCount" => 5) — вернуть только первые 5 разделов.

Пример простого использования

Задача: получить все активные разделы из инфоблока с идентификатором 2, отсортированные по возрастанию названия, и вывести на экран их названия и идентификаторы.

<?php
// Подключаем пролог, инициализируем систему
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

// Указываем фильтр
$arFilter = array(
    "IBLOCK_ID" => 2,
    "ACTIVE"    => "Y",
);

// Указываем сортировку
$arOrder = array("NAME" => "ASC");

// Вызываем метод GetList
$sectionResult = CIBlockSection::GetList($arOrder, $arFilter, false);

// Перебираем результат
while ($section = $sectionResult->GetNext()) {
    echo "ID раздела: " . $section["ID"] . "<br>";
    echo "Название раздела: " . $section["NAME"] . "<br><br>";
}
?>

В данном примере:
- Мы не используем параметр bIncCnt, поэтому элемент ELEMENT_CNT не будет подсчитан.
- Не указываем параметр Select, значит в $section придут только стандартные поля (ID, NAME, CODE, IBLOCK_ID, IBLOCK_SECTION_ID, и т. д.).
- Не используем постраничную навигацию, передав false в качестве пятого параметра.

Пример с подсчетом элементов и пользовательскими полями

Предположим, у нас есть инфоблок с ID=3, где в разделах хранятся пользовательские поля. Нужно:
1. Получить все активные разделы.
2. Подсчитать количество элементов в каждом разделе.
3. Взять дополнительные пользовательские поля, начинающиеся на UF_.

<?php
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

$arFilter = array(
    "IBLOCK_ID" => 3,
    "ACTIVE"    => "Y",
);

$arOrder = array("SORT" => "ASC");
$bIncCnt = true;             // Подсчитываем количество элементов
$arSelect = array("UF_*");   // Выбираем все пользовательские поля
// Постраничную навигацию не используем
$NavParams = false;

$sectionResult = CIBlockSection::GetList($arOrder, $arFilter, $bIncCnt, $arSelect, $NavParams);

while ($section = $sectionResult->GetNext()) {
    echo "Раздел: " . $section["NAME"] . "<br>";
    echo "Количество элементов: " . $section["ELEMENT_CNT"] . "<br>";

    // Вывод пользовательских полей, если они есть
    // Например, если есть UF_COLOR, выведем его значение
    if (!empty($section["UF_COLOR"])) {
        echo "Цвет: " . $section["UF_COLOR"] . "<br>";
    }
    echo "<hr>";
}
?>

Данный пример наглядно демонстрирует, как с помощью bIncCnt получать количество элементов в каждом разделе, и как с помощью arSelect можно выбрать все или конкретные пользовательские поля раздела.

Пример с постраничной навигацией

Если необходимо вывести разделы с постраничной навигацией (например, по 5 разделов на страницу), удобно использовать параметр NavStartParams.

<?php
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

// Фильтр: активные разделы в инфоблоке 4
$arFilter = array("IBLOCK_ID" => 4, "ACTIVE" => "Y");

// Параметры сортировки: сначала по SORT, потом по ID
$arOrder = array("SORT" => "ASC", "ID" => "ASC");

// Параметры навигации
$NavStartParams = array(
    "nPageSize" => 5, // по 5 разделов на страницу
    "iNumPage"  => 1, // номер текущей страницы
);

// Получаем результат
$sectionResult = CIBlockSection::GetList($arOrder, $arFilter, false, array(), $NavStartParams);

// Выводим список
while ($section = $sectionResult->GetNext()) {
    echo "ID: " . $section["ID"] . "; Название: " . $section["NAME"] . "<br>";
}

// Выводим ссылки постраничной навигации
echo $sectionResult->NavPrint("Разделы");
?>

Здесь:
- arFilter ограничивает выборку активными разделами из инфоблока 4.
- Сортировка идет сначала по SORT (ASC), потом по ID (ASC).
- nPageSize => 5 — на одной странице показываем 5 разделов.
- iNumPage => 1 — выбираем первую страницу результатов.
- Для отображения ссылок постраничной навигации используется метод NavPrint(), который можно настроить под нужды верстки или заменить более гибкой навигацией через компонент.

Работа с объектом `CIBlockResult`

Метод CIBlockSection::GetList() возвращает объект класса CIBlockResult. Этот класс используется во многих местах в 1С-Битрикс для работы с выборками из базы данных. Основные его методы, которые чаще всего применяются:

GetNext()
Возвращает ассоциативный массив следующей найденной записи, с индексами в формате ["FIELD_NAME"] => "value".
Fetch()
Аналогичен GetNext(), но возвращает названия полей в формате ["FIELD_NAME"] без преобразований (в частности, поля типа PICTURE и пр. могут отличаться).
GetFields()
Возвращает массив полей текущей записи.

Обычно в шаблонах и скриптах встречается классический цикл:

while ($arSection = $sectionResult->GetNext()) {
    // Здесь $arSection уже содержит поля раздела
}

или

while ($arSection = $sectionResult->Fetch()) {
    // В этом случае поля будут в "сыром" виде
}

Заключение

Метод CIBlockSection::GetList() — один из ключевых инструментов для выборки разделов в 1С-Битрикс. Понимая принципы его работы и умея пользоваться всеми параметрами, вы можете гибко формировать списки разделов под любые задачи:

Фильтровать по разным полям (ID, CODE, ACTIVE, GLOBAL_ACTIVE, и т. д.).
Сортировать по нескольким критериям.
Включать в выборку нужные поля, в том числе пользовательские.
Использовать постраничную навигацию.
Подсчитывать количество элементов в каждом разделе.

Знание и умелое применение данного метода во многом упрощает разработку функционала, связанного с информационными блоками, и позволяет легко управлять данными через стандартные механизмы 1С-Битрикс.

Теги: справочник