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

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

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

Материал ориентирован на встроенный язык 1С (управляемые и обычные формы). Примеры кода работают на актуальных версиях платформы 8.3 и легко адаптируются под более ранние релизы.

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

Табличный документ в 1С имеет двумерную адресацию: каждая ячейка определяется номером строки (по вертикали) и номером колонки (по горизонтали). Строки нумеруются с единицы, начиная от верхнего края документа. Адрес ячейки в стиле «R5C3» означает строка 5, колонка 3.

Ключевой объект для работы — область (ОбластьЯчеекТабличногоДокумента). Область может быть одной ячейкой, строкой, диапазоном или всем документом. У любой области есть свойства Верх, Низ, Лево, Право — это координаты границ. Для однострочной области Верх и Низ совпадают и равны номеру строки.

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

Поиск номера строки по значению ячейки

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

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

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

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

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

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

Обход всех строк документа в цикле

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

Для НомерСтроки = 2 По ТабДок.ВысотаТаблицы Цикл
// первая строка — шапка, начинаем со второй
ОбластьЯчейки = ТабДок.ПолучитьОбласть("R" + НомерСтроки + "C1");
ЗначениеЯчейки = ОбластьЯчейки.ТекущаяОбласть.Текст;
// обработка значения
КонецЦикла;

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

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

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

Номер строки текущей (выделенной) области

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

&НаКлиенте
Процедура ТабДокПриАктивизации(Элемент)
ТекущаяОбласть = Элемент.ТекущаяОбласть;
Если ТекущаяОбласть <> Неопределено Тогда
НомерСтроки = ТекущаяОбласть.Верх;
Сообщить("Выделена строка " + НомерСтроки);
КонецЕсли;
КонецПроцедуры

Здесь есть тонкость: если пользователь выделил диапазон из нескольких строк, Верх вернёт первую строку выделения, а Низ — последнюю. Если нужна именно активная ячейка внутри выделения, ориентируйтесь на Верх и Лево, но учитывайте, что при выделении целой колонки или всего документа координаты могут выходить за пределы заполненной области.

Также свойство Имя текущей области может содержать строковый адрес вида «R5C3» или имя именованной области из макета. Разобрать адрес в номера строки и колонки можно строковыми функциями, но надёжнее использовать числовые свойства Верх и Лево.

Именованные области и строки макета

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

НомерСтрокиНачало = ТабДок.ВысотаТаблицы + 1;
ТабДок.Вывести(ОбластьСтрока);
// область заняла строки с НомерСтрокиНачало по ТабДок.ВысотаТаблицы

Именованную область в уже сформированном документе можно получить методом ПолучитьОбласть("ИмяОбласти") — но только если область была выведена с сохранением имени (это происходит автоматически при выводе именованных областей макета). У полученной области свойства Верх и Низ покажут фактические номера строк в документе.

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

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

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

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

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

Проверка результата и выбор подходящего метода

После получения номера строки убедитесь, что он попадает в допустимый диапазон: от 1 до ВысотаТаблицы. Значение 0 или отрицательное число означает, что вы читаете свойство не той области или документ пуст. Для отладки выводите в сообщение не только номер строки, но и текст ячейки по этим координатам — так сразу видно, та ли строка найдена.

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

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