Структура в 1С: как добавить элементы и работать с ней

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

Запрос «1С структура как добавить» обычно означает одно из двух: как программно добавить новое поле в уже существующую структуру или как создать структуру с нужным набором элементов сразу. Ниже разобраны оба сценария, а также особенности, которые вызывают ошибки у начинающих разработчиков.

Материал ориентирован на работу во встроенном языке 1С:Предприятие 8.3 и подходит для управляемых и обычных форм, клиентского и серверного контекста.

Что такое Структура в 1С и когда её использовать

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

Типичные сценарии применения: передача множества параметров одной переменной, формирование данных для заполнения документа, возврат нескольких значений из функции, подготовка JSON-подобных данных для обмена. Структуры легковесны и не требуют предварительного описания типов.

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

Создание структуры сразу с элементами

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

Параметры = Новый Структура("Организация, Склад, ДатаОтгрузки",
ОрганизацияСсылка, СкладСсылка, ТекущаяДатаСеанса());

Если значения на момент создания неизвестны, вторую часть аргументов можно опустить — ключи будут созданы со значением Неопределено:

Результат = Новый Структура("Успех, СообщениеОбОшибке");

Такой приём удобен как «заготовка»: дальше значения заполняются по мере выполнения кода. Это делает код читаемым — сразу видно, какие поля ожидаются в структуре.

Как добавить элемент методом Вставить

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

Данные = Новый Структура;
Данные.Вставить("Номенклатура", НоменклатураСсылка);
Данные.Вставить("Количество", 10);
Данные.Вставить("Цена", 1500.50);

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

После добавления обращаться к элементу можно двумя способами: через точку (Данные.Количество) или через квадратные скобки (Данные["Количество"]). Второй вариант обязателен, когда имя ключа хранится в переменной:

ИмяПоля = "Цена";
Значение = Данные[ИмяПоля];

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

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

ЗначениеЦены = Неопределено;
Если Данные.Свойство("Цена", ЗначениеЦены) Тогда
// ключ есть, значение в переменной ЗначениеЦены
Иначе
// ключа нет — задаём поведение по умолчанию
КонецЕсли;

Метод возвращает Истина, если ключ найден, и помещает значение во второй параметр. Это основной приём защитного программирования при работе со структурами, полученными извне — из других модулей, обменов или параметров формы.

1. 1
   Создайте структуру через Новый Структура с перечнем известных ключей
2. 2
   Добавьте недостающие поля методом Вставить
3. 3
   Перед чтением проверяйте ключ методом Свойство
4. 4
   При перезаписи убедитесь, что имя ключа указано без опечаток
5. 5
   При передаче структуры между модулями зафиксируйте состав полей в комментарии

Вложенные структуры и обход элементов

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

Документ = Новый Структура;
Документ.Вставить("Шапка", Новый Структура("Номер, Дата", "0001", ТекущаяДатаСеанса()));
Документ.Вставить("Товары", Новый Массив);
Документ.Товары.Добавить(Новый Структура("Номенклатура, Количество", Ссылка, 5));

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

Для Каждого Элемент Из Данные Цикл
Сообщить(Элемент.Ключ + " = " + Строка(Элемент.Значение));
КонецЦикла;

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

Фиксированная структура и копирование

Разновидность объекта — ФиксированнаяСтруктура. Её состав ключей задаётся при создании и не может быть изменён: добавить или удалить поле невозможно, можно только менять значения существующих. Она применяется в платформенных механизмах (например, параметры сеанса, свойства форм) и в прикладном коде, когда состав данных должен быть гарантированно неизменным.

Обычную структуру можно превратить в фиксированную и обратно:

Фикс = Новый ФиксированнаяСтруктура(Данные);
Обычная = Новый Структура(Фикс);

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

Выбор коллекции под задачу

Структура

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

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

Ключ любого типа, включая ссылки. Нет доступа через точку, только через [].

ФиксированнаяСтруктура

Состав полей неизменен после создания. Подходит для защиты от случайных добавлений.

Массив

Доступ по индексу, порядок важен. Не подходит для именованных данных.

Типичные ошибки при добавлении в структуру

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

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

Третья группа — ожидание глубокого копирования. Присваивание переменной не создаёт независимую копию, и правки «копии» портят оригинал. Для вложенных структур это проявляется ещё и при переносе элементов в цикле — копируются ссылки на вложенные объекты.

Проверка результата и отладка

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

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

ОбязательныеПоля = СтрРазделить("Организация,Склад,ДатаОтгрузки", ",");
Для Каждого ИмяПоля Из ОбязательныеПоля Цикл
Если Не Данные.Свойство(СокрЛП(ИмяПоля)) Тогда
ВызватьИсключение "В структуре данных отсутствует поле: " + ИмяПоля;
КонецЕсли;
КонецЦикла;

Такая явная валидация на входе процедуры экономит часы отладки: ошибка возникает в точке передачи данных, а не где-то глубоко в логике обработки.

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

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

Состав ключей в отладчике

Норма

Все ожидаемые поля присутствуют, лишних нет

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

Есть поля с похожими именами — признак опечатки

Значения после Вставить

Норма

Каждое поле содержит ожидаемый тип данных

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

Поле равно Неопределено там, где ожидалось значение

Чтение через Свойство

Норма

Метод возвращает Истина для всех обязательных полей

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

Возвращает Ложь — ключ не был добавлен ранее

Часто задаваемые вопросы

Чем Структура отличается от Соответствия в 1С?

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

Можно ли удалить элемент из структуры?

Да, методом Удалить("ИмяКлюча"). Если ключ отсутствует, ошибки не будет — метод просто ничего не сделает. У фиксированной структуры метод Удалить отсутствует: её состав менять нельзя.

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

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

Почему обращение через точку выдаёт ошибку, хотя ключ добавлен?

Чаще всего ключ содержит пробелы, дефисы или начинается с цифры — такие имена недопустимы для синтаксиса через точку. Используйте обращение через квадратные скобки: Структура["Ключ с пробелом"], либо переименуйте ключ в корректный идентификатор.

Сохраняется ли порядок добавления элементов?

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

Можно ли хранить в структуре ссылки на объекты базы?

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