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

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

Адресовать ячейку можно несколькими способами: по координатам вида «R1C1», по имени области, заданному в макете, или по номерам строк и колонок через четыре числовых параметра. Выбор способа зависит от задачи: для макетов удобнее именованные области, для программного обхода — числовые координаты.

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

Метод Область(): основные способы адресации

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

• ТабДок.Область("R5C3") — одна ячейка на пересечении строки 5 и колонки 3;
• ТабДок.Область("R2C1:R10C4") — прямоугольный диапазон;
• ТабДок.Область("R5") — вся пятая строка;
• ТабДок.Область("C3") — вся третья колонка;
• ТабДок.Область("ШапкаДата") — именованная область из макета;
• ТабДок.Область(5, 3, 5, 3) — то же, что R5C3, но числовыми параметрами.

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

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

// Обращение по адресу R1C1
Ячейка = ТабДок.Область("R3C2");
Ячейка.Текст = "Итого";

// Обращение по координатам
Ячейка2 = ТабДок.Область(4, 2, 4, 2);
Ячейка2.Текст = Формат(СуммаДокумента, "ЧДЦ=2");

Обращение к ячейке по имени области из макета

Если табличный документ строится из макета, правильнее работать через именованные области. Имя ячейке или диапазону задают в редакторе макета: выделяют ячейки и в поле имени (слева от строки формул) вводят название, например «НомерДокумента» или «ИтогоСумма».

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

ОбластьИтого = ТабДок.Область("ИтогоСумма");
ОбластьИтого.Текст = Формат(Итог, "ЧДЦ=2");

Такой подход устойчив к изменениям макета: если в шапку добавят строки, адреса сместятся, а именованная область останется на месте. Код по координатам в этой ситуации придётся переписывать.

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

Чтение и запись значений ячейки

Получив область, вы работаете с её свойствами. Ключевые из них:

• Текст — строка, отображаемая в ячейке. Доступна для чтения и записи;
• Значение — типизированное значение ячейки, если в макете для ячейки установлено свойство «Содержит значение»;
• Параметр — доступ к параметру ячейки, если она объявлена как параметр макета;
• ТипЗначения — описание типов, допустимых для ячейки.

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

// Запись текста
ТабДок.Область("R2C1").Текст = "Покупатель";

// Запись типизированного значения
ЯчейкаСумма = ТабДок.Область("СуммаСтроки");
ЯчейкаСумма.Значение = 1250.50;

// Чтение значения
Сумма = ТабДок.Область(10, 3, 10, 3).Значение;
Если ТипЗнч(Сумма) = Тип("Число") Тогда
Итог = Итог + Сумма;
КонецЕсли;

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

Перебор ячеек и работа с диапазонами

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

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

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

Для диапазонов доступны операции оформления: через область можно задать ЦветФона, Шрифт, Границы, ГоризонтальноеПоложение. Например, подсветка итоговой строки:

ОбластьИтог = ТабДок.Область(НомерСтрокиИтог, 1, НомерСтрокиИтог, 5);
ОбластьИтог.Шрифт = Новый Шрифт(,, Истина);
ОбластьИтог.ЦветФона = WebЦвета.СветлоСерый;

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

Обращение к ячейкам в макете до вывода

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

Макет = ПолучитьМакет("ПечатнаяФорма");
ОбластьСтрока = Макет.ПолучитьОбласть("Строка");
ОбластьСтрока.Параметры.Номенклатура = СтрокаТовара.Номенклатура;
ОбластьСтрока.Область(1, 4, 1, 4).Текст = "шт.";
ТабДок.Вывести(ОбластьСтрока);

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

Проверка результата и отладка

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

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

Для отладки полезно выводить фактические границы документа через ВысотаТаблицы и ШиринаТаблицы: если обращаетесь к строке 20, а высота таблицы 15, причина пустого результата очевидна. Учтите также, что объединённые ячейки доступны только по левому верхнему углу объединения — обращение к «внутренней» ячейке объединённого диапазона не даст ожидаемого результата.

Ограничения и риски

Табличный документ хранится целиком в памяти. При программном построении очень больших документов (десятки тысяч строк с оформлением) потребление памяти растёт заметно, а обращения к областям в цикле замедляют формирование. Для массовых выгрузок без оформления часто рациональнее использовать построитель текстового или XML-вывода либо фоновое формирование.

Нумерация строк и колонок начинается с единицы. Обращение к нулевой строке вернёт пустую область. Формат адреса — только R1C1: привычная запись «B5» из Excel не поддерживается и тоже приведёт к пустой области без сообщения об ошибке.

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