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

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

В языке 1С для этого есть несколько подходов: обращение к области по координатам или имени, чтение текущей области на форме, последовательный перебор ячеек через свойства Текст и Значение. Каждый способ имеет свои ограничения: например, ячейка может содержать только текст-шаблон, а не значение, а попытка прочитать несуществующую область вызовет ошибку.

Ниже разобраны рабочие способы с примерами кода, критерии выбора между ними, типичные ошибки и способы проверить, что прочитано именно то, что нужно.

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

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

Каждая ячейка хранит несколько представлений данных. Свойство Текст возвращает то, что видно на экране или на печати, — всегда строку. Свойство Значение доступно, если тип содержимого ячейки — «Значение», и возвращает типизированные данные (число, дату, ссылку). Если макет заполнен через параметры, фактические данные лежат в свойстве Параметры самого табличного документа, а в ячейке хранится только шаблон вида [Номенклатура].

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

Базовый способ — метод Область() объекта ТабличныйДокумент. Он принимает либо четыре числа (верхняя строка, левая колонка, нижняя строка, правая колонка), либо строку-адрес в формате «R1C1», либо имя именованной области.

ТабДок = Новый ТабличныйДокумент;
ТабДок.Прочитать("C:\Temp\Данные.mxl");

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

// Диапазон ячеек
Диапазон = ТабДок.Область(2, 1, 10, 5);

// Именованная область из макета
ОбластьШапка = ТабДок.Область("Шапка");

Если именованной области с таким именем нет, метод вернёт Неопределено (в ряде версий платформы — вызовет исключение), поэтому перед обращением к свойствам результата полезна проверка. Адресация «R1C1» удобна, когда координаты вычисляются динамически: ТабДок.Область("R" + НомерСтроки + "C" + НомерКолонки).

Чтение значения ячейки: Текст, Значение и Параметры

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

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

Ячейка = ТабДок.Область(5, 2);
Если Ячейка.СодержитЗначение Тогда
Результат = Ячейка.Значение; // типизированное значение
Иначе
Результат = Ячейка.Текст;    // строковое представление
КонецЕсли;

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

Когда табличный документ отображён на форме в элементе «Поле табличного документа», пользователь может выделить ячейку или диапазон. Получить выделенную область помогает свойство ТекущаяОбласть расширения поля табличного документа.

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

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

Перебор всех ячеек и чтение данных построчно

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

Для НомерСтроки = 2 По ТабДок.ВысотаТаблицы Цикл
Наименование = ТабДок.Область(НомерСтроки, 1).Текст;
Артикул      = ТабДок.Область(НомерСтроки, 2).Текст;
Если ПустаяСтрока(Наименование) Тогда
Продолжить; // пропускаем пустые строки
КонецЕсли;
// дальнейшая обработка: поиск в справочнике, создание документа
КонецЦикла;

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

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

Сравнение способов и выбор под задачу

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

Что читать: Текст или Значение

Ячейка.Текст

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

Ячейка.Значение

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

ТабДок.Параметры.Имя

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

Типичные ошибки и проверка результата

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

Третья группа проблем — границы: первая строка и колонка имеют номер 1, а не 0; попытка прочитать строку 0 или колонку 0 вызывает ошибку. При обработке файлов из Excel помните, что пустые «хвостовые» строки могут входить в ВысотаТаблицы, поэтому в цикле нужна проверка на пустоту ключевых колонок.

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

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

Результат Область()

Норма

Возвращён объект области, свойства доступны

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

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

Содержимое ячейки

Норма

Значение ожидаемого типа (число, дата, строка)

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

Строка с разделителями вместо числа или шаблон в квадратных скобках

Перебранная таблица

Норма

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

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

Пропущены строки с объединёнными ячейками или захвачены пустые хвостовые строки

FAQ

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

Платформа использует адресацию вида «R1C1», поэтому адрес в стиле Excel нужно преобразовать: букву колонки перевести в номер (A → 1, B → 2) и вызвать Область(номерСтроки, номерКолонки). Для колонок после Z потребуется функция разбора буквенного кода.

Почему Область("Шапка") возвращает пустое значение?

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

Как прочитать число из ячейки, если Текст возвращает строку с пробелами?

Если ячейка содержит типизированное значение, используйте свойство Значение. Если доступен только Текст, удалите неразрывные пробелы через СтрЗаменить(Текст, Символ(160), "") и обычные пробелы, затем преобразуйте строку функцией Число().

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

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

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

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

Что вернёт свойство Текст у объединённой ячейки?

Текст хранится в левой верхней ячейке объединённого диапазона. Обращение к остальным ячейкам диапазона вернёт пустую строку. Определить объединение можно по свойствам области: у объединённой ячейки размеры (Верх–Низ, Лево–Право) больше одной строки или колонки.