Как обратиться к ячейке макета в 1С

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

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

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

Как устроен макет и что такое область

Макет табличного документа состоит из ячеек, каждая из которых может содержать текст, параметр или шаблон. Ячейка с типом «Параметр» заполняется программно по имени, ячейка с типом «Шаблон» содержит текст с вставками параметров в квадратных скобках, а обычный текст выводится как есть.

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

Получение области и заполнение параметров

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

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

Если в ячейке задан шаблон вида «Организация: [Организация]», параметр заполняется так же — по имени внутри квадратных скобок. Метод УстановитьПараметр("Организация", Значение) делает то же самое, но удобен, когда имя параметра хранится в переменной.

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

Прямое обращение к ячейке по координатам

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

// По строковому адресу
Ячейка = ТабДок.Область("R5C3");
Ячейка.Текст = "Новое значение";

// По числовым координатам (строка, колонка)
Ячейка = ТабДок.Область(5, 3);
Значение = Ячейка.Текст;

// Прямоугольный диапазон
Диапазон = ТабДок.Область(2, 1, 10, 4);

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

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

Поиск значения в табличном документе

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

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

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

1. 1
   Откройте макет в конфигураторе и задайте имена областям и параметрам ячеек
2. 2
   В коде получите макет методом ПолучитьМакет() и извлеките область через ПолучитьОбласть()
3. 3
   Заполните параметры через Область.Параметры.ИмяПараметра или УстановитьПараметр()
4. 4
   Выведите область методом ТабДок.Вывести() или присоедините методом Присоединить()
5. 5
   При необходимости скорректируйте отдельные ячейки через ТабДок.Область(строка, колонка)
6. 6
   Проверьте результат, открыв табличный документ на предпросмотр

Типичные ошибки при обращении к ячейкам

Наиболее частая проблема — обращение к несуществующей области или параметру. Вызов ПолучитьОбласть("Сторка1") с опечаткой вызовет исключение, а вот опечатка в имени параметра часто проходит молча: ячейка просто останется пустой, и ошибку заметят только на печатной форме.

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

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

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

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

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

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

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

Значение параметра на форме

Норма

Ячейка содержит ожидаемое значение в нужном формате

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

Ячейка пуста или содержит имя параметра в квадратных скобках

Координаты области

Норма

Верх и Лево соответствуют ожидаемой позиции в документе

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

Область = Неопределено или координаты указывают на другой фрагмент

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

Норма

ВысотаТаблицы соответствует числу выведенных строк

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

Высота меньше ожидаемой — часть областей не выведена

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

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

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

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

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

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

У области ячейки есть свойство Формат, которому присваивается строка формата, например ТабДок.Область(5, 3).Формат = "ЧДЦ=2". Альтернатива — задать формат заранее в свойствах ячейки макета, тогда он применится автоматически при выводе.

Можно ли прочитать значение из ячейки сформированного отчёта СКД?

Да, результат компоновки выводится в табличный документ, и дальше работают стандартные методы: НайтиТекст() для поиска и Область(строка, колонка) для чтения свойства Текст. Учитывайте, что в ячейках могут быть расшифровки — само значение расшифровки хранится отдельно в свойстве Расшифровка.

Что вернёт ТабДок.Область(), если координаты выходят за пределы документа?

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