Как обратиться к перечислениям в 1С: синтаксис, примеры и нюансы

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

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

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

Базовый синтаксис обращения к значению перечисления

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

// Получение значения перечисления
СтатусЗаказа = Перечисления.СтатусыЗаказов.ВРаботе;

// Сравнение реквизита объекта со значением перечисления
Если Документ.Статус = Перечисления.СтатусыЗаказов.Завершен Тогда
// логика обработки
КонецЕсли;

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

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

Перебор всех значений перечисления

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

Перебор через метаданные

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

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

Получение значения по имени через менеджер

Если имя значения хранится в переменной (например, пришло из файла обмена или настройки), используйте прямое обращение через квадратные скобки:

ИмяЗначения = "ВРаботе";
СсылкаНаЗначение = Перечисления.СтатусыЗаказов[ИмяЗначения];
Если СсылкаНаЗначение = Неопределено Тогда
// значение с таким именем не найдено
КонецЕсли;

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

Обращение к перечислению в запросах

В языке запросов 1С синтаксис отличается: здесь нет менеджеров, поэтому значение перечисления указывают через функцию ЗНАЧЕНИЕ():

ВЫБРАТЬ
Заказы.Номер,
Заказы.Статус
ИЗ
Документ.ЗаказПокупателя КАК Заказы
ГДЕ
Заказы.Статус = ЗНАЧЕНИЕ(Перечисление.СтатусыЗаказов.ВРаботе)

Обратите внимание: внутри ЗНАЧЕНИЕ() используется единственное число — Перечисление, а не Перечисления. Это частая причина ошибок при написании запросов.

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

Запрос.УстановитьПараметр("НужныйСтатус", Перечисления.СтатусыЗаказов.ВРаботе);

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

Запрос = Новый Запрос;
Запрос.Текст = "ВЫБРАТЬ Т.Ссылка ИЗ Документ.ЗаказПокупателя КАК Т ГДЕ Т.Статус = &Статус";
Запрос.УстановитьПараметр("Статус", Перечисления.СтатусыЗаказов.ВРаботе);
Результат = Запрос.Выполнить().Выгрузить();

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

В управляемых формах (тонкий и веб-клиент) действуют ограничения: на клиенте доступны не все серверные объекты. Однако обращение к значениям перечислений вида Перечисления.Имя.Значение работает и на клиенте, если модуль имеет соответствующие директивы компиляции.

Для директивы &НаКлиенте обращение к перечислениям допустимо — платформа сериализует значение и передаёт его между клиентом и сервером. Но перебор через метаданные на клиенте недоступен: вынесите такую логику в серверную процедуру или заранее подготовьте список значений при создании формы.

Заполнение списка выбора на форме

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

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

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

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

// Способ 1: сравнение с пустой ссылкой
Если Документ.Статус = Перечисления.СтатусыЗаказов.ПустаяСсылка() Тогда
// статус не заполнен
КонецЕсли;

// Способ 2: функция ЗначениеЗаполнено
Если Не ЗначениеЗаполнено(Документ.Статус) Тогда
// статус не заполнен
КонецЕсли;

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

В запросах пустая ссылка проверяется через то же ЗНАЧЕНИЕ() без указания конкретного значения — ЗНАЧЕНИЕ(Перечисление.СтатусыЗаказов.ПустаяСсылка) — или через условие на неопределённое значение в зависимости от состава типа поля.

Получение представления и порядкового номера значения

Иногда требуется получить строковое представление значения для вывода пользователю или записи в журнал. Функция Строка() или неявное преобразование вернут синоним значения:

ПредставлениеСтатуса = Строка(Перечисления.СтатусыЗаказов.ВРаботе); // вернёт синоним

Если нужно именно имя значения, как оно задано в конфигураторе (например, для обмена данными), получите его через метаданные:

ИмяЗначения = Документ.Статус.Метаданные().ЗначенияПеречисления[
Перечисления.СтатусыЗаказов.Индекс(Документ.Статус)].Имя;

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

Типичные ошибки и их диагностика

Наиболее распространённая ошибка — «Поле объекта не обнаружено» при обращении к значению перечисления. Причины: опечатка в имени значения, значение удалено или переименовано при обновлении конфигурации, либо обращение идёт к другому перечислению с похожим именем.

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

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

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