Как правильно добавить новый вариант отчета в БСП и решить проблемы с КлючВарианта

← На главную

При разработке в современных конфигурациях на базе Библиотеки стандартных подсистем (БСП) версии 3.0 и выше (например, ЗУП 3.1, ERP 2.5, КА 2.5), программисты часто сталкиваются с тем, что программно добавленные варианты отчетов ведут себя непредсказуемо. Либо КлючВарианта остается пустым, что ломает логику типовых проверок, либо отчет «рассыпается» в панели отчетов, превращаясь в кучу отдельных записей вместо одной группы.

В этой статье мы подробно разберем, как правильно регистрировать новые варианты отчетов в модуле менеджера, как управлять их видимостью и почему типовые функции могут не возвращать ключ варианта. Проанализируем ситуацию на примере типового отчета и подсистемы «Зарплата и кадры».

Разбор проблемы 1: Почему КлючВарианта возвращает пустое значение

Многие разработчики используют конструкцию ЗарплатаКадрыОтчеты.КлючВарианта(КомпоновщикНастроек) для определения текущего контекста отчета. Однако после добавления нового предопределенного варианта в СКД и его описания в коде, эта функция может возвращать пустую строку. Выясним причину этого поведения.

Функция получения ключа варианта работает не просто со строковым именем из схемы компоновки данных (СКД). Она анализирует ПользовательскиеНастройки и связывает их с записями в справочнике «Варианты отчетов». Рассмотрим основные причины неудачи:

Отсутствие регистрации в справочнике: Когда вы добавляете вариант в конфигураторе, БСП должна «узнать» о нем и создать соответствующую запись в справочнике «Варианты отчетов». Пока эта запись не создана или не сопоставлена, система не может идентифицировать текущие настройки компоновщика как ваш новый вариант.
Несовпадение имен: Важно, чтобы имя варианта в СКД (вкладка «Настройки» в конфигураторе) и параметр КлючВарианта, который вы передаете в функцию ВариантыОтчетов.ОписаниеВарианта, совпадали с точностью до символа и регистра.
Инициализация формы: Если вы открываете отчет не через стандартную панель отчетов, а, например, программно или из избранного, параметры формы могут не содержать КлючВарианта, и компоновщик не успевает инициализироваться нужными метаданными.

Для решения этой проблемы необходимо убедиться, что в модуле менеджера отчета в процедуре НастроитьВариантыОтчета правильно заполнено описание. Разберем пример кода:


Процедура НастроитьВариантыОтчета(Настройки, НастройкиОтчета) Экспорт
    // Создаем описание для нашего нового варианта
    НастройкиВарианта = ВариантыОтчетов.ОписаниеВарианта(Настройки, НастройкиОтчета, "Т2ВУС");
    НастройкиВарианта.Описание = НСтр("ru = 'Личная карточка Т2 ВУС'");
    
    // Важный момент для ЗУП/ERP: вызываем типовое переопределение
    ЗарплатаКадрыОтчеты.КонфигурацияНастроитьВариантыОтчета(Настройки, НастройкиОтчета);
КонецПроцедуры

Разбор проблемы 2: Управление отображением в панели отчетов

Часто возникает ситуация: вы добавили новый вариант в существующий типовой отчет (например, в «Личные карточки»), но вместо того, чтобы появиться внутри этого отчета, ваш вариант выводится в общем списке как отдельный полноценный отчет. Это загромождает интерфейс пользователя.

Существует распространенное заблуждение, что все предопределенные варианты всегда выводятся отдельно. На самом деле, поведением можно и нужно управлять через структуру ОписаниеВарианта. Посмотрим, какие свойства за это отвечают:

Свойство ВидимостьПоУмолчанию: Если установить его в Ложь, вариант не будет виден в основной панели отчетов, но его можно будет выбрать внутри самого отчета через меню «Выбрать вариант...». Это идеальный способ «спрятать» вариант внутри родительского отчета.
Свойство Размещение: Позволяет указать, в каких подсистемах должен отображаться вариант.
Группировка по Идентификатору: БСП группирует варианты вокруг объекта метаданных. Если ваш вариант привязан к тому же отчету (объекту метаданных), он должен подчиняться общим правилам отображения этого отчета.

Проанализируем, как скрыть вариант из общего списка, оставив его доступным внутри отчета:


НастройкиВарианта = ВариантыОтчетов.ОписаниеВарианта(Настройки, НастройкиОтчета, "Т2ВУС");
НастройкиВарианта.ВидимостьПоУмолчанию = Ложь;
НастройкиВарианта.Описание = НСтр("ru = 'Специализированный вариант, доступный только из меню выбора'");

Шаг 1: Правильная регистрация нового варианта

Чтобы избежать ошибок с пустыми ключами и неправильным отображением, пройдем по шагам процесса регистрации. Процесс в БСП 3.0+ разделен на описание в коде и обновление данных в ИБ.

1. Добавление в СКД. В конфигураторе откройте схему компоновки данных вашего отчета. На вкладке «Настройки» добавьте новый вариант. Запомните его имя (например, ВариантТ2ВУС).

2. Описание в модуле менеджера. В модуле менеджера отчета найдите (или создайте) процедуру НастроитьВариантыОтчета. Используйте метод ВариантыОтчетов.ОписаниеВарианта. Обязательно передавайте в третий параметр именно то имя, которое вы указали в СКД.

3. Привязка к подсистемам. Если вы хотите, чтобы отчет появился в конкретном разделе интерфейса, используйте настройки размещения. Однако помните, что в типовых конфигурациях (ЗУП, ERP) часто используется централизованная настройка через подсистему «Зарплата и кадры».


// Пример правильного заполнения размещения
НастройкиВарианта.Размещение.Очистить();
НовоеРазмещение = НастройкиВарианта.Размещение.Добавить();
НовоеРазмещение.Подсистема = Метаданные.Подсистемы.Кадры;
НовоеРазмещение.ВариантВарианта = "ВариантТ2ВУС";

Шаг 2: Обновление справочников вариантов отчетов

Это критически важный этап, о котором часто забывают. После того как вы написали код в конфигураторе, база данных (справочник «Варианты отчетов») еще ничего не знает о ваших изменениях. Система должна просканировать метаданные и обновить свои внутренние таблицы.

Существует три способа запустить это обновление:

Параметр запуска /СведенияОбОбновленииИБ. Запустите сеанс 1С:Предприятие с этим ключом. Это инициирует выполнение всех обработчиков обновления, включая обновление списка вариантов отчетов.
Программный вызов. В консоли кода или через обработку выполните метод Справочники.ВариантыОтчетов.ОбновитьДанныеСправочника(). Это принудительно синхронизирует метаданные конфигуратора со справочником в базе.
Версионирование. Если вы выпускаете расширение или новую версию конфигурации, БСП сама запустит обновление при первом входе, если номер версии метаданных изменился.

Важно: Без этого шага КлючВарианта почти всегда будет пустым, так как система не найдет связи между «настройками в памяти» и «записью в справочнике».

Шаг 3: Особенности подсистемы «Зарплата и Кадры» (ЗУП 3.1)

В конфигурации Зарплата и Управление Персоналом логика БСП обернута в дополнительные сервисные функции. Для корректной работы отчетов в этой конфигурации мы рекомендуем всегда проверять вызовы в общем модуле ЗарплатаКадрыОтчеты.

Рассмотрим, как работает функция получения ключа в ЗУП. Она пытается извлечь ключ не только из компоновщика, но и из кешированных данных формы. Если вы работаете с расширением, убедитесь, что ваш новый вариант отчета также корректно подхватывается процедурами переопределения.

Проанализируем типичный алгоритм инициализации отчета:

При создании формы вызывается ОпределитьНастройкиФормы.
Система ищет настройки в справочнике по связке ОбъектМетаданных + ИмяВарианта.
Если вы используете расширение, убедитесь, что вы не просто добавили вариант в СКД, но и обновили модуль менеджера основного отчета (или использовали соответствующие зацепки в расширении).