7.2. Программная работа с документами
С документами в пользовательском режиме можно работать не только интерактивно – так, как мы это делали до сих пор, но и программно. Рассмотрим объекты 1С:Предприятие, которые используются для программной работы с документами.
ДокументыМенеджер – этот объект доступен через свойство глобального контекста Документы. Он позволяет управлять документами, давая доступ к объекту ДокументМенеджер для конкретного документа
ДокументМенеджер – позволяет управлять документом, в частности, создавать новые документы, производить поиск документов, помечать документы на удаление, получать выборки.
ДокументСсылка – идентификатор документа. Используется обычно в реквизитах других объектов для указания ссылки на определенный документ.
ДокументОбъект – позволяет работать с отдельным документом – читать и редактировать его данные.
ДокументВыборка – предназначен для работы с выборкой документов, произведенной по определенным условиям.
ДокументСписок – позволяет управлять списком документов, расположенных в табличном поле.
Для доступа к метаданным документа можно воспользоваться свойством Документы свойства глобального контекста Метаданные.
Создадим новую обработку, назовем ее РаботаСДокументами. Включим в подсистему Администрирование.
Добавим в обработку команду с именем ВывестиСписокВидовДокументов, зададим обработчик для этой команды, выведем ее на форму обработки.
Воспользуемся свойством глобального контекста Метаданные для того, чтобы вывести пользователю список синонимов существующих в конфигурации документов. Для подобных действий нам понадобится серверная процедура, которую мы вызовем из клиентской процедуры обработчика ранее созданной команды. Выполнить запланированное можно с помощью следующего кода:
&НаКлиенте
Процедура ВывестиСписокВидовДокументов(Команда)
ВывестиСинонимыДокументов();
КонецПроцедуры
Процедура ВывестиСинонимыДокументов()
Для каждого Документ из Метаданные.Документы Цикл
Сообщить(Документ.Синоним);
КонецЦикла;
КонецПроцедуры
Результат выполнения показан на рис. 7.13.
Рис. 7.13. Вывод списка синонимов документов
С помощью коллекции Метаданные (тип ОбъектМетаданныхКонфигурация) мы можем получить доступ к структуре конфигурации, в частности, к коллекции Документы (тип КоллекцияОбъектовМетаданных), состоящей из объектов типа ОбъектМетаданных: Документ. Обратившись к документу, как к объекту метаданных, мы можем узнать имя, синоним и другие метаданные.
Теперь рассмотрим следующую задачу. Нужно программно создать новый документ заданного вида, заполнить его некоторыми данными, сохранить в базе данных, приняв решение о том, проводить его или не проводить на основе анализа флага ПроводитьДокумент, который имеется на форме обработки, после чего открыть его форму для проверки пользователем.
Здесь нам понадобится начинать "поиски" нужного объекта от объекта ДокументыМенеджер. С его помощью мы можем получить объект ДокументМенеджер для нужного вида документов, и уже с помощью этого объекта мы сможем создать новый документ.
Добавим в нашу обработку новую команду –
СоздатьДокументПоступлениеМатериалов. Так же добавим новый реквизит – ПроводитьДокумент, поместим его на форму, рис. 7.14.
Мы зададим все данные, в том числе – и тип документа для создания – в коде.
Рис. 7.14. Модификация формы обработки
Решить поставленную задачу можно с помощью следующего кода:
&НаКлиенте
Процедура СоздатьДокументПоступлениеМатериалов(Команда)
//Настраиваем режим записи нового документа
РежимЗаписи=РежимЗаписиДокумента.Запись;
Если ПроводитьДокумент Тогда
РежимЗаписи=РежимЗаписиДокумента.Проведение;
КонецЕсли;
//В функции будет создан новый документ
//Она возвратит ссылку на него
Документ=СоздатьДокумент(РежимЗаписи);
//Открываем форму документа
ОткрытьЗначение(Документ);
КонецПроцедуры
Функция СоздатьДокумент(РежимЗаписи)
//Создаем новый документ
Документ = Документы.ПоступлениеМатериалов.СоздатьДокумент();
//Заполняем его реквизиты
Документ.Дата=ТекущаяДата();
Документ.ОтветственныйСотрудник=Справочники.Сотрудники.НайтиПоКоду("000000003");
Документ.Контрагент=Справочники.Контрагенты.НайтиПоРеквизиту("КонтактныеСведения", "ул. Береговая, д. 2, телефон 3-34-34");
Документ.Комментарий="Документ создан автоматически";
//Заполняем строку табличной части
НоваяСтрокаТЧ=Документ.Материалы.Добавить();
НоваяСтрокаТЧ.Номенклатура=Справочники.Номенклатура.НайтиПоНаименованию("Духи");
НоваяСтрокаТЧ.Количество=10;
НоваяСтрокаТЧ.Цена=200;
НоваяСтрокаТЧ.Сумма=10*200;
//Записываем документ
Документ.Записать(РежимЗаписи);
//Возвращаем ссылку на документ
Возврат(Документ.Ссылка);
КонецФункции
Проведение документа, либо его запись, либо – отмена проведения – производятся с помощью метода документа Записать(). Этот метод принимает параметр, который и отвечает за то, что будет произведено при записи документа. В начале клиентской процедуры СоздатьДокументПоступлениеМатериалов мы анализируем флаг ПроводитьДокумент, предварительно установив переменную РежимЗаписи в значение РежимЗаписиДокумента.Запись. Если флаг установлен – то есть мы хотим не только записать, но и провести документ, значение переменной меняется на РежимЗаписиДокумента.Проведение.
При вызове функции СоздатьДокумент(), мы планируем воспользоваться возвращенной ей ссылкой на созданный документ для открытия его формы с помощью метода ОткрытьЗначение().
Функция СоздатьДокумент принимает один параметр – РежимЗаписи, который мы используем после создания документа для задания режима его записи.
В переменной Документ, после работы метода СоздатьДокумент(), мы имеем объект типа ДокументОбъект, новый чистый документ, с которым можем работать. Мы заполняем дату с помощью функции ТекущаяДата(). Заполняя реквизиты мы пользуемся различными методами поиска данных в справочнике. Метод НайтиПоКоду() позволяет найти элемент справочника по заданному коду, НайтиПоРеквизиту() ищет по значению заданного реквизита. Оба эти метода возвращают нам ссылку на элемент справочника.
В реквизит Комментарий мы записываем строку.
Следующим этапом работы с документом становится заполнение его табличной части. Мы выполняем заполнение построчно, добавляя в табличную часть строку – она представлена в коде переменной НоваяСтрокаТЧ с типом Строка табличной части. Когда строка добавлена, мы обращаемся к ее реквизитам, заполняя их данными.
После того, как документ сформирован, мы записываем его (или – и записываем и проводим – в зависимости от значения параметра РежимЗаписи) и возвращаем ссылку на него в точку вызова функции СоздатьДокумент.
Форма документа, созданного программно с помощью нашего кода, рис. 7.15.
Рис. 7.15. Документ, созданный автоматически
Решим теперь следующую задачу. Нужно пометить на удаление все документы типа ПоступлениемМатериалов, которые созданы автоматически – их реквизит Комментарий содержит текст "Документ создан автоматически".
Добавим в форму обработки новую команду, назовем ее ПометитьНаУдаление. Поставленную задачу можно реализовать с помощью следующего кода:
&НаКлиенте
Процедура ПометитьНаУдаление(Команда)
ПометитьДокументыНаУдаление();
Предупреждение("Были помечены на удаление документы поступления материалов");
КонецПроцедуры
Процедура ПометитьДокументыНаУдаление()
Запрос = Новый Запрос;
Запрос.Текст =
"ВЫБРАТЬ
| ПоступлениеМатериалов.Ссылка
|ИЗ
| Документ.ПоступлениеМатериалов КАК ПоступлениеМатериалов
|ГДЕ
| ПоступлениеМатериалов.Комментарий = &Комментарий";
Запрос.УстановитьПараметр("Комментарий", "Документ создан автоматически");
Результат = Запрос.Выполнить();
ВыборкаДетальныеЗаписи = Результат.Выбрать();
Пока ВыборкаДетальныеЗаписи.Следующий() Цикл
Документ=ВыборкаДетальныеЗаписи.Ссылка.ПолучитьОбъект();
Документ.УстановитьПометкуУдаления(Истина);
КонецЦикла;
КонецПроцедуры
Здесь мы, в серверной процедуре ПометитьДокументыНаУдаление(), получаем с помощью запроса список ссылок на документы, реквизит Комментарий которых равен нужному нам значению. После этого в цикле обхода выборки запроса переходим от ссылки на объект к объекту (тип ДокументОбъект) и устанавливаем у объектов пометки удаления.
При завершении серверной процедуры, мы, на клиенте, показываем пользователю окно сообщения, рис. 7.16.
Рис. 7.16. Сообщение пользователю о пометке документов на удаление
Нашей следующей задачей будет вывод пользователю списка документов за заданный пользователем период. Добавим в форму обработки команду ВыводСпискаДокументовЗаПериод и два реквизита – ДатаНачала и ДатаОкончания – тип Дата, состав даты – Дата и время. Дата документа содержит сведения о дате и времени создания документа, поэтому для выбора периода, в который должны попасть искомые документы, нам понадобятся значения даты с датой и временем.
Решение задачи может выглядеть так:
&НаКлиенте
Процедура ВыводСпискаДокументовЗаПериод(Команда)
Сообщить("Обнаружены следующие документы за период с "+ДатаНачала+" по "+ДатаОкончания);
ВыводСписка();
КонецПроцедуры
Процедура ВыводСписка()
Выборка=Документы.ПоступлениеМатериалов.Выбрать(ДатаНачала, ДатаОкончания);
Пока Выборка.Следующий() Цикл
Сообщить(Выборка.Ссылка);
КонецЦикла
КонецПроцедуры
Здесь мы пользуемся методом Выбрать с параметрами, устанавливающими дату начала и дату окончания для выборки документов. Полученную выборку перебираем в цикле и сообщаем пользователю о найденных документах, рис. 7.17.
Рис. 7.17. Вывод списка документов, принадлежащих периоду, заданному пользователем