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

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

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

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

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

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

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

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

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

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

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

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

После получения область заполняют параметрами. Параметры — это именованные placeholders в ячейках макета (в свойствах ячейки указано «Заполнение: Параметр»). Обращение идёт через коллекцию Параметры:

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

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

Адресация области по координатам ячеек

Когда имена областей не заданы или нужен произвольный фрагмент, используют строку адреса в формате R1C1: "R2C1:R5C8" — прямоугольник со второй по пятую строку и с первой по восьмую колонку. Одна ячейка адресуется как "R3C4", целая строка — "R7", диапазон строк — "R10:R20".

// Одна ячейка
ОбластьЯчейка = ТабДок.ПолучитьОбласть("R3C4");
Значение = ОбластьЯчейка.ТекущаяОбласть.Текст;

// Диапазон строк
ОбластьСтрок = ТабДок.ПолучитьОбласть("R5:R12");

// Прямоугольный диапазон
ОбластьДиапазон = ТабДок.ПолучитьОбласть("R2C1:R10C6");

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

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

Вывод областей в цикле и проверка влезания на страницу

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

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

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

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

Также полезен метод ВывестиГоризонтально() — он добавляет область справа от уже выведенного содержимого, а не снизу. Это используется для форм с несколькими колонками данных, например при печати этикеток по несколько штук в ряд.

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

Получение области из уже заполненного документа

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

Для чтения значений удобнее обращаться к ячейкам напрямую через метод Область(), который возвращает объект ячейки без копирования фрагмента:

Ячейка = ТабДок.Область("R" + НомерСтроки + "C2");
ЗначениеЯчейки = Ячейка.Текст;

Различие принципиально: ПолучитьОбласть() создаёт копию фрагмента документа — изменения в ней не затронут оригинал, пока область не будет выведена обратно. А Область() возвращает ссылку на живую ячейку: присвоение Ячейка.Текст = "Новое значение" сразу меняет документ. Путаница между этими методами — частая причина «не сохраняющихся» правок.

ПолучитьОбласть или Область

ПолучитьОбласть()

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

Область()

Возвращает ссылку на живую ячейку или диапазон. Подходит для чтения и изменения содержимого текущего документа.

НайтиТекст()

Ищет ячейку по содержимому. Подходит, когда позиция данных в документе заранее неизвестна.

Типичные ошибки и как их диагностировать

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

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

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

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

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

Область получена

Норма

Метод вернул объект без исключения

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

Ошибка «Область не найдена» — сверить имя с макетом

Параметры заполнены

Норма

В выведенной области подставлены значения вместо шаблонов

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

Видны имена параметров или пустые места

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

Норма

Таблица не обрывается посреди строки, заголовок повторяется

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

Строки разрываются, заголовок теряется — нужен ПроверитьВывод

FAQ: частые вопросы о получении областей

Можно ли получить область по имени из заполненного табличного документа, а не из макета?

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

Чем ПолучитьОбласть отличается от метода Область?

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

Как получить область из внешнего файла Excel?

Сначала загрузите файл в табличный документ методом Прочитать() с указанием способа чтения «Значение» или «Текст». Именованных областей в таком документе не будет, поэтому данные извлекают по координатам: перебором строк и обращением к ячейкам вида Область("R5C2").

Почему ПолучитьОбласть возвращает пустую область без ошибки?

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

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

Используйте метод ВывестиГоризонтально() вместо Вывести(). Он присоединяет область справа от текущего содержимого. Так строят многоколоночные формы, например печать нескольких этикеток в одной строке листа.

Чувствительно ли имя области к регистру букв?

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