Как добавить значение в список значений 1С

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

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

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

Инициализация объекта и базовые настройки

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

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

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

СписокДанных = Новый СписокЗначений;
СписокДанных.ИспользоватьПометкиУдаления = Истина;
СписокДанных.Колонки.Добавить("Комментарий", ТипОписанияТипов("Строка(50)"));

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

Метод Добавит: синтаксис и параметры

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

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

Третий параметр — ПометкаУдаления. Он актуален только если свойство ИспользоватьПометкиУдаления у самого списка установлено в Истина. Четвертый параметр позволяет передать объект ДополнительныеЗначения, который представляет собой структуру с произвольными данными, привязанными к этому элементу.

• 📦 Значение — основное хранимое данные (любой тип).
• 🏷️ Представление — строка для отображения в списке выбора или поле ввода.
• 🗑️ ПометкаУдаления — булево значение, скрывающее элемент логически.
• 📝 ДополнительныеЗначения — структура с расширенной информацией.

Использование всех параметров сразу делает код компактным. Однако, если вам нужно добавить элемент с дефолтными настройками, достаточно передать только первое значение. Система сама подставит представление, равное строковому виду значения, и установит пометку удаления в Ложь.

ЭлементСписка = СписокДанных.Добавить(Справочники.Номенклатура.НайтиПоНаименованию("Стол"), "Офисный стол", Ложь);

Добавление элементов с дополнительными реквизитами

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

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

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

Параметр	Тип данных	Описание назначения
Значение	Любой	Основной объект (Ссылка, Число, Строка)
Представление	Строка	Текст для отображения в форме
Доп. значения	Структура	Контейнер для скрытых атрибутов (ИНН, Рейтинг)

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

ДопДанные = Новый Структура("ПланПродаж, Факт", 100000, 95000);
СписокДанных.Добавить(Сотрудник, Иванов И.И., Ложь, ДопДанные);

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

Как получить доступ к дополнительным значениям?

Для доступа используйте конструкцию: ЭлементСписка.ДополнительныеЗначения.ИмяКлюча. Убедитесь, что ключ существует, иначе получите ошибку выполнения.

Вставка элементов по индексу и перемещение

Иногда критически важно контролировать порядок следования элементов. Стандартный метод Добавить помещает новый элемент в конец коллекции. Если бизнес-логика требует вставить запись в середину списка или в самое начало, следует использовать метод Вставить.

Этот метод принимает два основных параметра: индекс позиции и само значение (а также опционально представление и остальные параметры, аналогично методу Добавить). Индексация в 1С начинается с нуля. Следовательно, вставка по индексу 0 поместит элемент в самое начало списка, сдвинув все остальные элементы вниз.

Также существует возможность перемещения уже существующих элементов внутри списка. Методы Сдвинуть и Переместить позволяют менять порядок без удаления и повторного создания объектов. Это особенно актуально в интерфейсах, где пользователь может сортировать список drag-and-drop или кнопками "Вверх/Вниз".

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

Если ИндексВставки <= СписокДанных.Количество Тогда
СписокДанных.Вставить(ИндексВставки, НовоеЗначение, "Описание");
КонецЕсли;

Массовое заполнение из других коллекций

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

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

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

• 🚀 ЗагрузитьЗначения — массовый импорт из ТаблицыЗначений.
• 🔄 ВыгрузитьЗначения — экспорт обратно в таблицу для обработки запросом.
• 🧹 Очистить — быстрое удаление всех элементов без уничтожения объекта.

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

ТаблицаДанных = ПолучитьТаблицуИзЗапроса();
СписокДанных.ЗагрузитьЗначения(ТаблицаДанных, "Ссылка", "Наименование", "ЭтоГруппа");

⚠️ Внимание: При загрузке из таблицы значений убедитесь, что типы данных в колонках таблицы совместимы с целевыми свойствами списка. Например, попытка записать строку в колонку, соответствующую свойству "ПометкаУдаления" (Булево), вызовет исключение.

Обработка ошибок и отладка списка

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

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

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

В случае сложных структур данных рекомендуется оборачивать операции добавления в конструкцию Попытка...Исключение. Это позволит корректно обработать ситуацию, если, например, объект метаданных был помечен на удаление в базе и не может быть использован в списке выбора.

Попытка
СписокДанных.Добавить(Значение);
Исключение
Сообщить("Ошибка добавления: " + ОписаниеОшибки());
КонецПопытки;

Можно ли изменить значение элемента после добавления?

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

В чем разница между СпискомЗначений и Массивом?

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

Как очистить список значений полностью?

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

Поддерживает ли список значений сортировку?

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