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

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

Начинающие разработчики часто путают список значений с массивом или таблицей значений и пытаются обратиться к нему неподходящими методами. В результате возникает ошибка «Метод объекта не обнаружен» или данные добавляются, но не отображаются на форме. Ниже разобраны рабочие варианты кода, нюансы работы с формой и типичные ошибки.

Что такое список значений и где он встречается

Список значений (тип «СписокЗначений») — объект встроенного языка 1С, каждая строка которого содержит четыре свойства: Значение, Представление, Пометка (булево) и Картинка. Значение может быть любого типа: строка, число, ссылка на справочник или документ, дата.

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

Программное добавление строки методом Добавить()

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

Список = Новый СписокЗначений;
Список.Добавить("Москва");
Список.Добавить("СПб", "Санкт-Петербург");
Список.Добавить(Справочники.Контрагенты.НайтиПоКоду("000001"), "Основной контрагент", Истина);

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

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

НоваяСтрока = Список.Добавить(ТекущаяДатаСеанса(), "Дата отгрузки");
НоваяСтрока.Картинка = БиблиотекаКартинок.Календарь;

Список = Новый СписокЗначений;
Элемент = Список.Добавить(Значение, "Представление", Истина);
Элемент.Картинка = БиблиотекаКартинок.Информация;

Вставка строки в нужную позицию

Метод Добавить() всегда помещает строку в конец списка. Если требуется вставить элемент в середину или в начало, используют метод Вставить() с указанием индекса позиции. Индексация начинается с нуля, поэтому вставка в позицию 0 поместит строку первой.

Список.Вставить(0, "Срочно", "Приоритетная задача");

Если указать индекс больше текущего количества элементов, платформа выдаст ошибку «Неверное значение индекса». Перед вставкой в произвольную позицию проверяйте размер списка через Количество(). Для перестановки уже существующих строк есть метод Сдвинуть(), а для замены значения — прямое обращение к элементу по индексу.

Добавление строки в список на форме

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

Программно строка в реквизит формы добавляется тем же методом Добавить() — обращение идёт к реквизиту по имени:

&НаКлиенте
Процедура ДобавитьСтроку(Команда)
СписокДокументов.Добавить(ТекущийДокумент, Строка(ТекущийДокумент));
КонецПроцедуры

Отображение на форме обновляется автоматически, отдельный вызов обновления не нужен. Частая ситуация: разработчик создаёт локальную переменную Новый СписокЗначений внутри процедуры, добавляет в неё строки — и удивляется, что на форме ничего не появилось. Локальная переменная и реквизит формы — разные объекты; чтобы данные попали на форму, работать нужно именно с реквизитом или присвоить ему готовый список целиком.

1. 1
   Создайте объект: Список = Новый СписокЗначений — или используйте существующий реквизит формы
2. 2
   Вызовите Список.Добавить(Значение, Представление, Пометка) с нужными параметрами
3. 3
   При необходимости вставки в середину используйте Список.Вставить(Индекс, Значение)
4. 4
   Проверьте результат: Список.Количество() должно увеличиться, значение доступно по индексу
5. 5
   Если список на форме — убедитесь, что добавляете в реквизит формы, а не в локальную переменную

Добавление нескольких строк и загрузка готового набора

Если строк много, их добавляют в цикле. Например, заполнение списка из выборки запроса или массива:

Для Каждого СтрокаВыборки Из Выборка Цикл
Список.Добавить(СтрокаВыборки.Ссылка, СтрокаВыборки.Наименование);
КонецЦикла;

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

МассивКонтрагентов = Новый Массив;
МассивКонтрагентов.Добавить(Контрагент1);
МассивКонтрагентов.Добавить(Контрагент2);
Список.ЗагрузитьЗначения(МассивКонтрагентов);

Учтите: ЗагрузитьЗначения() полностью очищает список перед загрузкой. Если нужно дополнить существующие строки, используйте цикл с Добавить(), а не загрузку.

Проверка дублей и поиск перед добавлением

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

Если Список.НайтиПоЗначению(НовыйКонтрагент) = Неопределено Тогда
Список.Добавить(НовыйКонтрагент);
КонецЕсли;

Метод возвращает найденный элемент списка или Неопределено, если значения нет. Сравнение идёт по значению, а не по представлению: две строки с одинаковым представлением, но разными ссылками считаются разными элементами. Для ссылочных типов сравнение выполняется по ссылке, что обычно и требуется в учётных задачах.

Типичные ошибки и ограничения

Самая частая ошибка — перепутанный порядок параметров. Разработчик пишет Список.Добавить("Представление", Значение), и в значение строки попадает строка-представление, а само значение уходит в представление. Запомните порядок: сначала значение, затем представление, затем пометка.

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

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

Когда список значений — не лучший выбор

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

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