Список значений в 1С: как добавить элемент и работать с коллекцией

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

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

Что такое список значений и когда он нужен

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

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

Создание списка и базовое добавление элементов

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

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

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

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

Элемент = Список.Добавить(ДокСсылка);
Элемент.Представление = "Реализация № " + ДокСсылка.Номер;
Элемент.Пометка = Истина;

1. 1
   Создайте объект: Список = Новый СписокЗначений
2. 2
   Добавьте элементы методом Добавить с нужными параметрами
3. 3
   При необходимости задайте представление и пометку через возвращаемый элемент
4. 4
   Проверьте результат: Список.Количество() и перебор циклом Для Каждого

Массовое наполнение: массив, запрос, таблица значений

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

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

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

Из результата запроса список наполняется перебором выборки. Это стандартный приём для списков ссылок:

Запрос = Новый Запрос("ВЫБРАТЬ Ссылка, Наименование ИЗ Справочник.Номенклатура");
Выборка = Запрос.Выполнить().Выбрать();
Пока Выборка.Следующий() Цикл
Список.Добавить(Выборка.Ссылка, Выборка.Наименование);
КонецЦикла;

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

Метод Вставить(Индекс, Значение, ...) добавляет элемент не в конец, а в указанную позицию, сдвигая остальные. Индексация начинается с нуля. Это полезно, когда первым элементом должен идти служебный пункт вроде «Все» или «Не выбрано»:

Список.Вставить(0, "Все", "<Все склады>");

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

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

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

Поиск выполняется с учётом типа: строка «123» и число 123 — разные значения, и НайтиПоЗначению их не отождествит. Если список наполняется из разных источников, приводите значения к одному типу перед проверкой, иначе получите визуально одинаковые, но логически разные дубли.

Работа со списком на форме и диалоги выбора

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

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

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

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

Сортировка, проверка и отладка результата

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

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

Если Список.Количество() = 0 Тогда
Сообщить("По заданным условиям данные не найдены");
Возврат;
КонецЕсли;

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

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

Количество элементов

Норма

Список.Количество() совпадает с числом строк источника

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

Список пуст или элементов меньше, чем строк в выборке

Отображение в диалоге

Норма

Каждый элемент показывает понятное представление

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

Пустые строки или технические коды вместо текста

Уникальность

Норма

НайтиПоЗначению находит каждое значение один раз

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

Визуальные дубли из-за разных типов значений

Список значений против массива и соответствия

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

Сравнение вариантов

Список значений

Подходит для диалогов выбора и отметки, параметров отчётов, списков выбора полей. Избыточен для внутренних расчётов на больших объёмах

Массив

Быстрее и легче, подходит для передачи данных между процедурами. Нет представлений, пометок и стандартных диалогов

Соответствие

Мгновенный поиск по ключу, удобно для проверки уникальности. Нет упорядоченности и индексного доступа

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

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

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

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

Почему НайтиПоЗначению не находит добавленный элемент?

Чаще всего различаются типы: добавлено число, а ищется строка, или сравниваются ссылки из разных видов справочников. Проверьте тип искомого значения через ТипЗнч() и приведите его к типу элементов списка перед поиском.

Как добавить элемент в начало списка, а не в конец?

Используйте метод Вставить с индексом 0: Список.Вставить(0, Значение, Представление). Все существующие элементы сдвинутся на одну позицию вниз, порядок остальных сохранится.

Можно ли добавить в список значений другой список?

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

Как заполнить список значений из параметра отчёта на СКД?

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

Чем отличается Добавить на сервере и на клиенте?

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