Как вставить таблицу значений в табличный документ 1С

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

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

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

Какой способ вывода выбрать

Прежде чем писать код, определите требования к результату. Если печатная форма регламентирована (счёт, акт, ТОРГ-12), нужен макет с фиксированными областями — только так вы гарантируете точное расположение реквизитов, рамок и шрифтов.

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

Для быстрых служебных отчётов, где важна скорость разработки, а не дизайн, подойдёт построитель отчёта: он сам строит шапку и строки по произвольной таблице значений.

Сравнение способов вывода

Макет с областями

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

Заполнение по координатам

Подходит при динамическом наборе колонок. Оформление задаётся кодом, объём работы больше.

Построитель отчёта

Быстрый вывод любой таблицы значений без макета. Оформление минимальное, тонкая настройка затруднена.

Подготовка макета с областями

Создайте макет типа «Табличный документ» — в общих макетах конфигурации или у конкретного объекта. В макете выделите строки будущей шапки, щёлкните правой кнопкой и задайте имя области, например «Шапка». Аналогично создайте область «Строка» для одной строки данных и при необходимости «Подвал» для итогов.

Внутри ячеек области «Строка» укажите параметры: в свойстве ячейки «Заполнение» выберите «Параметр», а в тексте ячейки впишите имя параметра, например [Номенклатура] или просто Номенклатура с типом заполнения «Параметр». Имена параметров удобно делать совпадающими с именами колонок таблицы значений — это упростит код вывода.

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

Вывод таблицы значений через макет: пошаговый код

Основной сценарий: получить макет, получить области, вывести шапку один раз, затем в цикле по строкам таблицы значений заполнять параметры области «Строка» и выводить её в табличный документ.

ТабДок = Новый ТабличныйДокумент;
Макет = ПолучитьМакет("МакетОтчета");

ОбластьШапка = Макет.ПолучитьОбласть("Шапка");
ОбластьСтрока = Макет.ПолучитьОбласть("Строка");
ОбластьПодвал = Макет.ПолучитьОбласть("Подвал");

ТабДок.Вывести(ОбластьШапка);

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

ОбластьПодвал.Параметры.ИтогоСумма = ТаблицаЗначений.Итог("Сумма");
ТабДок.Вывести(ОбластьПодвал);

Если имена параметров совпадают с именами колонок, заполнение можно сократить до одной строки: ОбластьСтрока.Параметры.Заполнить(СтрокаТЗ);. Метод Заполнить() переносит значения по совпадающим именам, что удобно при большом числе колонок.

После вывода установите служебные свойства документа: ТабДок.АвтоМасштаб = Истина;, ориентацию страницы, поля. Для показа пользователю используйте ТабДок.Показать("Отчёт") в обычном приложении или поместите документ в реквизит формы типа «ТабличныйДокумент» в управляемом приложении.

1. 1
   Создайте макет и разметьте области Шапка, Строка, Подвал
2. 2
   Укажите параметры в ячейках области Строка
3. 3
   Получите макет и области в коде
4. 4
   Выведите шапку один раз
5. 5
   В цикле заполните параметры и выведите область для каждой строки таблицы значений
6. 6
   Выведите подвал с итогами и покажите документ пользователю

Заполнение ячеек напрямую без макета

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

ТабДок = Новый ТабличныйДокумент;
НомерСтроки = 1;

// Шапка из имён колонок
НомерКолонки = 1;
Для Каждого Колонка Из ТаблицаЗначений.Колонки Цикл
Ячейка = ТабДок.Область(НомерСтроки, НомерКолонки);
Ячейка.Текст = Колонка.Имя;
Ячейка.Шрифт = Новый Шрифт(,, Истина);
НомерКолонки = НомерКолонки + 1;
КонецЦикла;

// Данные
Для Каждого СтрокаТЗ Из ТаблицаЗначений Цикл
НомерСтроки = НомерСтроки + 1;
Для НомерКолонки = 1 По ТаблицаЗначений.Колонки.Количество() Цикл
ТабДок.Область(НомерСтроки, НомерКолонки).Текст =
Строка(СтрокаТЗ[НомерКолонки - 1]);
КонецЦикла;
КонецЦикла;

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

Для оформления задайте границы программно: Ячейка.ГраницаСверху = Новый Линия(ТипЛинииЯчейкиТабличногоДокумента.Сплошная); — и так для каждой стороны. Учтите, что массовая установка свойств по одной ячейке медленнее вывода готовых областей макета, поэтому на больших таблицах (десятки тысяч строк) этот способ заметно проигрывает по скорости.

Быстрый вывод через построитель отчёта

Для служебных задач — посмотреть содержимое таблицы значений, отладить расчёт, выгрузить простой список — используйте объект ПостроительОтчета. Ему достаточно передать источник данных, и он сам сформирует шапку и строки.

Построитель = Новый ПостроительОтчета;
Построитель.ИсточникДанных = Новый ОписаниеИсточникаДанных(ТаблицаЗначений);
Построитель.ЗаполнитьНастройки();

ТабДок = Новый ТабличныйДокумент;
Построитель.Вывести(ТабДок);

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

Ограничение способа — оформление: построитель использует стандартные стили, и вмешаться в дизайн отдельных ячеек сложно. Для печатных форм, которые увидит клиент, этот вариант не подходит.

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

Группировки, итоги и разрывы страниц

Если таблица значений содержит данные нескольких документов или контрагентов, логично группировать строки. Отсортируйте таблицу по полю группировки (ТаблицаЗначений.Сортировать("Контрагент")), затем в цикле отслеживайте смену значения: при смене выводите область «ПодвалГруппы» с промежуточным итогом и область «ШапкаГруппы» для новой группы.

Для контроля разрывов страниц используйте метод ТабДок.ПроверитьВывод(МассивОбластей). Он возвращает Истина, если переданные области помещаются на текущей странице. Если нет — выведите горизонтальный разделитель страниц: ТабДок.ВывестиГоризонтальныйРазделительСтраниц(), затем повторите шапку.

МассивОбластей = Новый Массив;
МассивОбластей.Добавить(ОбластьСтрока);

Если Не ТабДок.ПроверитьВывод(МассивОбластей) Тогда
ТабДок.ВывестиГоризонтальныйРазделительСтраниц();
ТабДок.Вывести(ОбластьШапка);
КонецЕсли;

ТабДок.Вывести(ОбластьСтрока);

При группировке проверяйте вывод совместно строки и первой строки следующей группы, чтобы на странице не остался «висячий» подвал без данных. Это стандартный приём для печатных форм с итогами.

Типичные ошибки и как их избежать

Самая частая проблема — пустые ячейки в результате. Причина почти всегда в несовпадении имени параметра в макете и имени, используемого в коде, либо в том, что у ячейки не установлен тип заполнения «Параметр». Откройте макет и сверьте имена посимвольно.

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

Третья группа проблем — производительность и память при больших объёмах. Не выводите в табличный документ данные «на всякий случай»: табличный документ хранит оформление каждой ячейки и плохо масштабируется. Для выгрузки больших массивов предназначены другие механизмы — текстовый файл, CSV, Excel через COM-объект или пакетная запись.

Проверка результата перед печатью

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

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

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

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

Число строк данных

Норма

Равно количеству строк таблицы значений

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

Строк меньше или больше — проверяйте цикл и фильтры

Итоговые суммы

Норма

Совпадают с ТаблицаЗначений.Итог() по каждой суммовой колонке

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

Расхождение — проверяйте заполнение параметров и округление

Перенос страниц

Норма

Шапка повторяется, подвал не оторван от строк

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

Висячие итоги или обрезанные строки — добавьте ПроверитьВывод

FAQ

Как вывести таблицу значений, если имена колонок содержат пробелы или кириллицу?

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

Можно ли вывести таблицу значений в уже существующий табличный документ, не очищая его?

Да. Табличный документ — это объект с текущей позицией вывода. Метод Вывести() добавляет области ниже уже выведенных. Если нужно очистить документ, вызовите метод Очистить(). Для вставки в середину используйте метод ВставитьОбласть() с указанием области-приёмника.

Как вывести картинку или штрихкод в строку табличного документа?

Добавьте в макет ячейку с типом «Картинка» и заполнением «Параметр», затем в коде присвойте параметру объект типа Картинка. Для штрихкода используйте компоненту формирования штрихкодов и специальный макет с элементом управления штрихкода — подход зависит от версии платформы и используемой библиотеки печати.

Почему при выводе через ПостроительОтчета колонки выходят в другом порядке?

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

Как ускорить вывод большой таблицы значений?

Используйте вывод областей макета вместо поячеечного заполнения, заполнение параметров методом Заполнить() вместо построчного присваивания и ограничьте объём данных. Если строк больше нескольких десятков тысяч, рассмотрите выгрузку в Excel или CSV — табличный документ не предназначен для таких объёмов.

Как повторять шапку таблицы на каждой странице при печати?

Установите у табличного документа свойство ПовторятьПриПечатиСтроки, указав область-строку шапки (например, ТабДок.ПовторятьПриПечатиСтроки = ТабДок.Область(1, , 2, )). Альтернатива — программный вывод шапки после каждого горизонтального разделителя страниц при использовании ПроверитьВывод().