Своя команда на форме 1С без изменения конфигурации
Содержание
Кнопку через внешнюю обработку
1С добавляют двумя способами. Если кнопка нужна на форме самой обработки — создайте команду формы, перетащите её в командную панель и напишите обработчик. Если кнопка нужна в форме типового документа или справочника — зарегистрируйте обработку в разделе Администрирование → Печатные формы, отчеты и обработки как «Заполнение объекта», и команда появится в форме без снятия конфигурации с поддержки.
Первый способ подходит для служебных инструментов: загрузки, групповой правки, выгрузки. Второй — когда пользователь должен нажимать кнопку прямо в документе, например «Проставить комментарий» в реализации. Ниже оба способа на примерах для управляемых форм платформы 8.3 и типовых конфигураций на БСП (Бухгалтерия 3.0, ЗУП 3.1, УТ 11).
Выбор способа и подготовка внешней обработки
Сначала решите, где должна жить кнопка. От этого зависит, что писать в модулях.
| Способ | Где появится кнопка | Что меняется в базе | Когда выбирать |
|---|---|---|---|
| Команда на форме обработки | Только в окне обработки | Ничего | Разовые и служебные задачи |
| Регистрация «Заполнение объекта» | В форме документа или справочника | Запись в справочнике дополнительных обработок | Кнопка нужна пользователям в типовой форме |
| Расширение конфигурации | Где угодно, включая новые поля | Подключается расширение | Нужно менять форму глубже, чем добавить команду |
Внешняя обработка сама по себе форму документа изменить не может. Кнопку в чужую форму встраивает механизм БСП «Дополнительные отчеты и обработки». Если его нет или нужна сложная доработка формы, используйте расширение.
Создание файла обработки
- Откройте Конфигуратор той базы, для которой пишете обработку. Так в коде будут доступны её типы: справочники, документы, реквизиты.
- Выберите
Файл → Новый → Внешняя обработка. - На вкладке «Основные» задайте имя латиницей или кириллицей без пробелов, например
ПроставитьКомментарий. - На вкладке «Формы» нажмите «Добавить», оставьте тип «Форма обработки» и отметьте её как основную.
- Сохраните файл с расширением
.epf.
Сохраняйте файл сразу и регулярно. Внешняя обработка не входит в конфигурацию, и при закрытии Конфигуратора несохранённые правки пропадут.
Команда формы и кнопка в командной панели
В управляемой форме кнопка — это только внешний вид. Действие живёт в команде. Сначала создают команду, потом кнопку, которая на неё ссылается.
Пошагово в редакторе формы
- Откройте форму обработки двойным щелчком.
- В правом верхнем окне перейдите на вкладку «Команды» и нажмите «Добавить». Появится команда
Команда1. - В палитре свойств задайте имя, например
ЗаполнитьСписок, и заголовок «Заполнить список». - В свойстве «Действие» нажмите на значок лупы. Платформа спросит, где создать обработчик — выберите «Создать на клиенте и процедуру на сервере».
- Перетащите команду мышью в дерево элементов, в узел «Командная панель формы». Появится кнопка.
Готово: кнопка видна в окне обработки. Её внешний вид настраивают в свойствах элемента-кнопки, а не команды.
| Свойство кнопки | Что даёт |
|---|---|
| Отображение | Только текст, только картинка или картинка и текст |
| Картинка | Значок из библиотеки картинок конфигурации |
| Кнопка по умолчанию | Срабатывает по Ctrl+Enter |
| Видимость, Доступность | Скрыть или заблокировать кнопку |
| Сочетание клавиш | Своё сочетание для вызова команды |
Кнопку можно поставить не только в командную панель. Перетащите команду в любое место формы — получится обычная кнопка рядом с полями.
Кнопка, добавленная кодом
Иногда кнопку создают программно: например, набор команд зависит от настроек. Для этого в обработчике ПриСозданииНаСервере добавляют команду и элемент:
&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
НоваяКоманда = Команды.Добавить("ОбновитьСписокДинамически");
НоваяКоманда.Заголовок = "Обновить список";
НоваяКоманда.Действие = "ОбновитьСписокДинамически";
НоваяКнопка = Элементы.Добавить("КнопкаОбновитьСписок", Тип("КнопкаФормы"), КоманднаяПанель);
НоваяКнопка.ИмяКоманды = "ОбновитьСписокДинамически";
КонецПроцедуры
&НаКлиенте
Процедура ОбновитьСписокДинамически(Команда)
ЗаполнитьСписокНаСервере();
КонецПроцедуры
Процедура из свойства Действие должна существовать в модуле формы и принимать параметр Команда. Иначе форма не откроется с ошибкой о ненайденном обработчике.
Код обработчика нажатия
Обработчик команды всегда начинается на клиенте. Всё, что читает или пишет базу, выносите в серверную процедуру.
Клиент и сервер: какую директиву ставить
- 🖥️
&НаКлиенте— диалоги, вопросы пользователю, открытие форм. Запросов к базе здесь нет. - 🗄️
&НаСервере— запросы, запись объектов. Доступны реквизиты формы, но форма передаётся на сервер целиком. - ⚡
&НаСервереБезКонтекста— быстрее, форма не передаётся. Нет доступа кОбъекти элементам формы, данные передают параметрами.
Пример: заполнить табличную часть по нажатию
В обработке создана табличная часть Документы с колонками Документ (тип ДокументСсылка.РеализацияТоваровУслуг) и Сумма. Реквизиты обработки НачалоПериода и КонецПериода типа «Дата».
&НаКлиенте
Процедура ЗаполнитьСписок(Команда)
Если Не ЗначениеЗаполнено(Объект.НачалоПериода) Тогда
ПоказатьПредупреждение(, "Укажите начало периода.");
Возврат;
КонецЕсли;
ЗаполнитьСписокНаСервере();
КонецПроцедуры
&НаСервере
Процедура ЗаполнитьСписокНаСервере()
Запрос = Новый Запрос;
Запрос.Текст =
"ВЫБРАТЬ
| Реализация.Ссылка КАК Документ,
| Реализация.СуммаДокумента КАК Сумма
|ИЗ
| Документ.РеализацияТоваровУслуг КАК Реализация
|ГДЕ
| Реализация.Дата МЕЖДУ &Начало И &Конец
| И Реализация.Проведен";
Запрос.УстановитьПараметр("Начало", НачалоДня(Объект.НачалоПериода));
Запрос.УстановитьПараметр("Конец", КонецДня(Объект.КонецПериода));
Объект.Документы.Загрузить(Запрос.Выполнить().Выгрузить());
КонецПроцедуры
Метод Загрузить сопоставляет колонки по именам. Поэтому псевдонимы в запросе совпадают с именами колонок табличной части.
Кнопка в форме типового документа через «Дополнительные обработки»
Это главный приём для задачи «кнопка в документе без доработки конфигурации». Обработка сообщает программе о себе через экспортную функцию СведенияОВнешнейОбработке в модуле объекта (не формы). Программа читает её при регистрации и добавляет команду в формы указанных объектов.
Модуль объекта: регистрационные сведения
Функция СведенияОВнешнейОбработке() Экспорт
ПараметрыРегистрации = ДополнительныеОтчетыИОбработки.СведенияОВнешнейОбработке();
ПараметрыРегистрации.Вид = ДополнительныеОтчетыИОбработкиКлиентСервер.ВидОбработкиЗаполнениеОбъекта();
ПараметрыРегистрации.Версия = "1.0";
ПараметрыРегистрации.Наименование = "Проставить комментарий";
ПараметрыРегистрации.БезопасныйРежим = Истина;
ПараметрыРегистрации.Назначение.Добавить("Документ.РеализацияТоваровУслуг");
Команда = ПараметрыРегистрации.Команды.Добавить();
Команда.Представление = "Проставить комментарий";
Команда.Идентификатор = "ПроставитьКомментарий";
Команда.Использование = ДополнительныеОтчетыИОбработкиКлиентСервер.ТипКомандыВызовСерверногоМетода();
Команда.ПоказыватьОповещение = Истина;
Возврат ПараметрыРегистрации;
КонецФункции
Назначение задаётся полным именем объекта метаданных. Можно добавить несколько строк — тогда кнопка появится в формах всех перечисленных документов.
Модуль объекта: действие кнопки
Для типа «Вызов серверного метода» программа ищет в модуле объекта экспортную процедуру ВыполнитьКоманду. В параметр ОбъектыНазначения приходит массив ссылок на документы, из которых нажали кнопку.
Процедура ВыполнитьКоманду(ИдентификаторКоманды, ОбъектыНазначения, ПараметрыВыполненияКоманды) Экспорт
Если ИдентификаторКоманды <> "ПроставитьКомментарий" Тогда
Возврат;
КонецЕсли;
Для Каждого Ссылка Из ОбъектыНазначения Цикл
ДокументОбъект = Ссылка.ПолучитьОбъект();
ДокументОбъект.Комментарий = "Проверено " + Формат(ТекущаяДатаСеанса(), "ДФ=dd.MM.yyyy");
ДокументОбъект.Записать();
КонецЦикла;
КонецПроцедуры
Комментарий на движения не влияет, поэтому документ здесь просто записывается. Если обработка меняет суммы или товары проведённого документа, записывайте его в режиме РежимЗаписиДокумента.Проведение.
Команда работает с записанным документом. Новый, ещё не записанный документ программа предложит сначала записать.
Регистрация в базе
| Конфигурация | Где включить и открыть список |
|---|---|
| Бухгалтерия 3.0 | Администрирование → Печатные формы, отчеты и обработки |
| ЗУП 3.1 | Администрирование → Печатные формы, отчеты и обработки |
| УТ 11 | НСИ и администрирование → Печатные формы, отчеты и обработки |
- Отметьте флажок «Дополнительные отчеты и обработки» и перейдите по ссылке.
- Нажмите «Добавить из файла» и выберите
.epf. - Программа прочитает сведения: вид, назначение, команды. Проверьте, что в назначении стоит нужный документ.
- Сохраните карточку и откройте любой документ из назначения. Команда появится в командной панели формы.
Регистрировать обработку от чужого автора без проверки кода нельзя: с флагом «небезопасного режима» она получает доступ к файлам и сети сервера.
Реквизиты и данные формы в обработчике
Чтобы кнопка что-то делала, ей нужны данные. В форме обработки они живут в двух местах.
- 📦
Объект— основной реквизит: реквизиты и табличные части самой обработки. - 📝 Реквизиты формы — добавляются на вкладке «Реквизиты» редактора формы. Подходят для полей, которые не нужно хранить в объекте.
Как вызвать метод модуля объекта из формы
Экспортные процедуры модуля объекта доступны только у настоящего объекта, а в форме лежит его копия — данные формы. Преобразуйте их на сервере:
&НаСервере
Процедура ВыполнитьРасчетНаСервере()
ОбработкаОбъект = РеквизитФормыВЗначение("Объект");
ОбработкаОбъект.Рассчитать();
ЗначениеВРеквизитФормы(ОбработкаОбъект, "Объект");
КонецПроцедуры
После ЗначениеВРеквизитФормы изменения, сделанные методом Рассчитать, видны на форме.
Передача данных в серверную процедуру без контекста
Если не нужен весь объект, передайте параметры явно. Это быстрее при большой форме:
&НаКлиенте
Процедура ПроверитьКонтрагента(Команда)
Сообщение = Новый СообщениеПользователю;
Сообщение.Текст = ОписаниеКонтрагента(Объект.Контрагент);
Сообщение.Сообщить();
КонецПроцедуры
&НаСервереБезКонтекста
Функция ОписаниеКонтрагента(Контрагент)
Возврат "ИНН: " + Контрагент.ИНН;
КонецФункции
Обращение к реквизиту через точку (Контрагент.ИНН) на сервере допустимо, но в цикле по сотням ссылок медленно. Для массовой обработки берите данные одним запросом.
Отладка и проверка кнопки
Проверяйте кнопку на копии базы. Обработка, которая пишет документы, при ошибке в цикле испортит сотни записей.
Отладка файла, открытого напрямую
- В Конфигураторе откройте тот же файл
.epfи поставьте точку останова (F9) в обработчике. - Запустите отладку клавишей F5 — откроется 1С:Предприятие.
- В пользовательском режиме выберите
Файл → Открытьи укажите этот файл. - Нажмите кнопку — выполнение остановится на точке останова.
В файловой базе серверный код выполняется в процессе клиента, поэтому останавливаются и клиентские, и серверные процедуры. В клиент-серверном варианте для серверных точек останова на сервере 1С должна быть включена отладка. Её включают параметром запуска службы агента, а перезапуск службы обрывает сеансы всех пользователей — делайте это вне рабочего времени.
Проверка зарегистрированной обработки
В карточке дополнительной обработки есть поле «Публикация». Значение «Режим отладки» показывает команду только администратору: можно проверить кнопку в рабочей базе, не показывая её бухгалтерам. После проверки переключите на «Используется».
Если обработку правили, файл нужно загрузить в карточку заново. Программа хранит в базе копию, и правки в .epf на диске сами не подхватываются.
Ошибки при добавлении кнопки и как их исправить
Ещё одна частая ловушка — безопасный режим. При БезопасныйРежим = Истина обработка не может работать с файлами, COM-объектами и внешними компонентами. Если кнопка должна, например, сохранять файл на диск, это ограничение снимают в регистрационных сведениях, а программа при регистрации запросит разрешения у администратора.