Модули в 1С 8.3: как использовать в разработке

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

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

Ниже разобраны все основные виды модулей платформы 1С 8.3, правила выбора модуля под конкретную задачу, директивы компиляции, экспортные процедуры и типичные ошибки с способами их проверки.

Какие виды модулей существуют в 1С 8.3

Платформа предоставляет несколько типов модулей, каждый со своей областью видимости и контекстом исполнения. Понимание этой карты — первый шаг к грамотному размещению кода.

• Модуль управляемого приложения — исполняется при старте и завершении системы, содержит обработчики событий приложения (ПередНачаломРаботыСистемы, ПриНачалеРаботыСистемы).
• Модуль сеанса — выполняется на сервере при инициализации сеанса, обычно используется для установки параметров сеанса.
• Общие модули — библиотеки процедур и функций, доступные из любого места конфигурации.
• Модуль объекта — описывает поведение конкретного объекта: документа, справочника, регистра (проведение, заполнение, проверка).
• Модуль менеджера — содержит логику, относящуюся ко всему типу объектов, а не к одному экземпляру (например, формирование представления).
• Модуль формы — обработчики событий формы и команд интерфейса.
• Модуль команды — код, выполняемый при вызове команды объекта или общей команды.
• Модуль внешнего соединения и модуль обычного приложения — специализированные модули для com-соединений и обычного режима.

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

Общие модули создаются в ветке «Общие → Общие модули» дерева конфигурации. Это основное место для функций, которые нужны в нескольких объектах: расчёт сумм, работа со строками, обращения к данным, интеграционные процедуры. Вызов выглядит просто: ИмяМодуля.ИмяПроцедуры(Параметры).

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

• Сервер — модуль доступен только на сервере; сюда помещают запросы и работу с данными.
• Клиент (управляемое приложение) — код для клиентской логики без обращения к базе.
• Вызов сервера — разрешает обращаться к серверному модулю с клиента; без этого флага серверный модуль из формы недоступен.
• Привилегированный режим — код выполняется без проверки прав; используйте осознанно, только где это необходимо.
• Глобальный — процедуры модуля доступны без указания имени модуля; применять не рекомендуется из-за конфликтов имён.

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

Модуль объекта и модуль менеджера: где описывать поведение данных

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

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

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

Частая ошибка — размещать массовые операции (запросы по всем документам вида) в модуле объекта. Такой код будет работать, но логически ему место в общем модуле или модуле менеджера: модуль объекта должен отвечать только за поведение одного экземпляра.

Модуль формы и директивы компиляции

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

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

Правильный паттерн клиент-серверного взаимодействия: клиентская процедура собирает параметры и вызывает серверную, серверная выполняет работу с данными и возвращает результат, клиентская отображает его пользователю. Вызов сервера с клиента — дорогая операция, поэтому несколько мелких вызовов стоит объединять в один.

1. 1
   Создайте команду формы и перетащите её на форму как кнопку
2. 2
   В обработчике команды с директивой &НаКлиенте соберите входные параметры
3. 3
   Создайте процедуру &НаСервереБезКонтекста, выполняющую запрос и возвращающую результат
4. 4
   Вызовите серверную процедуру из клиентской и обработайте возвращённое значение
5. 5
   Проверьте работу в тонком клиенте — именно там всплывают ошибки контекста

Модуль приложения и модуль сеанса

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

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

Типичные ошибки при работе с модулями

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

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

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

Компиляция конфигурации (Конфигурация → Проверка конфигурации)

Норма

Ошибок нет во всех режимах проверки: тонкий, веб-клиент, сервер

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

Ошибки «переменная не определена» или «метод недоступен» в отдельных режимах

Запуск в тонком клиенте

Норма

Функциональность работает так же, как в толстом клиенте

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

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

Права пользователя

Норма

Код доступен под пользователем с ограниченными правами

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

Нарушение прав доступа там, где ожидался привилегированный режим

Как выбрать модуль под задачу

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

Как выбрать действие

Код нужен нескольким объектам конфигурацииСоздайте общий модуль; серверный — для работы с данными, клиентский — для интерфейсных функций

Логика относится к одному экземпляру документа или справочникаИспользуйте модуль объекта и его обработчики событий

Нужно действие по нажатию кнопки на формеОбработчик команды в модуле формы: &НаКлиенте для интерфейса, &НаСервереБезКонтекста для данных

Требуется инициализация при входе пользователяМодуль сеанса для параметров сеанса, модуль приложения для клиентских действий

Нужны печатные формы или представление объектаМодуль менеджера объекта

При сомнениях полезно задать себе два вопроса: «Нужен ли этому коду доступ к данным?» и «Нужен ли он больше чем одному объекту?». Ответ «да, данные» — серверный контекст; ответ «да, несколько объектов» — общий модуль. Комбинация ответов однозначно приводит к правильному месту размещения.

Частые вопросы о модулях 1С 8.3

Чем отличается модуль объекта от модуля формы?

Модуль объекта описывает поведение данных (запись, проведение, проверка) и работает независимо от того, открыта форма или нет. Модуль формы описывает поведение интерфейса и существует только пока форма открыта. Бизнес-логику следует держать в модуле объекта, чтобы она срабатывала при любом способе изменения данных, включая обмены и фоновые задания.

Что делает ключевое слово Экспорт?

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

Почему серверный общий модуль не виден из формы?

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

Когда использовать &НаСервереБезКонтекста вместо &НаСервере?

Всегда, когда процедуре не нужны реквизиты и данные самой формы. Вызов без контекста не сериализует данные формы на сервер и обратно, поэтому работает заметно быстрее и меньше нагружает сервер.

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

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

Где хранить код, используемый и на клиенте, и на сервере?

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