Как получить объект документа в 1С

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

Чтобы получить объект документа, чаще всего используют метод ПолучитьОбъект(), вызванный у ссылки. Альтернативные пути — создание нового объекта через менеджер документа (Документы.РеализацияТоваровУслуг.СоздатьДокумент()) или получение объекта из данных формы. Выбор способа зависит от задачи: изменить существующий документ, создать новый или просто прочитать данные.

Неправильное понимание различий между ссылкой и объектом — одна из самых частых причин ошибок «Поле объекта не обнаружено» и проблем с производительностью. Универсальные механизмы вроде обмена данными или печатных форм работают именно через объект, поэтому умение корректно его получать — базовый навык разработчика 1С.

Чем ссылка отличается от объекта документа

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

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

Практическое правило: если нужно только прочитать номер, дату или пару реквизитов — работайте через ссылку или запрос. Если нужно изменить документ, заполнить табличную часть или перепровести — получайте объект.

Как получить объект документа по ссылке

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

ДокОбъект = ДокументСсылка.ПолучитьОбъект();
ДокОбъект.Комментарий = "Изменено программно";
ДокОбъект.Записать(РежимЗаписиДокумента.Проведение);

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

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

Как создать объект нового документа

Если документа ещё нет в базе, объект создаётся через менеджер документа: Документы.ИмяДокумента.СоздатьДокумент(). Возвращается новый объект с незаполненными реквизитами, датой по умолчанию и без номера — номер будет присвоен при записи.

НовыйДок = Документы.ПриходныйОрдерНаТовары.СоздатьДокумент();
НовыйДок.Дата = ТекущаяДатаСеанса();
НовыйДок.Склад = СкладПоУмолчанию;
НовыйДок.Записать(РежимЗаписиДокумента.Запись);

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

Как получить объект из формы документа

В модуле формы документа данные хранятся в реквизите формы (обычно Объект типа ДанныеФормыСтруктура), а не как настоящий ДокументОбъект. Чтобы получить полноценный объект на сервере, используют метод РеквизитФормыВЗначение("Объект").

&НаСервере
Процедура ПересчитатьНаСервере()
    ДокОбъект = РеквизитФормыВЗначение("Объект");
    ДокОбъект.ДополнительныеСвойства.Вставить("РежимПересчёта", Истина);
    ЗначениеВРеквизитФормы(ДокОбъект, "Объект");
КонецПроцедуры

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

Получение объекта в запросах и обходе выборок

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

1. 1
   Составьте запрос, выбирающий ссылки документов по нужному условию
2. 2
   Выполните запрос и получите выборку
3. 3
   В цикле для каждой ссылки вызовите ПолучитьОбъект()
4. 4
   Проверьте, что объект не равен Неопределено
5. 5
   Измените реквизиты и вызовите Записать() с нужным режимом
6. 6
   По завершении убедитесь, что все документы записаны без исключений

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

Проверка результата и типичные ошибки

После получения объекта и записи стоит убедиться, что операция прошла корректно. Признаки успеха: объект не равен Неопределено, метод Записать() не вызвал исключения, у проведённого документа Проведен = Истина, а движения появились в регистрах.

Ограничения и безопасная работа

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

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

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