Как добавить пользовательскую команду (кнопку) на общую форму отчета в 1С:БСП?

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

Общий принцип работы с формой отчета БСП

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

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

Мы проанализируем пошаговый процесс добавления команды, которая будет полноценно функционировать, вызывая код из модуля объекта отчета или из общего модуля, способного взаимодействовать с клиентской частью.

Пошаговая инструкция по добавлению команды на форму отчета

Для добавления команды на общую форму отчета в БСП нам потребуется модифицировать несколько мест в коде нашего отчета. Разберем каждый шаг подробно.

1. Инициализация настройки формы в модуле менеджера отчета

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

1. Откройте модуль менеджера вашего отчета (например, Отчет.ВашОтчет.МодульМенеджера).
2. Найдите или создайте экспортную процедуру НастроитьВариантыОтчета. Эта процедура вызывается подсистемой отчетов БСП для конфигурирования вариантов.
3. В этой процедуре установите свойство ОпределитьНастройкиФормы объекта НастройкиОтчета в значение Истина. Это даст БСП сигнал, что она должна вызвать процедуру ОпределитьНастройкиФормы в модуле объекта отчета.

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

// В модуле менеджера отчета: Отчет.ВашОтчет.МодульМенеджера

Процедура НастроитьВариантыОтчета(НастройкиОтчета) Экспорт
    НастройкиОтчета.ОпределитьНастройкиФормы = Истина;
    // Дополнительные настройки вариантов отчета, если есть
КонецПроцедуры

Этот код является критически важным, поскольку без него БСП не будет знать, что нужно вызывать дополнительный код для настройки формы вашего отчета.

2. Определение настроек формы в модуле объекта отчета

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

1. Откройте модуль объекта вашего отчета (например, Отчет.ВашОтчет.МодульОбъекта).
2. Создайте экспортную процедуру ОпределитьНастройкиФормы(Форма, КлючВарианта, Настройки). Эта процедура вызывается БСП для каждого варианта отчета, если в модуле менеджера было установлено ОпределитьНастройкиФормы = Истина.
3. В этой процедуре установите свойство Настройки.События.ПриСозданииНаСервере = Истина. Это указывает, что при создании формы отчета на сервере будет вызван обработчик ПриСозданииНаСервере, где мы и будем добавлять команду.

Пример кода:

// В модуле объекта отчета: Отчет.ВашОтчет.МодульОбъекта

Процедура ОпределитьНастройкиФормы(Форма, КлючВарианта, Настройки) Экспорт
    Настройки.События.ПриСозданииНаСервере = Истина;
    // Можно также добавить другие настройки или элементы управления
    // Например, если требуется изменить стандартные кнопки или добавить поля
КонецПроцедуры

Установка ПриСозданииНаСервере = Истина является ключевым моментом, поскольку именно в этом обработчике мы получим доступ к объекту формы и сможем программно добавить на нее новые элементы и команды.

3. Добавление команды и элемента на форме в обработчике ПриСозданииНаСервере

Теперь, когда мы подготовили почву, мы можем непосредственно добавлять команду на форму. Это делается в процедуре ПриСозданииНаСервере модуля объекта отчета.

1. В модуле объекта отчета создайте или модифицируйте экспортную процедуру ПриСозданииНаСервере(Форма, Отказ, СтандартнаяОбработка). Эта процедура будет вызвана БСП на сервере перед тем, как форма будет показана пользователю.
2. Внутри этой процедуры мы можем программно создать новую команду, установить ее свойства и разместить на форме.

Шаги по добавлению команды (включая подключаемые команды БСП):

1. Добавление команды в коллекцию команд формы: Используйте метод Форма.Команды.Добавить("ИмяКоманды"). Присвойте команде уникальное имя.
2. Установка свойств команды: Задайте Заголовок (текст на кнопке), Картинку (если требуется), Отображение (например, ОтображениеКнопки.Текст или ОтображениеКнопки.КартинкаИТекст).
3. Установка действия команды: Это самый важный шаг. Для того чтобы команда была обработана в клиентском контексте, мы не можем просто указать имя серверной процедуры. Вместо этого мы используем специальный механизм БСП. Установите НоваяКоманда.Действие = "Подключаемый_Команда". Это универсальный обработчик БСП, который будет перенаправлять вызовы команд в специализированный общий модуль.
4. Размещение команды на форме: После того как команда создана, ее необходимо вывести на форму в виде кнопки. Для этого можно использовать вспомогательные функции БСП, например, ОтчетыСервер.ВывестиКоманду(). Эта функция позволяет указать, в какую группу элементов формы должна быть добавлена кнопка.

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

// В модуле объекта отчета: Отчет.ВашОтчет.МодульОбъекта

Процедура ПриСозданииНаСервере(Форма, Отказ, СтандартнаяОбработка) Экспорт
    // Создаем новую команду
    НоваяКоманда = Форма.Команды.Добавить("МояДополнительнаяКоманда");
    НоваяКоманда.Заголовок = НСтр("ru = 'Выполнить особое действие'");
    НоваяКоманда.Картинка = БиблиотекаКартинок.ЗаписатьФайл; // Пример картинки
    НоваяКоманда.Отображение = ОтображениеКнопки.КартинкаИТекст;

    // Указываем, что действие будет обрабатываться через универсальный обработчик БСП
    // Имя команды "МояДополнительнаяКоманда" будет передано в обработчик
    НоваяКоманда.Действие = "Подключаемый_Команда";

    // Размещаем команду на форме, например, в группу "КомандыОтчета"
    ОтчетыСервер.ВывестиКоманду(Форма, НоваяКоманда, "КомандыОтчета");

    // Также можно добавить другие элементы управления
    // Например, поле ввода для какого-либо параметра
    // НовыйЭлемент = Форма.Элементы.Добавить("МоеПоле", Тип("ПолеФормы"), Форма.Элементы.ГруппаПараметров);
    // НовыйЭлемент.Вид = ВидПоляФормы.ПолеВвода;
    // НовыйЭлемент.ПутьКДанным = "Объект.МойРеквизит";
    // ... и т.д.
КонецПроцедуры

В этом примере мы используем "Подключаемый_Команда" как универсальный обработчик. Это позволяет БСП перехватывать вызов любой команды, у которой указано такое действие, и направлять его в предопределенный общий модуль.

4. Реализация обработчика команды

Последний и самый важный шаг — это создание кода, который будет выполняться при нажатии на нашу кнопку. Поскольку действие команды указано как "Подключаемый_Команда", БСП будет искать обработчик в специализированном общем модуле.

1. Откройте общий модуль ОтчетыКлиентПереопределяемый (или аналогичный общий модуль, который используется в вашей версии БСП для переопределяемых действий).
2. Найдите или создайте процедуру ОбработчикКоманды(ИмяКоманды, ФормаОтчета, Команда). Эта процедура должна быть помечена директивой &НаКлиенте, так как она будет выполняться на стороне клиента.
3. Внутри этой процедуры мы используем условный оператор для определения, какая именно команда была вызвана, основываясь на ее ИмяКоманды.
4. В соответствующей ветке Если реализуйте вашу логику. Здесь вы можете вызывать другие процедуры, как клиентские (в этом же или другом клиентском общем модуле), так и серверные (с помощью директивы &НаСервереБезКонтекста или &НаСервере).

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

// В общем модуле: ОтчетыКлиентПереопределяемый (или подобном)

// Обработчик команды
//
// Параметры:
//   ИмяКоманды      - Строка - Имя команды.
//   ФормаОтчета     - ФормаОтчета - Форма отчета.
//   Команда         - ОбъектКоманда - Объект команды, для которого вызван обработчик.
//
&НаКлиенте
Процедура ОбработчикКоманды(ИмяКоманды, ФормаОтчета, Команда) Экспорт
    Если ИмяКоманды = "МояДополнительнаяКоманда" Тогда
        // Здесь выполняется код, когда пользователь нажимает на нашу кнопку
        Сообщить("Вы нажали на 'Выполнить особое действие'!");
        
        // Пример вызова серверной процедуры (если необходимо)
        // ВыполнитьОсобоеДействиеНаСервере(ФормаОтчета.ОтчетОбъект);
        
        // Пример вызова другой клиентской процедуры
        // МойКлиентскийМодуль.ОбработатьНажатиеКнопки(ФормаОтчета, Команда);
    Иначе
        // Обработка других команд, если они есть
    КонецЕсли;
КонецПроцедуры

// Пример серверной процедуры, которая может быть вызвана из клиентского обработчика
&НаСервереБезКонтекста
Процедура ВыполнитьОсобоеДействиеНаСервере(ОтчетОбъект)
    // Здесь код, который выполняется на сервере
    // Например, запись данных, сложные расчеты и т.д.
    Сообщить("Особое действие выполнено на сервере для отчета " + ОтчетОбъект.Метаданные().Имя);
КонецПроцедуры

Использование универсального обработчика Подключаемый_Команда и модуля ОтчетыКлиентПереопределяемый позволяет централизованно управлять командами, добавляемыми на формы отчетов, и обходить ограничения на прямой вызов клиентских процедур из динамически добавленных элементов без явного указания в метаданных.

Важные аспекты и нюансы

При работе с механизмами расширения форм в БСП следует учитывать несколько дополнительных моментов.

Размещение команды

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

Расширение функционала, помимо кнопок и дополнительных отборов

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

Дополнительные отчеты и обработки

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

Изменения в БСП 2.4 и выше

В более новых версиях БСП (начиная с 2.4) произошли некоторые изменения в организации подключаемых команд. Если ранее для разных целей (печать, ввод на основании, меню отчетов) использовались разные общие модули ("УправлениеПечатью", "ВводНаОсновании", "МенюОтчеты"), то в БСП 2.4 и выше эти функции были унифицированы и централизованы в общем модуле ПодключаемыеКоманды. Это означает, что если вы разрабатываете для более новой версии БСП, вам, возможно, потребуется изучить этот модуль и адаптировать вызовы соответствующих процедур, но общий принцип динамического добавления элементов и их обработки через универсальный диспетчер сохраняется.

Отладка

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

Заключение

Добавление пользовательских команд на общую форму отчета в 1С:БСП — это мощный инструмент для расширения функционала типовых решений. Несмотря на то, что процесс включает несколько шагов и требует понимания архитектуры БСП, он является стандартным и хорошо документированным. Следуя приведенной инструкции, мы можем создавать гибкие и функциональные отчеты, которые полностью отвечают специфическим потребностям пользователей, сохраняя при этом интеграцию со стандартными механизмами системы.