Ввод на основании в расширении 1С: как реализовать правильно

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

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

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

Что такое ввод на основании и как он работает в 1С

Механизм ввода на основании связывает два объекта метаданных: документ-основание и документ, который на его основе создаётся. Связь задаётся в свойствах объекта: у документа есть поля «Вводится на основании» (перечень документов-источников) и «Является основанием для» (перечень целевых документов). Эти свойства взаимосвязаны — заполнение одного автоматически отражается в другом.

Когда связь настроена, платформа автоматически добавляет в форму документа кнопку «Создать на основании» и строит цепочку связанных документов в панели навигации. При создании нового объекта платформа вызывает обработчик события ОбработкаЗаполнения модуля объекта, передавая туда параметр ДанныеЗаполнения — ссылку на документ-основание. Именно в этом обработчике программист описывает, какие реквизиты и табличные части копируются.

В типовых конфигурациях на базе БСП (Библиотека стандартных подсистем) дополнительно работает подсистема «Создание на основании» с командами ввода, которые выводятся в формы списков и документов. При доработке через расширение чаще всего достаточно базового механизма платформы, но иногда требуется интеграция именно с командами БСП.

Подготовка расширения и заимствование объектов

Создайте новое расширение: в конфигураторе откройте «Конфигурация → Расширения конфигурации», добавьте расширение, задайте имя и префикс (например, Расш1_). Префикс важен: все добавляемые расширением объекты должны иметь уникальные имена, чтобы не конфликтовать с типовыми при обновлении.

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

Откройте свойства заимствованного документа-основания, найдите раздел «Ввод на основании» и добавьте целевой документ в список «Является основанием для». Альтернатива — открыть свойства целевого документа и указать источник в списке «Вводится на основании». Результат одинаковый, выбирайте тот объект, который удобнее редактировать.

1. 1
   Создайте расширение и задайте префикс объектов
2. 2
   Заимствуйте документ-основание и целевой документ (или добавьте новый)
3. 3
   В свойствах укажите связь «Вводится на основании» / «Является основанием для»
4. 4
   Добавьте или переопределите обработчик ОбработкаЗаполнения целевого документа
5. 5
   Обновите конфигурацию базы данных и проверьте кнопку в пользовательском режиме

Сценарий 1: целевой документ добавляется расширением

Это самый чистый сценарий: вы создаёте в расширении новый документ, например Расш1_ЗаявкаНаКомандировку, который должен создаваться на основании типового документа «Счет на оплату покупателю». Поскольку модуль объекта нового документа полностью ваш, никаких ограничений на код нет.

В модуле объекта нового документа напишите обработчик заполнения. Платформа передаёт в ДанныеЗаполнения ссылку на основание, поэтому тип проверяют через ТипЗнч:

Процедура ОбработкаЗаполнения(ДанныеЗаполнения, ТекстЗаполнения, СтандартнаяОбработка)

Если ТипЗнч(ДанныеЗаполнения) = Тип("ДокументСсылка.СчетНаОплатуПокупателю") Тогда
Организация = ДанныеЗаполнения.Организация;
Контрагент = ДанныеЗаполнения.Контрагент;
ДокументОснование = ДанныеЗаполнения;
Для Каждого СтрокаТовары Из ДанныеЗаполнения.Товары Цикл
НоваяСтрока = Товары.Добавить();
НоваяСтрока.Номенклатура = СтрокаТовары.Номенклатура;
НоваяСтрока.Количество = СтрокаТовары.Количество;
КонецЦикла;
КонецЕсли;

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

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

Сценарий 2: оба документа типовые, логику заполнения нужно переопределить

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

Платформа создаст в расширении обёртку с вызовом типового обработчика. Ваша задача — вставить свою логику до или после вызова Расш1_ОбработкаЗаполнения() (имя генерируется с префиксом расширения). Типичный приём: сначала вызвать типовое заполнение, затем скорректировать отдельные реквизиты под свои требования.

&Вместо("ОбработкаЗаполнения")
Процедура Расш1_ОбработкаЗаполнения(ДанныеЗаполнения, ТекстЗаполнения, СтандартнаяОбработка)
	Если ТипЗнч(ДанныеЗаполнения) = Тип("ДокументСсылка.ЗаказКлиента") Тогда
		СтандартнаяОбработка = Ложь;
		Организация = ДанныеЗаполнения.Организация;
		Контрагент = ДанныеЗаполнения.Контрагент;
	Иначе
		ПродолжитьВызов(ДанныеЗаполнения, ТекстЗаполнения, СтандартнаяОбработка);
	КонецЕсли;
КонецПроцедуры

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

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

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

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

Вывод команды в форму и проверка результата

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

Проверку выполняйте в пользовательском режиме на копии базы: откройте документ-основание, нажмите «Создать на основании», убедитесь, что создаётся нужный тип документа, реквизиты и табличные части переносятся корректно, а в форме нового документа отображается ссылка на основание. Проведите созданный документ и проверьте движения, если они зависят от заполненных реквизитов.

Типичные ошибки и ограничения расширений

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

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

FAQ