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

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

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

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

Что такое область табличного документа и как её получить

Область — это прямоугольный фрагмент табличного документа: одна или несколько строк, колонок либо произвольный диапазон ячеек. Области бывают именованными (заданы в макете в конфигураторе) и адресуемыми по координатам, например R1C1:R5C10.

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

Макет = Документы.РеализацияТоваровУслуг.ПолучитьМакет("МакетПечати");
ОбластьШапка = Макет.ПолучитьОбласть("Шапка");
ОбластьСтрока = Макет.ПолучитьОбласть("Строка");

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

Метод Вывести: добавление области вниз документа

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

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

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

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

1. 1
   Создайте новый объект ТабличныйДокумент
2. 2
   Получите макет через ПолучитьМакет
3. 3
   Получите нужные области методом ПолучитьОбласть
4. 4
   Заполните параметры области через свойство Параметры
5. 5
   Выведите области методом Вывести в нужной последовательности
6. 6
   Проверьте результат через Показать или запись в файл

Метод Присоединить: вывод области справа

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

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

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

Комбинация Вывести + Присоединить позволяет строить сложные формы: сначала выводится строка-заголовок, затем к ней присоединяются колонки данных, после чего следующая строка выводится снова методом Вывести.

Метод ВставитьОбласть: вставка в произвольное место

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

ОбластьПриемник = ТабДок.Область("R10C1");
ТабДок.ВставитьОбласть(ОбластьИсточник.Область(), ОбластьПриемник,
ТипСмещенияТабличногоДокумента.ПоВертикали);

Параметры метода: область-источник, область-приёмник (ячейка, начиная с которой выполняется вставка) и тип смещения. Тип смещения определяет, куда сдвинутся существующие ячейки:

• ПоВертикали — строки ниже точки вставки сдвигаются вниз на высоту вставляемой области;
• ПоГоризонтали — колонки правее точки вставки сдвигаются вправо;
• БезСмещения — ячейки в области вставки замещаются содержимым источника.

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

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

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

ОбластьКопия = ТабДок.ПолучитьОбласть("R2C1:R5C8");
ТабДок2.Вывести(ОбластьКопия);

При копировании переносятся значения ячеек, форматирование, объединения и расшифровки. Не переносятся параметры макета — после вывода в документ области уже не связаны с макетом, и обращение к Параметры у скопированной области работает иначе, чем у области макета.

Практический сценарий: формирование двух экземпляров одной формы на одном листе. Документ строится один раз, затем нужный диапазон копируется и выводится повторно ниже с разрывом страницы между копиями.

Параметры, шаблоны и заполнение области перед выводом

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

ОбластьШапка.Параметры.НомерДокумента = НомерДок;
ОбластьШапка.Параметры.ДатаДокумента = Формат(ДатаДок, "ДЛФ=D");

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

Для шаблонов текст ячейки формируется автоматически при подстановке параметров — это удобно для составных строк вида «Покупатель: [Контрагент], ИНН [ИНН]». Для параметров ячейка содержит только одно значение, зато его тип сохраняется (дата останется датой, число — числом), что важно для итогов и форматирования.

Сравнение методов вывода

Вывести

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

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

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

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

Вставляет в произвольную позицию со смещением или замещением. Подходит для правки уже сформированного документа. Требует контроля координат.

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

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

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

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

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

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

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

Норма

Области расположены в ожидаемом порядке, параметры заполнены

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

Пустые параметры, сдвинутые строки, отсутствующие блоки

Сохраните документ в файл MXL или Excel и откройте

Норма

Форматирование, объединения и границы сохранены

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

Потеряны объединения ячеек или границы таблиц

Проверьте постраничный вывод через ПроверитьВывод / ПроверитьПрисоединение

Норма

Методы возвращают Истина для выводимых областей

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

Область не помещается на страницу и обрезается при печати

Ограничения и альтернативные подходы

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

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

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

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

Чем Вывести отличается от ВставитьОбласть?

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

Почему возникает ошибка «Область не найдена»?

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

Как вставить область перед определённой строкой, а не в конец?

Определите номер целевой строки (например, через поиск текста или сохранённую координату), получите ячейку-приёмник методом Область("R" + НомерСтроки + "C1") и вызовите ВставитьОбласть с типом смещения ПоВертикали. Строки ниже точки вставки сдвинутся вниз на высоту вставляемой области.

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

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

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

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

Что делать, если присоединяемая область съезжает по высоте?

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