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

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

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

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

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

Область табличного документа описывается координатами: номер первой строки, номер первой колонки, номер последней строки, номер последней колонки. Одна ячейка — частный случай области, где начало и конец совпадают. Адрес ячейки записывается в стиле R5C3 (строка 5, колонка 3), диапазон — как R5C3:R10C7.

Области бывают именованными и неименованными. Именованные создаются в макете конфигуратором (выделить диапазон → свойства → задать имя) и используются при программном выводе: ПолучитьОбласть("Шапка"). Неименованные области доступны только по координатам или через поиск.

Важно понимать: тип ОбластьЯчеекТабличногоДокумента — это «живая» ссылка на диапазон внутри конкретного табличного документа. Если документ очищен или пересоздан, ранее полученная область может стать недействительной.

Как найти область по тексту: метод НайтиТекст

Самый частый сценарий — есть заполненный табличный документ (например, результат отчёта или загруженный из Excel файл), и нужно найти ячейку с определённым текстом. Для этого служит метод НайтиТекст:

Область = ТабДок.НайтиТекст("Итого", , , Истина, Истина, Истина);

Если Область = Неопределено Тогда
Сообщить("Текст не найден");
Иначе
Сообщить("Найдено в строке " + Область.Верх + ", колонке " + Область.Лево);
КонецЕсли;

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

Для поиска всех вхождений вызывайте НайтиТекст в цикле, передавая найденную область как начальную точку следующего поиска. Учтите: поиск по шаблону использует специальные символы (*, ?), поэтому для точного совпадения лучше отключать этот параметр.

1. 1
   Убедитесь, что табличный документ заполнен (ВысотаТаблицы больше 0)
2. 2
   Вызовите ТабДок.НайтиТекст с нужным текстом и режимом поиска
3. 3
   Проверьте результат на Неопределено перед обращением к свойствам
4. 4
   Считайте координаты через свойства Верх, Лево, Низ, Право найденной области

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

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

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

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

Для вертикальных именованных областей допустимо указание конкретных строк: ПолучитьОбласть("Строка|Колонка1") — пересечение вертикальной и горизонтальной именованных областей. Это удобно, когда макет содержит несколько вариантов оформления одной строки.

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

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

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

// По строковому адресу
Ячейка = ТабДок.Область("R5C3");
Диапазон = ТабДок.Область("R5C3:R10C7");

// По числовым координатам: верх, лево, низ, право
Диапазон2 = ТабДок.Область(5, 3, 10, 7);

// Одна ячейка по координатам
Ячейка2 = ТабДок.Область(5, 3);

У полученной области доступны свойства: Текст (отображаемый текст), Значение (для ячеек, содержащих значение), Верх, Низ, Лево, Право, Имя, а также свойства оформления — ЦветФона, Шрифт, Границы и другие.

Размеры документа узнаются через свойства ВысотаТаблицы (количество строк) и ШиринаТаблицы (количество колонок). Эти значения используют как границы при обходе документа в цикле:

Для НомерСтроки = 1 По ТабДок.ВысотаТаблицы Цикл
ТекстЯчейки = ТабДок.Область(НомерСтроки, 1).Текст;
// обработка
КонецЦикла;

Как узнать область, выделенную пользователем

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

&НаКлиенте
Процедура ПоказатьТекущуюОбласть(Команда)
Область = Элементы.ТабДок.ТекущаяОбласть;
Сообщить("Имя: " + Область.Имя + ", строка " + Область.Верх);
КонецПроцедуры

Для реакции на изменение выделения используется событие поля табличного документа ПриАктивизацииОбласти. В обработчике через Элементы.ТабДок.ТекущаяОбласть доступна активная область, а через её свойство Расшифровка — данные расшифровки отчёта, если документ построен на СКД.

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

Область = ТабДок.НайтиТекст("Итого");
Если Область <> Неопределено Тогда
    Элементы.ТабДок.ТекущаяОбласть = Область;
КонецЕсли;

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

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

Для Каждого Обл Из ТабДок.Области Цикл
Сообщить(Обл.Имя + ": строки " + Обл.Верх + "–" + Обл.Низ);
КонецЦикла;

Обратиться к конкретной именованной области можно и через индекс коллекции: ТабДок.Области.Найти("Шапка") вернёт область по имени или Неопределено. Это безопасный способ проверить существование области без исключения.

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

Типичные ошибки и ограничения

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

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

Третья — попытка использовать ТекущаяОбласть у реквизита формы типа ТабличныйДокумент вместо элемента формы. У объекта ТабличныйДокумент такого свойства нет, оно есть только у элемента формы «ПолеТабличногоДокумента».

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

После получения области убедитесь, что она указывает на ожидаемое место. Минимальный набор проверок: координаты не выходят за пределы документа (Верх <= ВысотаТаблицы, Лево <= ШиринаТаблицы), текст области соответствует ожиданиям, имя области заполнено, если работа ведётся с именованными диапазонами.

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

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