Как создать процедуру в 1С на клиенте

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

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

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

Где размещают клиентские процедуры

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

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

Отдельный случай — модуль команды. Если создаётся собственная команда интерфейса, её обработчик также выполняется на клиенте и оформляется с директивой &НаКлиенте.

Создание процедуры в модуле формы

Откройте конфигуратор, найдите нужный объект (например, документ или справочник), перейдите на вкладку «Формы» и откройте форму. Затем перейдите на вкладку «Модуль» внизу окна редактора формы — откроется модуль формы, где и размещается код.

Объявление клиентской процедуры выглядит так:

&НаКлиенте
Процедура ПоказатьСообщениеПользователю(ТекстСообщения)

ПоказатьПредупреждение(, ТекстСообщения, , "Внимание");

КонецПроцедуры

Директива &НаКлиенте обязательна и пишется без отступа в отдельной строке. После неё идёт стандартное объявление: ключевое слово Процедура, имя, список параметров в скобках, тело и КонецПроцедуры. Имя давайте осмысленным, начинающимся с глагола: РассчитатьСумму, ОткрытьФайлДоговора.

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

1. 1
   Откройте форму объекта в конфигураторе и перейдите на вкладку «Модуль»
2. 2
   Напишите директиву &НаКлиенте в отдельной строке
3. 3
   Объявите процедуру с параметрами и телом, завершите словом КонецПроцедуры
4. 4
   Вызовите процедуру из обработчика события или другой клиентской процедуры
5. 5
   Нажмите F7 (проверка модуля) и устраните синтаксические ошибки
6. 6
   Запустите режим предприятия и проверьте поведение в интерфейсе

Обработчики событий — частный случай клиентских процедур

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

&НаКлиенте
Процедура РассчитатьИтог(Команда)

РассчитатьИтогНаКлиенте();

КонецПроцедуры

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

Для событий самой формы («ПриОткрытии», «ПередЗаписью») ситуация иная: у них есть и клиентские, и серверные варианты. Например, «ПриСозданииНаСервере» выполняется на сервере, а «ПриОткрытии» — на клиенте. Выбирайте событие в зависимости от того, какие данные и операции нужны.

Ограничения клиентского контекста

Клиентский код не имеет прямого доступа к базе данных. Внутри процедуры с директивой &НаКлиенте нельзя использовать запросы (Запрос), менеджеры объектов для записи (Документы.Реализация.СоздатьДокумент()), прямые обращения к данным справочников по ссылке через точку. Попытка написать такой код приведёт к ошибке компиляции или выполнения.

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

Если внутри клиентской логики понадобились данные из базы — получите их через вызов серверной процедуры. Типовой приём: клиентская процедура собирает параметры, вызывает серверную функцию, та возвращает результат, клиент показывает его пользователю.

Вызов клиентской процедуры и обмен с сервером

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

Для обращения к серверу создайте в модуле формы процедуру с директивой &НаСервере или &НаСервереБезКонтекста и вызовите её из клиентской:

&НаКлиенте
Процедура ЗагрузитьОстаток(Команда)

Остаток = ПолучитьОстатокНаСервере(ТекущаяНоменклатура);
ПоказатьПредупреждение(, "Остаток: " + Остаток);

КонецПроцедуры

&НаСервереБезКонтекста
Функция ПолучитьОстатокНаСервере(Номенклатура)

// запрос к регистру остатков
Возврат Остаток;

КонецФункции

Каждый вызов сервера — это сетевое обращение, которое занимает время. Не вызывайте серверные процедуры в цикле: соберите данные в массив или структуру и передайте одним вызовом. Это особенно критично при работе через веб-клиент или медленное соединение.

Проверка и отладка клиентского кода

Первый уровень проверки — синтаксический контроль модуля: в конфигураторе нажмите F7 или выберите «Конфигурация → Проверка конфигурации». Проверяйте с включёнными режимами «Тонкий клиент» и «Веб-клиент», чтобы поймать ошибки недоступности методов именно в клиентском контексте.

Для пошаговой отладки включите в конфигураторе «Отладка → Подключение» и убедитесь, что отладка разрешена (в файловой базе — автоматически, в клиент-серверной — сервер запускается с ключом отладки). Поставьте точку останова в клиентской процедуре, запустите предприятие в режиме отладки и выполните действие в интерфейсе — выполнение остановится на нужной строке.

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

Контрольные точки

Как проверить результат

Синтаксический контроль модуля (F7)

Норма

Ошибок нет при проверке для тонкого и веб-клиента

Тревожный признак

Сообщения о недоступности метода в данном контексте

Запуск процедуры в режиме предприятия

Норма

Код выполняется, пользователь видит ожидаемый результат

Тревожный признак

Ошибка времени выполнения или отсутствие реакции

Точка останова в отладчике

Норма

Выполнение останавливается в клиентской процедуре

Тревожный признак

Точка не срабатывает — проверьте директиву и подключение сеанса

Клиентский или серверный: как выбрать контекст

Простое правило: всё, что связано с интерфейсом и компьютером пользователя, — на клиент; всё, что связано с базой данных и бизнес-логикой, — на сервер. Показ диалога, открытие формы, выбор файла — клиент. Запрос данных, запись объектов, проверка прав, сложные расчёты по большим данным — сервер.

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

Маршрут решения

Как выбрать контекст процедуры

Нужно показать диалог, открыть форму или выбрать файлСоздавайте процедуру с директивой &НаКлиенте

Нужен запрос к базе или запись объектаСоздавайте серверную процедуру, вызывайте её из клиентской

Логика используется в нескольких формахВыносите в общий модуль с флагом «Клиент» или «Сервер»

Процедуре нужны данные текущей формы на сервереИспользуйте &НаСервере (с контекстом), а не БезКонтекста

Частые вопросы

Чем процедура отличается от функции в 1С?

Функция возвращает значение через оператор «Возврат» и может использоваться в выражениях, процедура — нет. Если результат работы нужен вызывающему коду (например, рассчитанная сумма), используйте функцию; если выполняется действие без результата (показ сообщения, открытие формы) — процедуру.

Можно ли вызвать клиентскую процедуру с сервера?

Напрямую — нет: сервер не имеет доступа к клиентскому контексту. Серверная процедура может только вернуть данные, а клиентская, получив их, продолжит работу. Для инициирования действий на клиенте используются оповещения (Оповестить) или механизмы взаимодействия вроде системы взаимодействия.

Почему в веб-клиенте не работает выбор файла?

Работа с файловой системой в тонком и веб-клиенте требует подключения расширения работы с файлами. Используйте асинхронные методы НачатьПодключениеРасширенияРаботыСФайлами и НачатьПомещениеФайла — они корректно работают во всех видах клиентов.

Что такое &НаКлиентеНаСервереБезКонтекста и когда она нужна?

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

Как передать данные формы в серверную процедуру без контекста?

Напрямую — никак: процедура &НаСервереБезКонтекста не видит реквизиты формы. Передайте нужные значения параметрами (ссылки, структуры, массивы) или используйте процедуру &НаСервере, которая имеет доступ к данным формы. Для передачи всего объекта формы применяется преобразование в значение через РеквизитФормыВЗначение.

Нужно ли писать Экспорт для обработчиков событий?

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