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

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

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

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

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

Объект ТабличныйДокумент хранит ячейки в виде матрицы: у каждой ячейки есть номер строки и номер колонки, начиная с единицы. Фактические размеры заполненной части доступны через свойства ВысотаТаблицы (число строк) и ШиринаТаблицы (число колонок). За пределами этих границ ячейки существуют виртуально, но обращение к ним возвращает пустые области.

Строка как самостоятельный объект отсутствует. Когда говорят «получить строку табличного документа», обычно имеют в виду одно из трех действий: получить область, охватывающую всю строку; прочитать значения всех ячеек этой строки; вывести строку в другой табличный документ. Каждое действие решается своим методом.

Получение области строки через ПолучитьОбласть

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

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

ОбластьСтроки = ТабДок.ПолучитьОбласть("R5");
// ОбластьСтроки — отдельный табличный документ с одной строкой

// Вставить эту строку в другой документ:
Результат.ВставитьОбласть(ОбластьСтроки.Область("R1"),
Результат.Область(Результат.ВысотаТаблицы + 1, 1));

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

Чтение значений ячеек строки по координатам

Самый прямой способ получить содержимое строки — обратиться к каждой ячейке по номеру строки и колонки. Свойство Текст области возвращает отображаемый текст, свойство Параметр — значение параметра, если ячейка была заполнена через параметр макета.

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

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

Если нужно именно типизированное значение (число, дата, ссылка), а не его строковое представление, читайте Ячейка.Параметр. Но учитывайте: у ячеек, заполненных присвоением текста напрямую, параметр пуст, и значение придется приводить из строки самостоятельно.

Перебор всех строк документа

Типовая задача — пройти по всем строкам и собрать данные в таблицу значений или массив структур. Границы цикла задают свойства ВысотаТаблицы и ШиринаТаблицы.

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

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

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

Поиск нужной строки по содержимому

Когда номер строки заранее неизвестен, ее находят методом НайтиТекст(). Метод возвращает область найденной ячейки или Неопределено, если совпадений нет. Из найденной области извлекают координаты: свойства Верх (номер строки) и Лево (номер колонки).

Найденная = ТабДок.НайтиТекст("Итого", , , Истина);
Если Найденная <> Неопределено Тогда
НомерСтроки = Найденная.Верх;
// читаем соседние ячейки этой строки
СуммаИтого = ТабДок.Область(НомерСтроки, Найденная.Лево + 1).Текст;
КонецЕсли;

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

НайтиТекст ищет по отображаемому тексту с учетом формата. Если число выведено как «1 234,56», искать нужно именно эту строку, а не «1234.56» — иначе совпадение не будет найдено.

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

Макет табличного документа

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

Результат СКД или запроса

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

Сравнение вариантов

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

Подходит для переноса строки с оформлением; медленнее при массовом переборе

Область(Строка, Колонка).Текст

Быстрое чтение значений; оформление недоступно, только текст или параметр

НайтиТекст

Когда номер строки неизвестен; требует точного совпадения отображаемого текста

Типичные ошибки и их признаки

Наиболее частая проблема — обращение к ячейке за границами заполненной области. Ошибки выполнения при этом обычно нет, просто возвращается пустой текст, и логика разбора молча дает неверный результат. Всегда сверяйте номера строк с ВысотаТаблицы.

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

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

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

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

Количество прочитанных строк

Норма

Совпадает с числом строк источника минус заголовки

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

Меньше ожидаемого — проверьте границы цикла и пустые строки

Значения в числовых колонках

Норма

Числа преобразуются без ошибок

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

Строки с пробелами-разделителями не преобразуются — нужна очистка

Данные из объединенных ячеек

Норма

Значение читается из левой верхней ячейки области

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

Пустой текст при непустом отображении на экране

FAQ

Как получить номер строки ячейки, найденной через НайтиТекст?

Метод возвращает область, у которой свойство Верх содержит номер строки, а Лево — номер колонки. Сохраните эти значения в переменные и используйте для чтения соседних ячеек той же строки.

Можно ли обратиться к строке по имени, как к именованной области?

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

Почему Область(Строка, Колонка).Текст возвращает пустую строку, хотя на экране значение видно?

Чаще всего ячейка входит в объединенную область, а текст хранится в ее левой верхней ячейке. Реже — значение записано в параметр без шаблона отображения. Проверьте оба свойства и факт объединения ячеек.

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

Готового метода преобразования нет. Стандартный подход — цикл по строкам от 1 до ВысотаТаблицы с чтением ячеек и заполнением таблицы значений. Для больших файлов из Excel рассмотрите чтение через механизмы работы с файлами напрямую, минуя табличный документ.

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

Получите строку через ПолучитьОбласть("R" + НомерСтроки), затем вставьте ее в целевой документ методом ВставитьОбласть, указав источник и ячейку вставки. Так переносятся и данные, и оформление строки.

Чем отличаются свойства Текст и Параметр у ячейки?

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