К статье
Практический материал

Другое · 6 мин

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

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

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

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

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

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

Строкой табличного документа понимается горизонтальный набор ячеек с фиксированным номером внутри объекта ТабличныйДокумент. Каждая строка может содержать текст, числа, даты, ссылки или быть пустой, в зависимости от того, что выводилось в документ.

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

Порядок действий
  1. 1
    Убедитесь, что объект является табличным документом, а не таблицей значений
  2. 2
    Проверьте, что номер строки находится в допустимом диапазоне
  3. 3
    Получите область строки через метод Область
  4. 4
    Пройдите по колонкам и считайте значения ячеек
  5. 5
    Проверьте результат на пустые или некорректные данные

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

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

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

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

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

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

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

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

Номер строки в допустимом диапазоне
Норма

Чтение завершилось без ошибки

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

Ошибка индекса за пределами коллекции

Ячейка заполнена
Норма

Получено текстовое или числовое значение

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

Пустая строка или неопределенное значение

Проверка индексов и границы безопасной работы

Номер строки должен быть больше или равен единице и не превышать количество строк табличного документа. Аналогичное правило справедливо для колонок. Выход за эти границы приводит к ошибке выполнения и может прервать обработку документа.

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

bsl
Если НомерСтроки < 1 Или НомерСтроки > ТабличныйДокумент.КоличествоСтрок() Тогда
    Возврат Неопределено;
КонецЕсли;

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

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

Отличие от таблицы значений и альтернативы

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

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

Типичные ошибки и что делать если строка не найдена

Типичные ошибки
01
Обращение к строке с нулевым или отрицательным номером вызывает ошибку выполнения
02
Чтение колонки за пределами количества колонок прерывает алгоритм
03
Путать табличный документ с таблицей значений и применять несоответствующие методы
04
Изменять проведенный документ без проверки последствий для остатков и регистров

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

Когда данные отсутствуют по логике отчета, верните признак отсутствия строки вместо выдуманного значения. Это позволит вызывающему коду корректно обработать ситуацию, например показать пользователю сообщение или пропустить расчет.

Итог

Что важно запомнить

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

Нумерация строк начинается с единицы или с нуля?

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

Чем табличный документ отличается от таблицы значений?

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

Что делать, если строка не найдена?

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

Можно ли изменять ячейки табличного документа напрямую?

Технически изменение возможно, но в рабочей базе это опасно, особенно для проведенных документов. Сначала проверяйте алгоритм на копии и предпочитайте чтение без изменения исходных данных.