Разработка и Конфигурация · 13 мин
Как написать модуль 1С: практическое руководство
Как написать модуль в 1С: виды модулей, создание общего модуля, синтаксис процедур и функций, директивы компиляции, примеры кода и типичные ошибки новичков.
Модуль в 1С — это контейнер для программного кода на встроенном языке платформы. Практически вся бизнес-логика конфигурации хранится именно в модулях: расчёт цен, проведение документов, проверка прав, обмен данными. Умение грамотно создавать и организовывать модули — базовый навык разработчика 1С, без которого невозможно ни доработать типовую конфигурацию, ни написать собственное решение.
Начинающие разработчики часто путаются в видах модулей: код, написанный в модуле формы, недоступен из модуля объекта, а серверная процедура не может вызвать клиентскую функцию. Эти ограничения не случайны — они связаны с клиент-серверной архитектурой платформы. Понимание того, где исполняется каждый модуль, избавит от большинства ошибок ещё до запуска кода.
Ниже разобран практический путь: от выбора типа модуля до написания, отладки и проверки работающего кода. Примеры приведены на встроенном языке 1С и подходят для конфигураций на управляемых формах (режим «такси»), что актуально для большинства современных решений.
Виды модулей в 1С и где исполняется каждый из них
Платформа 1С:Предприятие содержит несколько типов модулей, и выбор правильного — первое решение при написании кода. Модуль приложения и модуль сеанса выполняются при запуске системы и установке сеанса. Общие модули хранят переиспользуемые процедуры и функции, доступные из любой точки конфигурации. Модуль объекта (справочника, документа, отчёта) содержит логику самого объекта — например, обработку проведения. Модуль формы отвечает за поведение пользовательского интерфейса.
Ключевое различие — место исполнения. В клиент-серверном режиме код может выполняться на клиенте (тонкий, толстый клиент, веб-клиент) или на сервере. Модуль формы разделён директивами: процедуры с &НаКлиенте работают в браузере или клиентском приложении, с &НаСервере — на сервере. Модуль объекта всегда исполняется на сервере, поэтому из него нельзя вызвать диалоговое окно или обратиться к элементам формы.
Отдельно стоит упомянуть модули менеджера и модули команды: они нужны для расширения стандартного поведения объектов и команд интерфейса. Начинающему разработчику достаточно освоить три типа: общий модуль, модуль объекта и модуль формы — они покрывают подавляющее большинство задач.
Подготовка: конфигуратор и настройка окружения
Работа с модулями ведётся в конфигураторе 1С:Предприятия. Откройте его через ярлык с параметром «Конфигуратор» или из командной строки с ключом DESIGNER. Убедитесь, что конфигурация не заблокирована другими пользователями и у вас есть права на изменение — для типовой конфигурации потребуется включить возможность изменений (меню «Конфигурация → Поддержка → Настройка поддержки»).
Перед любыми доработками сделайте резервную копию информационной базы через «Администрирование → Выгрузить информационную базу» или средствами СУБД, если база клиент-серверная. Ошибка в модуле проведения документа может повредить учётные данные, и откат без копии будет невозможен.
Полезно сразу настроить редактор модуля: включите автоматическую подсветку синтаксиса, контекстную подсказку (Ctrl+Пробел) и шаблоны кода. Эти инструменты встроены в конфигуратор и заметно ускоряют написание кода, снижая количество синтаксических ошибок.
Создание общего модуля шаг за шагом
Общий модуль — оптимальное место для функций, которые используются в нескольких объектах. Например, расчёт скидки, форматирование строки или проверка заполнения реквизита. Создаётся он в дереве конфигурации: ветка «Общие → Общие модули», команда «Добавить».
- 1Откройте конфигуратор и дерево конфигурации (Ctrl+Shift+1 или меню Конфигурация → Открыть конфигурацию)
- 2В ветке «Общие → Общие модули» нажмите «Добавить» и задайте имя, например РаботаСоСтроками
- 3В свойствах модуля установите флаги: «Сервер» — для серверной логики, «Вызов сервера» — если модуль нужно вызывать с клиента
- 4Напишите процедуры и функции, экспортируемые — с ключевым словом Экспорт
- 5Выполните синтакс-контроль модуля (Ctrl+F7) и обновите конфигурацию базы данных (F7)
- 6Проверьте вызов функции из другого модуля в режиме отладки (F5)
Флаги в свойствах модуля определяют контекст исполнения. «Сервер» — код выполняется только на сервере. «Клиент (управляемое приложение)» — на клиенте. «Вызов сервера» разрешает обращаться к серверному модулю из клиентского кода. «Привилегированный режим» отключает проверку прав доступа — используйте его осознанно, только для операций, которые должны выполняться независимо от прав пользователя, например запись служебных данных.
Имя модуля становится пространством имён: функция СформироватьПредставление из модуля РаботаСоСтроками вызывается как РаботаСоСтроками.СформироватьПредставление(..). Выбирайте осмысленные имена — по ним коллеги будут искать нужную логику.
Синтаксис: процедуры, функции и директивы компиляции
Встроенный язык 1С поддерживает русский и английский синтаксис, чаще используется русский. Процедура не возвращает значение, функция возвращает через оператор Возврат. Ключевое слово Экспорт делает метод доступным извне модуля — без него процедура остаётся внутренней.
// Общий модуль РаботаСоСтроками (Сервер)
Функция СократитьСтроку(ИсходнаяСтрока, МаксДлина) Экспорт
Если СтрДлина(ИсходнаяСтрока) <= МаксДлина Тогда
Возврат ИсходнаяСтрока;
КонецЕсли;
Возврат Лев(ИсходнаяСтрока, МаксДлина - 3) + "..";
КонецФункции
Процедура ЗаписатьВЖурнал(ТекстСобытия) Экспорт
ЗаписьЖурналаРегистрации("РаботаСоСтроками",
УровеньЖурналаРегистрации.Информация, , , ТекстСобытия);
КонецПроцедурыВ модуле формы каждая процедура обязана иметь директиву компиляции: &НаКлиенте, &НаСервере, &НаСервереБезКонтекста или &НаКлиентеНаСервереБезКонтекста. Директива ставится перед объявлением. Вариант «БезКонтекста» работает быстрее, потому что не передаёт на сервер данные всей формы, но в такой процедуре недоступны реквизиты формы напрямую — их нужно передавать параметрами.
// Модуль формы документа
&НаКлиенте
Процедура РассчитатьИтог(Команда)
Итог = ПолучитьИтогНаСервере(Объект.Ссылка);
ПоказатьОповещениеПользователя("Итог: " + Итог);
КонецПроцедуры
&НаСервереБезКонтекста
Функция ПолучитьИтогНаСервере(ДокументСсылка)
Возврат ДокументСсылка.Товары.Итог("Сумма");
КонецФункцииОбратите внимание на типичный приём: клиентская процедура не выполняет запросы к базе сама, а вызывает серверную функцию. Прямое обращение к данным с клиента невозможно — платформа выдаст ошибку компиляции или выполнения.
Модуль объекта и обработчики событий
Модуль объекта документа или справочника содержит предопределённые обработчики событий: ОбработкаПроведения, ОбработкаЗаполнения, ПередЗаписью, ПриЗаписи. Платформа вызывает их автоматически в нужные моменты жизненного цикла объекта. Чтобы добавить обработчик, откройте модуль объекта и выберите событие из выпадающего списка в редакторе — конфигуратор сам создаст заготовку с правильной сигнатурой.
Пример минимальной обработки проведения: очистить движения, сформировать записи в регистр накопления на основании табличной части, записать.
Если логика проведения объёмная, вынесите её в общий модуль, а в обработчике оставьте только вызов: ПроведениеДокументов.ОтразитьДвижения(ЭтотОбъект). Так код легче тестировать и переиспользовать.
Отладка и проверка результата
После написания кода выполните синтакс-контроль модуля (Ctrl+F7) — он выявит ошибки компиляции: незакрытые конструкции, несуществующие методы, неверные директивы. Затем обновите конфигурацию базы данных (F7) и запустите отладку (F5). Поставьте точку останова (F9) в нужной строке и выполните действие в пользовательском режиме — выполнение остановится, и вы сможете посмотреть значения переменных через табло (Shift+F9).
Как проверить результат
Нет сообщений об ошибках в окне служебных сообщений
Ошибки компиляции, ссылки на несуществующие процедуры
Функция доступна в контекстной подсказке после имени модуля и точки
Процедура не видна — забыто ключевое слово Экспорт или не включён нужный флаг контекста
Код проходит по ожидаемым веткам, переменные содержат ожидаемые значения
Исключение времени выполнения, обращение к неопределённой переменной
Серверные вызовы выполняются, данные возвращаются на клиент
Ошибка «вызов сервера запрещён» или недоступность контекста
Отдельно проверьте работу в том режиме, в котором будет работать пользователь: тонкий клиент и веб-клиент накладывают больше ограничений, чем толстый. Код, успешно работающий в файловой базе на толстом клиенте, может упасть в клиент-серверном варианте из-за попытки выполнить серверную операцию на клиенте.
Типичные ошибки и ограничения
Особого внимания заслуживают расширения конфигурации. Если задача — доработать типовое решение, предпочтительный путь сегодня — не править модули поставщика, а создать расширение (меню «Конфигурация → Расширения конфигурации») и добавить в него аннотации &ИзменениеИКонтроль, &Вместо, &После. Это сохранит конфигурацию на поддержке и упростит обновления.
Как выбрать место для кода
И помните про ограничения производительности: не размещайте в общих модулях с флагом «Вызов сервера» громоздкие процедуры, которые будут дергаться при каждом клике. Каждый серверный вызов — это сетевой обмен, и частые вызовы заметно замедляют работу пользователей на веб-клиенте.
Что важно запомнить
Модуль 1С создаётся в конфигураторе, а место размещения кода определяется тем, где он исполняется: клиент, сервер или объект. Пишите переиспользуемую логику в общих модулях, используйте правильные директивы компиляции, не забывайте Экспорт, проверяйте код синтакс-контролем и отладкой, а типовые конфигурации дорабатывайте через расширения. Всегда работайте на копии базы.
Частые вопросы о написании модулей 1С
Чем процедура отличается от функции в 1С?
Функция обязана возвращать значение через оператор Возврат и может использоваться в выражениях, например в правой части присваивания. Процедура ничего не возвращает и вызывается как отдельный оператор. Если результат работы кода нужен вызывающей стороне — пишите функцию, если выполняется действие без результата (запись в журнал, изменение данных) — процедуру.
Почему моя функция не видна из другого модуля?
Чаще всего причина в отсутствии ключевого слова Экспорт после объявления функции. Вторая типичная причина — не включён нужный флаг контекста в свойствах общего модуля: например, клиентский код не видит серверный модуль без флага «Вызов сервера». Проверьте также, что имя модуля написано без опечаток.
Можно ли вызвать серверную процедуру из клиентского кода?
Да, но только косвенно: клиентская процедура вызывает серверную процедуру модуля формы с директивой &НаСервере или функцию общего модуля с флагом «Вызов сервера». Прямого доступа клиента к базе данных нет — это архитектурное ограничение платформы, обойти его нельзя.
Что такое привилегированный режим и когда он нужен?
Привилегированный режим отключает проверку прав доступа к объектам базы данных. Он нужен, когда операция должна выполниться независимо от прав пользователя — например, запись служебного лога или обновление системных настроек. Включать его для обычной бизнес-логики опасно: пользователь сможет косвенно изменить данные, к которым у него нет доступа.
Как доработать модуль типовой конфигурации, не снимая её с поддержки?
Используйте расширение конфигурации: создайте расширение, заимствуйте нужный модуль или процедуру и измените код с помощью аннотаций &ИзменениеИКонтроль, &Вместо, &Перед или &После. Расширение подключается поверх типовой конфигурации и не мешает штатному обновлению, хотя после обновления расширение стоит проверить на совместимость.
Где смотреть ошибки, если код «молча» не работает?
Сначала проверьте, что обработчик события создан через выпадающий список редактора модулей — вручную написанная процедура с ошибкой в имени просто не вызывается. Затем используйте отладку с точками останова и смотрите журнал регистрации (в пользовательском режиме: Администрирование → Журнал регистрации) — туда попадают исключения и сообщения об ошибках выполнения.