Как написать команду в 1С: инструкция для разработчика

Команда в 1С — это действие, которое пользователь запускает кнопкой, пунктом меню или ссылкой в интерфейсе. За командой всегда стоит обработчик — процедура на встроенном языке, которая выполняет нужную логику: открывает форму, проводит документ, формирует отчёт или вызывает произвольный алгоритм. Понимание того, где создаётся команда и как она связывается с кодом, — базовый навык разработчика конфигураций.

Команды в 1С бывают нескольких видов: стандартные (встроенные в платформу, например «Записать» или «Провести»), команды формы, глобальные команды интерфейса, команды объектов конфигурации и команды отчётов. Каждый вид создаётся в своём месте дерева конфигурации и имеет собственные правила размещения в панелях действий. Ошибка на этом этапе — самая частая причина, по которой кнопка «не появляется» у пользователя.

Ниже разобран практический порядок создания команды в конфигураторе: от добавления объекта до написания обработчиков на клиенте и сервере, проверки прав доступа и типичных ошибок. Примеры приведены для управляемых форм, которые используются в современных конфигурациях на платформе 8.3.

Какие виды команд существуют в 1С и где их создавать

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

• Команда формы — создаётся в редакторе конкретной формы и видна только в ней. Подходит для действий над текущим объектом: пересчитать итоги, заполнить табличную часть, вызвать печать.
• Команда объекта конфигурации — добавляется в свойствах справочника, документа, обработки. Может отображаться в списке, в форме объекта и в панели навигации. Типичный пример — команда «Заполнить» у документа.
• Глобальная команда — создаётся в общих командах конфигурации и доступна из панели функций разделов. Используется для открытия обработок, отчётов, служебных инструментов.
• Стандартная команда — предопределённая платформой (Записать, Провести, Пометить на удаление). Её нельзя создать, но можно переопределить поведение через обработчики формы.
• Команда отчёта — формируется автоматически на основе схемы компоновки данных или задаётся вручную для вариантов отчёта.

Выбор типа команды влияет и на контекст выполнения. Команда формы имеет доступ к данным формы напрямую, команда объекта получает ссылку на объект как параметр, а глобальная команда работает без привязки к данным и обычно просто открывает что-либо.

Как добавить команду в конфигураторе

Рассмотрим создание команды объекта на примере документа. Откройте конфигуратор, найдите нужный документ в дереве конфигурации, раскройте ветку и перейдите на вкладку «Команды». Нажмите «Добавить» и задайте свойства новой команды.

Ключевые свойства команды: Имя (идентификатор для обращения из кода, пишется латиницей или кириллицей без пробелов), Синоним (текст, который увидит пользователь на кнопке), Режим использования параметра (передаётся ли ссылка на объект: одиночный, множественный или без параметра) и Группа (в какую часть командной панели поместить кнопку). Также можно задать картинку, горячие клавиши и подсказку.

Для команды формы порядок иной: откройте форму объекта, перейдите на вкладку «Команды» в редакторе формы, добавьте команду, а затем перетащите её в дерево элементов формы — в командную панель или как кнопку в нужное место. Без перетаскивания в дерево элементов команда существует, но пользователь её не увидит.

1. 1
   Откройте объект конфигурации и перейдите на вкладку «Команды»
2. 2
   Добавьте команду, задайте имя, синоним и режим использования параметра
3. 3
   Нажмите кнопку с лупой у свойства «Действие» — конфигуратор создаст заготовку обработчика в модуле команды
4. 4
   Напишите код обработчика
5. 5
   Обновите конфигурацию базы данных и проверьте кнопку в режиме предприятия

Как написать обработчик команды

Обработчик — это процедура, которая выполняется при нажатии кнопки. Для команды объекта платформа создаёт её в модуле команды, для команды формы — в модуле формы. Заготовка появляется автоматически, если нажать кнопку открытия у свойства «Действие».

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

&НаКлиенте
Процедура ПроверитьЗаполнение(Команда)
Если НЕ ЗначениеЗаполнено(Объект.Контрагент) Тогда
Сообщить("Не заполнен контрагент");
Возврат;
КонецЕсли;
Сообщить("Проверка пройдена");
КонецПроцедуры

Обратите внимание на директиву компиляции. В управляемых формах код делится на клиентский и серверный: &НаКлиенте выполняется на компьютере пользователя и имеет доступ к интерфейсу, &НаСервере — к базе данных. Нельзя вызывать запросы или обращаться к менеджерам объектов из клиентской процедуры — это вызовет ошибку компиляции.

Типовой шаблон для «тяжёлой» логики: клиентская процедура принимает команду, собирает параметры и вызывает серверную процедуру, которая выполняет запросы и изменения данных, а затем возвращает результат на клиент для отображения.

&НаКлиенте
Процедура ЗаполнитьДанные(Команда)
	ЗаполнитьДанныеНаСервере();
КонецПроцедуры

&НаСервере
Процедура ЗаполнитьДанныеНаСервере()
	Запрос = Новый Запрос;
	Запрос.Текст = "ВЫБРАТЬ Первые 10 Ссылка ИЗ Справочник.Номенклатура";
	Выборка = Запрос.Выполнить().Выбрать();
	Пока Выборка.Следующий() Цикл
		Сообщить(Строка(Выборка.Ссылка));
	КонецЦикла;
КонецПроцедуры

Клиентский и серверный контекст: что где писать

Главная ошибка начинающих — попытка выполнить запрос к базе прямо в клиентском обработчике. В управляемом приложении клиент и сервер разделены, и платформа строго контролирует, какие операции где допустимы.

На клиенте допустимо: работа с элементами формы, диалоги с пользователем (вопросы, предупреждения, выбор файлов), открытие форм, вызов серверных процедур. На сервере: запросы, чтение и запись объектов, транзакции, обращения к регистрам и справочникам. Директива &НаСервереБезКонтекста используется, когда серверной процедуре не нужны данные формы — такой вызов быстрее, но объект придётся получать по ссылке заново.

Если команда изменяет данные, оборачивайте изменения в транзакцию через НачатьТранзакцию() и ЗафиксироватьТранзакцию() с обработкой исключений через Попытка...Исключение. Иначе при ошибке в середине алгоритма часть данных запишется, а часть — нет.

Параметры команды и работа со ссылками

Команда объекта может получать параметр — ссылку на объект, из которого она вызвана. Режим «Одиночный» передаёт одну ссылку, «Множественный» — массив выделенных в списке элементов, «Не использовать» — команда вызывается без контекста. Для массовой обработки документов выбирайте множественный режим и обрабатывайте массив в цикле.

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

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

Права, интерфейс и размещение кнопки

Команда написана и работает у разработчика, но пользователь её не видит — типичная ситуация с тремя возможными причинами. Первая: у роли пользователя нет права на саму команду. Откройте роль в конфигураторе и проверьте, что на команду установлено право (команды объектов и общие команды имеют собственный флажок в списке прав).

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

Дополнительно проверьте функциональные опции: если команда или её объект связаны с отключённой опцией, интерфейс скроет кнопку автоматически. Это удобно для отраслевых настроек, но часто сбивает при отладке.

Типичные ошибки при создании команд

Большинство проблем с командами укладывается в короткий список повторяющихся ошибок. Знание их экономит часы отладки.

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

Как проверить и отладить команду

Для отладки обработчика поставьте точку останова в процедуре и запустите конфигуратор в режиме отладки (F5). При нажатии кнопки выполнение остановится, и вы сможете просмотреть значения переменных, параметры команды и стек вызовов. Для серверных процедур убедитесь, что в настройках отладки включён серверный контекст.

Проверяйте команду в три этапа: сначала синтаксический контроль модуля (кнопка с галочкой в редакторе модуля), затем запуск под полными правами, затем под ролью реального пользователя. Только третий этап покажет проблемы с правами и командным интерфейсом.

Частые вопросы о командах в 1С