1С БСП: таблицу значений в массив структур и обратно

ОбщегоНазначения.ТаблицаЗначенийВМассив: таблицу значений в массив структур

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

// Сервер
ТаблицаОстатков = ЗапросОстатков.Выполнить().Выгрузить();

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

// МассивСтруктур[0].Номенклатура, МассивСтруктур[0].Количество, ...
Для Каждого Строка Из МассивСтруктур Цикл
    Сообщить(Строка.Номенклатура + ": " + Строка.Количество);
КонецЦикла;

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

Как формируются ключи структур и что происходит с типами колонок

Реализация в БСП предельно простая, и её полезно знать, потому что из неё следуют все ограничения. Функция сначала собирает имена колонок в одну строку через запятую, а затем на каждую строку таблицы создаёт структуру этим конструктором и переносит значения:

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

Отсюда четыре следствия, которые и порождают большинство вопросов:

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

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

Одна строка таблицы значений в структуру

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

СтрокаТаблицы = ТаблицаОстатков[0];

СтруктураСтроки = ОбщегоНазначения.СтрокаТаблицыЗначенийВСтруктуру(СтрокаТаблицы);

// Дальше структуру удобно передать в параметры формы или в общий метод
ОткрытьФорму("Обработка.Резервирование.Форма.Форма", СтруктураСтроки);

Разница с ТаблицаЗначенийВМассив только в объёме: набор ключей идентичен, состав колонок берётся из СтрокаТаблицыЗначений.Владелец().Колонки. Для отбора части колонок ни та, ни другая функция не годится — сначала сделайте Скопировать() таблицы с нужным списком колонок, потом преобразуйте.

1С массив в таблицу значений БСП: что реально есть в библиотеке

Запрос «1с массив в таблицу значений бсп» подразумевает симметричную функцию, но её в библиотеке нет. В ОбщегоНазначения и ОбщегоНазначенияКлиентСервер отсутствует МассивВТаблицуЗначений — искать её бесполезно. Библиотека закрывает обратное направление двумя процедурами общего модуля ОбщегоНазначенияКлиентСервер:

• ДополнитьТаблицуИзМассива(Таблица, Массив, ИмяПоля) — строка 588: массив простых значений в одну указанную колонку.
• ДополнитьТаблицу(ТаблицаИсточник, ТаблицаПриемник) — строка 571: построчное копирование из одной табличной коллекции в другую.

Если в вашей конфигурации функция МассивВТаблицуЗначений всё-таки вызывается — она принадлежит модулю самой конфигурации, а не БСП. В «Управлении торговлей», например, такой метод объявлен в ОбщегоНазначенияУТ, и при переносе кода в другую конфигурацию он не найдётся. Опираться на него как на библиотечный API нельзя.

ДополнитьТаблицуИзМассива: массив значений в одну колонку

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

МассивНоменклатуры = ОтобранныеТовары; // Массив из СправочникСсылка.Номенклатура

ТаблицаОтбора = Новый ТаблицаЗначений;
ТаблицаОтбора.Колонки.Добавить("Номенклатура",
    Новый ОписаниеТипов("СправочникСсылка.Номенклатура"));
ТаблицаОтбора.Колонки.Добавить("Количество", Новый ОписаниеТипов("Число"));

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

// Тело процедуры: Таблица.Добавить()[ИмяПоля] = Значение;

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

ДополнитьТаблицу: копирование строк между таблицами

Вторая процедура решает соседнюю задачу — слить две табличные коллекции. Работает не только с ТаблицаЗначений, но и с ТабличнаяЧасть, ДеревоЗначений и ДанныеФормыКоллекция, поэтому её удобно вызывать при переносе данных формы в объект.

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

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

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

1С массив структур в таблицу значений БСП: рабочий конвертер

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

// Сервер. Массив структур -> таблица значений с типизированными колонками
Функция ТаблицаИзМассиваСтруктур(МассивСтруктур)

    Таблица = Новый ТаблицаЗначений;
    Если МассивСтруктур.Количество() = 0 Тогда
        Возврат Таблица;
    КонецЕсли;

    // Колонки объявляем явно: типы в массиве структур не хранятся
    Таблица.Колонки.Добавить("Номенклатура",
        Новый ОписаниеТипов("СправочникСсылка.Номенклатура"));
    Таблица.Колонки.Добавить("Количество",
        Новый ОписаниеТипов("Число", Новый КвалификаторыЧисла(15, 3)));

    Для Каждого ЭлементМассива Из МассивСтруктур Цикл
        ЗаполнитьЗначенияСвойств(Таблица.Добавить(), ЭлементМассива);
    КонецЦикла;

    Возврат Таблица;

КонецФункции

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

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

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

&НаСервереБезКонтекста
Функция ОстаткиНаСервере(Склад)
    Возврат ОбщегоНазначения.ТаблицаЗначенийВМассив(
        РасчетОстатков.ТаблицаОстатков(Склад));
КонецФункции

&НаКлиенте
Процедура ОбновитьОстатки(Команда)

    Объект.Остатки.Очистить();
    Для Каждого ЭлементМассива Из ОстаткиНаСервере(Склад) Цикл
        ЗаполнитьЗначенияСвойств(Объект.Остатки.Добавить(), ЭлементМассива);
    КонецЦикла;

КонецПроцедуры

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

Возврат таблицы значений из фонового задания и сериализация

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

• Массив структур через временное хранилище. Фоновое задание кладёт результат ТаблицаЗначенийВМассив() в адрес, полученный из ДлительныеОперации.ПараметрыВыполненияВФоне(), клиент забирает готовую коллекцию и наполняет таблицу формы. Описание типов колонок при этом теряется.
• XML-сериализация целиком. ОбщегоНазначения.ЗначениеВСтрокуXML(Значение) (строка 5499) и парная ОбщегоНазначения.ЗначениеИзСтрокиXML(СтрокаXML) (строка 5517) сохраняют таблицу вместе с колонками и их типами. Это правильный путь, когда таблица нужна обратно на сервере в исходном виде — например, при сохранении промежуточного результата в реквизит типа «Строка неограниченной длины».

// Сервер: сохранение таблицы без потери типов колонок
СтрокаXML = ОбщегоНазначения.ЗначениеВСтрокуXML(ТаблицаОстатков);

// ... позже, в другом сеансе или задании
ВосстановленнаяТаблица = ОбщегоНазначения.ЗначениеИзСтрокиXML(СтрокаXML);

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

Частые ошибки при преобразовании таблицы значений в массив

• Поиск функции МассивВТаблицуЗначений в БСП. В ОбщегоНазначения и ОбщегоНазначенияКлиентСервер её нет. Одноимённый метод в конфигурации (например, в ОбщегоНазначенияУТ) при переносе кода в другую базу не найдётся.
• Вызов ТаблицаЗначенийВМассив() на клиенте. Модуль ОбщегоНазначения серверный. Преобразование выполняют на сервере, а на клиент отдают уже готовый массив.
• Имя колонки — не идентификатор. Пробел, точка или ведущая цифра в имени колонки ломают конструктор Новый Структура() внутри функции. Переименуйте колонки до преобразования.
• Ожидание, что типы колонок «доедут» вместе с данными. Массив структур хранит только значения. Для обратного преобразования колонки объявляют заново с явным ОписаниеТипов, иначе таблица уйдёт с нетипизированными колонками.
• Массив структур в ДополнитьТаблицуИзМассива(). Процедура пишет элемент массива целиком в одну колонку: Таблица.Добавить()[ИмяПоля] = Значение. Для массива структур нужен цикл с ЗаполнитьЗначенияСвойств().
• Приёмник не очищен перед ДополнитьТаблицу(). Обе процедуры именно дополняют, а не замещают. Повторный вызов даёт дубли строк.
• Расхождение имён колонок и ключей структур. Сопоставление идёт через ЗаполнитьЗначенияСвойств() по точному совпадению имени. Лишние свойства структуры игнорируются, непарные колонки остаются пустыми — ошибки не будет, будут пустые данные.
• Преобразование таблицы на десятки тысяч строк. Библиотека прямо не рекомендует такой сценарий: на каждую строку создаётся структура. Для больших объёмов передавайте данные через временное хранилище или сокращайте выборку до нужных колонок.

Частые вопросы о преобразовании таблицы значений в БСП