1С: как записать структуру и работать с ней

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

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

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

Что такое структура в языке 1С и когда её применять

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

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

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

Создание структуры через конструктор Новый Структура

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

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

// Обращение к значениям
СуммаДокумента = ПараметрыОтбора.Сумма;

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

Настройки = Новый Структура("ВыводитьИтоги, ФорматДаты, ИмяФайла");
Настройки.ВыводитьИтоги = Истина;
Настройки.ФорматДаты = "ДФ=dd.MM.yyyy";
Настройки.ИмяФайла = "Отчет.xml";

Допустимо создать пустую структуру без параметров — Новый Структура — и наполнять её методом Вставить. Это удобно, когда набор ключей формируется динамически в цикле.

Добавление и изменение элементов методом Вставить

Метод Вставить добавляет новый ключ или перезаписывает существующий. Первый параметр — имя ключа строкой, второй — значение. Если ключ уже есть, значение просто заменяется, ошибки не возникает.

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

// Перезапись существующего ключа
Данные.Вставить("Сумма", 25700);

Метод Вставить — единственный способ добавить ключ, которого не было при создании структуры. Попытка присвоить значение несуществующему ключу через точку (Данные.НовыйКлюч = 1) приведёт к ошибке «Поле объекта не обнаружено».

Проверка наличия ключа перед чтением

Обращение к несуществующему ключу через точку вызывает исключение и останавливает выполнение кода. Чтобы избежать этого, используйте метод Свойство — он возвращает Истина, если ключ найден, и помещает значение в переменную, переданную вторым параметром.

ЗначениеСкидки = 0;
Если Параметры.Свойство("Скидка", ЗначениеСкидки) Тогда
ИтоговаяСумма = ИтоговаяСумма - ЗначениеСкидки;
КонецЕсли;

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

Обход структуры в цикле

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

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

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

Если Настройки.Количество() = 0 Тогда
ВызватьИсключение "Настройки не заполнены";
КонецЕсли;

Метод Очистить() удаляет все элементы структуры. После очистки структура остаётся валидным объектом — её можно снова наполнять через Вставить.

Вложенные структуры и сложные значения

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

ПараметрыОбмена = Новый Структура;
ПараметрыОбмена.Вставить("Узел", УзелСсылка);

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

ПараметрыОбмена.Вставить("Отбор", Отбор);

// Обращение к вложенному значению
ДатаНачала = ПараметрыОбмена.Отбор.ДатаНачала;

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

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

Передача структуры в процедуры и функции

Структура передаётся в процедуры и функции по ссылке: вызванный код работает с тем же объектом, а не с копией. Изменения, сделанные внутри процедуры, сохраняются после её завершения.

Процедура ЗаполнитьСуммы(Данные)
Данные.Вставить("СуммаНДС", Данные.Сумма * 20 / 120);
КонецПроцедуры;

Док = Новый Структура("Сумма", 12000);
ЗаполнитьСуммы(Док);
// Док.СуммаНДС теперь содержит рассчитанное значение

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

Функция СкопироватьСтруктуру(Источник)
Копия = Новый Структура;
Для Каждого Элемент Из Источник Цикл
Копия.Вставить(Элемент.Ключ, Элемент.Значение);
КонецЦикла;
Возврат Копия;
КонецФункции

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

1. 1
   Объявите структуру: Новый Структура("Ключ1, Ключ2")
2. 2
   Заполните значения через точку или методом Вставить
3. 3
   Проверяйте наличие ключей методом Свойство перед чтением
4. 4
   Передайте структуру в процедуру как обычный параметр
5. 5
   Проверьте результат: обратитесь к ключам и убедитесь, что значения на месте

Структура или соответствие: что выбрать

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

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

Структура

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

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

Подходит для динамических ключей любого типа, например поиска по ссылкам. Ограничение: обращение только через скобки, код менее нагляден.

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

Подходит для параметров, которые нельзя менять после создания, например параметров формы. Ограничение: значения только для чтения.

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

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

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

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

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

Для Каждого Элемент Из Параметры Цикл
Сообщить(СтрШаблон("%1: %2", Элемент.Ключ, Элемент.Значение));
КонецЦикла;

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

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

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

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

Норма

Совпадает с числом заданных ключей

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

Меньше ожидаемого — часть Вставить не выполнилась

Наличие обязательных ключей

Норма

Свойство("Ключ") возвращает Истина для каждого

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

Возвращает Ложь — ключ не создан или опечатка в имени

Типы значений

Норма

ТипЗнч соответствует ожидаемому типу

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

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

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

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

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

Чем структура отличается от фиксированной структуры?

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

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

Метод Удалить("ИмяКлюча") удаляет конкретный элемент. Если ключа нет, возникнет ошибка, поэтому перед удалением стоит проверить его наличие методом Свойство. Для удаления всех элементов используется метод Очистить.

Передаётся ли структура между клиентом и сервером?

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

Как узнать, пустая ли структура?

Вызовите метод Количество() — он возвращает число элементов. Если результат равен нулю, структура пустая. Отдельного метода «Пустая» у структуры нет.

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

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