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

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

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

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

Основы структуры ДереваЗначений

Прежде чем приступать к добавлению новых полей, важно понимать, из чего состоит этот объект. ДеревоЗначений — это коллекция строк, каждая из которых может иметь вложенные строки. Но сами строки не могут иметь произвольные поля. Все возможные поля (колонки) должны быть предварительно описаны в свойстве Колонки.

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

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

⚠️ Внимание: Изменение структуры колонок (добавление или удаление) возможно только до того, как вы начали массово заполнять строки данными, если вы планируете использовать эти изменения в существующем дереве. Хотя технически добавить колонку можно в любой момент, логика заполнения может нарушиться, если вы не учтете новую колонку в циклах записи.

Создание и настройка новой колонки

Для добавления колонки используется коллекция Колонки, доступная у объекта ДеревоЗначений. Метод Добавить() этой коллекции возвращает объект КолонкаДереваЗначений, свойства которого необходимо настроить.

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

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

Дерево = Новый ДеревоЗначений;
НоваяКолонка = Дерево.Колонки.Добавить("СуммаПродаж");
НоваяКолонка.ТипЗначения = Новый ОписаниеТипов("Число");
НоваяКолонка.Заголовок = "Сумма продаж, руб.";

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

Динамическое формирование колонок из массива

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

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

• 📌 Создайте массив с именами будущих колонок.
• 📌 В цикле вызывайте метод Добавить() для каждого имени.
• 📌 Сразу настраивайте ТипЗначения и Ширина для корректного отображения.

Первая добавленная колонка будет крайней левой.

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

Для Каждого Поле Из СписокПолей Цикл
Колонка = Дерево.Колонки.Добавить(Поле.Ключ);
Колонка.ТипЗначения = Поле.Значение;
Колонка.Заголовок = Поле.Ключ;
КонецЦикла;

Заполнение данных в новые колонки

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

Обращение к полям происходит как к обычным свойствам объекта. Синтаксис Строка.ИмяКолонки = Значение является стандартным. Если имя колонки содержит пробелы или спецсимволы (что не рекомендуется, но возможно), придется использовать квадратные скобки: Строка["Имя Колонки"].

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

Метод	Назначение	Возвращаемое значение
Колонки.Добавить()	Создание новой колонки в структуре	Объект КолонкаДереваЗначений
Строки.Добавить()	Создание новой строки данных	Объект СтрокаДереваЗначений
Строки.Создать()	Создание строки без добавления в дерево	Объект СтрокаДереваЗначений
Колонки.Получить()	Получение объекта колонки по имени	Объект КолонкаДереваЗначений

⚠️ Внимание: Если вы присваиваете значение типа, не совместимого с объявленным ТипЗначения колонки, 1С попытается выполнить конвертацию. Если конвертация невозможна (например, строка "Абв" в число), возникнет ошибка выполнения.

Работа с иерархией и вложенными колонками

Главное преимущество ДереваЗначений перед обычными таблицами — поддержка иерархии. Добавленные вами колонки автоматически становятся доступными на всех уровнях вложенности. Вам не нужно дублировать определение колонок для дочерних элементов.

Когда вы создаете дочернюю строку через метод Строки.Добавить(Родитель), она наследует всю структуру колонок родительского дерева. Это упрощает код: вы определяете поля один раз в корне, а заполнять можете любую ветку.

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

Особенности производительности при глубокой вложенности

При глубине вложенности более 100 уровней и большом количестве колонок (более 50) отрисовка дерева в форме может начать подтормаживать. В таких случаях рекомендуется использовать виртуальные таблицы или выгружать данные сразу в Табличный Документ, минуя вывод в форму.

Для проверки наличия вложенных элементов у строки используется свойство ЕстьДети или метод ПолучитьЭлементы(). Это позволяет формировать итоговые значения в колонках родительских строк, суммируя данные детей.

Для Каждого Строка Из Дерево.Строки Цикл
Если Строка.ЕстьДети Тогда
Сумма = 0;
Для Каждого Дочерний Из Строка.Строки Цикл
Сумма = Сумма + Дочерний.СуммаПродаж;
КонецЦикла;
Строка.СуммаПродаж = Сумма;
КонецЕсли;
КонецЦикла;

Вывод результатов в Табличный Документ

Конечной целью создания ДереваЗначений чаще всего является печать отчета или выгрузка в Excel. Для этого используется объект Табличный Документ. Метод Заполнить() позволяет перенести все данные и структуру колонок одной командой.

При выводе важно настроить заголовки. Если вы задали свойство Заголовок у колонки дерева, оно автоматически попадет в шапку табличного документа. Если нет — будет использовано имя колонки, что может быть неудобно для пользователя (например, имя SummSales вместо "Сумма продаж").

Также можно управлять видимостью колонок. Если какая-то служебная колонка нужна для расчетов, но не должна выводиться в отчет, её можно исключить при заполнении, передав список видимых колонок вторым параметром в метод Заполнить.

• 🖨️ Создайте объект ТабличныйДокумент.
• 🖨️ Вызовите метод Заполнить(ДеревоЗначений).
• 🖨️ Примените автоширину колонок для читаемости.
• 🖨️ Выведите документ на экран или отправьте на печать.

⚠️ Внимание: Интерфейс и возможности объекта Табличный Документ могут незначительно отличаться в зависимости от версии платформы 1С и режима совместимости. Если вы разрабатываете конфигурацию для широкого круга версий, проверяйте документацию по конкретному релизу.

Часто встречающиеся ошибки и решения

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

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

Также стоит упомянуть проблему с кодировкой и спецсимволами при выгрузке в внешние файлы. Если в заголовках колонок используются символы, не поддерживаемые кодировкой файла (например, CSV), данные могут исказиться. Рекомендуется использовать UTF-8 или выгрузку через COM-объект Excel для сложных отчетов.

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

Нет, свойство ТипЗначения у объекта КолонкаДереваЗначений доступно только для чтения после создания. Чтобы изменить тип, нужно удалить колонку (если это поддерживается версией) и добавить её заново, либо создать новое ДеревоЗначений.

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

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

Влияет ли количество колонок на скорость работы отчета?

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

Можно ли использовать колонки для сортировки дерева?

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

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

Свойства доступности редактирования настраиваются не в самом ДеревеЗначений, а в элементах формы (Табличное поле), которое отображает это дерево. В свойствах колонки табличного поля на форме нужно снять галочку "Редактирование" или использовать СКД.