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

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

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

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

Создание табличного документа и базовые операции

Объект создаётся конструктором Новый ТабличныйДокумент. Документ существует только в памяти: пока вы не показали его пользователю или не записали в файл, он нигде не хранится и не требует очистки в базе данных. Это удобно для промежуточных расчётов и формирования файлов «на лету».

Минимальный пример создания и заполнения одной ячейки:

ТабДок = Новый ТабличныйДокумент;
ТабДок.Область(1, 1).Текст = "Номенклатура";
ТабДок.Область(1, 2).Текст = "Цена";
ТабДок.Область(2, 1).Текст = "Кабель ВВГ 3х2.5";
ТабДок.Область(2, 2).Значение = 145.50;
ТабДок.Показать("Прайс-лист");

Метод Область(НомерСтроки, НомерКолонки) возвращает область ячеек, через которую доступны свойства Текст, Значение, ЦветФона, Шрифт и другие. Различие важно: Текст хранит строковое представление, а Значение — типизированное значение (число, дату). Для последующей выгрузки в Excel корректнее заполнять Значение, иначе числа станут текстом.

Заполнение табличного документа по макету

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

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

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

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

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

1. 1
   Создайте макет с именованными областями и параметрами в конфигураторе
2. 2
   Получите макет методом ПолучитьМакет() и создайте Новый ТабличныйДокумент
3. 3
   Получите каждую область через ПолучитьОбласть() и заполните параметры
4. 4
   Выведите области методом Вывести() в нужном порядке
5. 5
   Покажите результат методом Показать() или запишите в файл через Записать()

Чтение данных из табличного документа

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

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

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

Сохранение и выгрузка в файл

Метод Записать(ИмяФайла, ТипФайла) сохраняет табличный документ в файл. Тип файла задаётся перечислением ТипФайлаТабличногоДокумента: MXL, XLSX, XLS, PDF, HTML, ODS, TXT. Выбор формата зависит от потребителя: MXL — для обмена между базами 1С, XLSX — для пользователей Excel, PDF — для печати и отправки контрагентам.

ТабДок.Записать("C:\Выгрузка\отчет.xlsx",
ТипФайлаТабличногоДокумента.XLSX);

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

На сервере запись выполняется в файловую систему сервера, поэтому путь должен быть доступен серверному процессу. Для отдачи файла пользователю из клиент-серверной базы типовой приём — записать файл во временное хранилище и передать на клиента через ПоместитьВоВременноеХранилище() и ПолучитьФайл().

Выбор формата сохранения

MXL

Родной формат 1С, сохраняет всё форматирование; открывается только в 1С

XLSX

Для передачи пользователям Excel; часть оформления может отличаться от оригинала

PDF

Для печати и отправки контрагентам; данные нельзя редактировать

HTML

Для публикации и вставки в письма; формулы и структура теряются

Изменение уже выведенных областей

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

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

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

Маршрут решения

Как выбрать способ обработки

Документ формируется один раз по готовому шаблонуИспользуйте макет с областями и метод Вывести()

Структура документа заранее неизвестна или генерируется динамическиЗаполняйте ячейки напрямую через Область(строка, колонка)

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

Нужно изменить одно значение в готовом документеНайдите ячейку через НайтиТекст() и запишите новое значение

Работа в управляемых формах и тонком клиенте

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

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

Для вывода отдельного окна без формы используйте метод Показать() — он работает и в тонком, и в веб-клиенте. Метод Напечатать() отправляет документ на принтер без предпросмотра; используйте его только после явного действия пользователя, чтобы не расходовать бумагу на ошибочные печати.

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

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

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

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

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

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

ВысотаТаблицы после формирования

Норма

Больше нуля и соответствует числу строк данных плюс шапка и подвал

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

Равна 0 или сильно меньше ожидаемого — области не выведены

Числа в выгруженном Excel

Норма

Распознаются как числа, формулы суммы работают

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

Числа сохранены как текст — ячейки заполнялись через Текст

Итоги и шапка

Норма

Присутствуют один раз, значения параметров подставлены

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

Пустые параметры или дублирующиеся области

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

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

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

Как вывести табличный документ на печать без предпросмотра?

Используйте метод Напечатать() с параметром РежимИспользованияДиалогаПечати.БезДиалога. Убедитесь, что у пользователя настроен принтер по умолчанию, иначе печать завершится ошибкой. Для массовой печати документов предварительно проверьте, что каждый документ сформирован без ошибок.

Можно ли читать файлы Excel без установленного Excel на сервере?

Да. Метод Прочитать() табличного документа открывает файлы XLSX и XLS штатными средствами платформы, установка Microsoft Excel не требуется. Ограничение: файлы с макросами, защитой паролем или сложными формулами могут читаться с потерями, поэтому для загрузок лучше давать пользователям простой шаблон.

Почему в выгруженном Excel числа стали текстом?

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

Как защитить табличный документ от редактирования пользователем?

Установите свойство Защита в значение Истина — пользователь сможет просматривать и печатать документ, но не изменять ячейки. Дополнительно можно скрыть сетку и линейки через свойства отображения. Учтите, что это защита от случайного редактирования, а не криптографическая защита данных.

Что делать, если формирование большого документа занимает много времени?

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