Как добавить строку в область в 1С

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

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

Ниже разобраны все способы добавления строк — от простого цикла вывода до вставки строк внутрь уже сформированного документа, а также типичные ошибки и способы проверки результата.

Что такое область макета и как она устроена

Макет табличного документа в 1С состоит из именованных областей. Область может быть строкой, диапазоном строк, колонкой или прямоугольным фрагментом. В конфигураторе области создаются через меню «Таблица — Имена — Назначить имя» или выделением строк и нажатием Ctrl+Shift+N.

Ячейки области бывают трёх типов заполнения: «Текст» (фиксированное значение), «Параметр» (подставляется из кода через Область.Параметры.ИмяПараметра) и «Шаблон» (текст с встроенными параметрами в квадратных скобках, например Товар: [Номенклатура]). Понимание типа ячейки важно: если ячейка имеет тип «Текст», присвоение параметра из кода её не изменит.

Базовый способ: ПолучитьОбласть и Вывести

Стандартный цикл добавления строк выглядит так: получаете макет через ПолучитьМакет("ИмяМакета"), из макета — область строки, затем в цикле по данным заполняете параметры и выводите область в табличный документ.

Макет = ЭтотОбъект.ПолучитьМакет("МакетПечати");
ОбластьСтрока = Макет.ПолучитьОбласть("Строка");

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

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

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

1. 1
   Создайте в макете именованную область строки с параметрами в ячейках
2. 2
   В коде получите макет и область методом ПолучитьОбласть()
3. 3
   В цикле заполните Область.Параметры значениями текущей строки данных
4. 4
   Вызовите ТабДок.Вывести(Область) для каждой строки
5. 5
   Проверьте результат: количество строк в ТабДок должно совпадать с числом итераций

Добавление строки по горизонтали: метод Присоединить

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

Типичный сценарий: сначала выводите шапку колонки через Вывести(), затем в цикле присоединяете значения по каждому периоду или складу. Комбинация Вывести() + Присоединить() позволяет строить кросс-таблицы без СКД.

ОбластьШапкаКолонки = Макет.ПолучитьОбласть("ШапкаКолонка");
ОбластьЯчейка      = Макет.ПолучитьОбласть("Ячейка");

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

Вывести или Присоединить

Вывести()

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

Присоединить()

Добавляет область справа на текущих строках. Подходит для кросс-отчётов и динамических колонок. Требует аккуратности с высотой областей — высоты должны совпадать.

ВставитьОбласть()

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

Заполнение параметров области: нюансы

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

Частая ситуация — параметр не заполнен, и в печатной форме выводится пустота или значение по умолчанию. Чтобы избежать «висячих» пустых значений, присваивайте параметры явно, в том числе пустые строки или нули. Для дат и чисел учитывайте формат ячейки: формат задаётся в свойствах ячейки макета через конструктор форматной строки, а не в коде.

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

Контроль разрыва страниц при выводе строк

При выводе большого числа строк печатная форма разбивается на страницы, и строка может оказаться «разорванной» между листами. Чтобы этого избежать, используют метод ПроверитьВывод(МассивОбластей) — он возвращает Истина, если переданные области помещаются на текущей странице.

Типовой приём: перед выводом очередной строки проверяют, поместится ли она вместе с подвалом. Если нет — выводят подвал страницы, затем новую шапку, и только потом строку.

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

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

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

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

Вставка строки в середину сформированного документа

Иногда строку нужно добавить не в конец, а внутрь уже готового табличного документа — например, вставить строку итогов по группе перед строками детализации. Для этого служит метод ВставитьОбласть(ОбластьИсточник, ОбластьПриёмник, ТипСмещения).

Область приёмника задаётся как объект ОбластьЯчеекТабличногоДокумента, которую получают через ТабДок.Область("R10C1:R10C5") или по имени ранее выведенной именованной области. Тип смещения определяет, куда сдвинутся существующие ячейки — по вертикали или по горизонтали.

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

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

Большинство проблем при добавлении строк связаны с невнимательностью к макету, а не к коду. Ниже — ошибки, которые встречаются чаще всего.

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

Проверка результата

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

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

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

Количество строк

Норма

ВысотаТаблицы соответствует шапке + N строк данных + подвалу

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

Строк меньше, чем записей в данных — часть не выведена

Значения параметров

Норма

В каждой строке отображаются данные соответствующей записи

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

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

Разрывы страниц

Норма

Строка не разрезана, шапка повторяется на каждой странице

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

Половина строки на одном листе, половина на другом

Для визуальной проверки используйте ТабДок.Показать() в отладке или сохраните документ в файл через ТабДок.Записать() и откройте в Excel — так проще заметить съехавшую вёрстку.

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

Как добавить пустую строку в табличный документ?

Получите область строки из макета и вызовите ТабДок.Вывести(Область), не заполняя параметры, либо присвойте параметрам пустые значения. Если области в макете нет, можно вывести любую область-заглушку нужной высоты.

Почему параметр не заполняется, хотя код выполняется без ошибок?

Чаще всего ячейка в макете имеет тип заполнения «Текст» вместо «Параметр» или «Шаблон». Откройте свойства ячейки в макете и измените тип заполнения. Также проверьте точное совпадение имени параметра.

Как вывести строки с группировкой и итогами по группам?

Создайте в макете отдельные области: «ГруппаШапка», «Строка», «ГруппаПодвал». При обходе выборки с обходом по группировкам (метод Выбрать(ОбходРезультатаЗапроса.ПоГруппировкам)) выводите шапку группы, затем детальные строки, затем подвал группы с итогами.

Можно ли добавить строку в уже открытый у пользователя табличный документ?

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

Чем отличается область «Строка» от области «Колонка» в макете?

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

Как программно создать строку без макета?

Можно работать напрямую с ячейками: ТабДок.Область("R5C2").Текст = "Значение". Это подходит для простых случаев, но для печатных форм с оформлением предпочтительнее макет — вёрстка, шрифты и границы задаются в нём централизованно.