Как правильно настроить команду управляемой формы 1С для загрузки данных из Excel?

При разработке внешних обработок и форм в 1С:Предприятие 8.3 (особенно в управляемом приложении) разработчики часто сталкиваются с ошибками при попытке привязать команду формы напрямую к серверной процедуре. Выясним причину такого поведения платформы и разберем по шагам правильную архитектуру взаимодействия клиентской и серверной частей при чтении файлов Excel.

Ограничение платформы 1С по директивам компиляции

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

Кнопка на форме нажата пользователем на его компьютере (на клиенте). Поэтому точка входа всегда должна располагаться на клиенте. Если вся бизнес-логика и обработка данных должна выполняться на стороне сервера, клиентская процедура выступает в роли обертки: она принимает действия пользователя и затем вызывает отдельную серверную процедуру (с директивой &НаСервере или &НаСервереБезКонтекста).

Схема передачи файла Excel с клиента на сервер

Проанализируем ситуацию: файл `.xlsx` находится на локальном компьютере пользователя (на клиенте), а создание документов или элементов справочника происходит на сервере 1С. Сервер не имеет прямого доступа к файловой системе клиентского компьютера. Чтобы сервер смог прочитать файл Excel, необходимо передать данные через временное хранилище.

Рассмотрим классический алгоритм передачи файла:

1. На клиенте: запрашиваем у пользователя файл с помощью диалога выбора файлов или асинхронной функции.
2. На клиенте: считываем выбранный файл в двоичные данные и помещаем его во временное хранилище платформы.
3. На клиенте: получаем адрес временного хранилища (строка вида e1cib/tempstorage/...) и передаем его параметром в серверную процедуру.
4. На сервере: извлекаем двоичные данные из временного хранилища по полученному адресу, сохраняем их во временный файл на сервере (через ПолучитьИмяВременногоФайла()).
5. На сервере: считываем данные из временного файла Excel, создаем или обновляем объекты информационной базы.
6. На сервере: удаляем временный файл и возвращаем клиенту результат выполнения операции.

Пример программного кода

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

&НаКлиенте
Процедура ЗагрузитьФайлКоманда(Команда)

    // Настраиваем обработчик завершения выбора и помещаем файл во временное хранилище
    ОписаниеОповещения = Новый ОписаниеОповещения("ЗагрузитьФайлЗавершение", ЭтотОбъект);
    НачатьПомещениеФайлаНаСервер(ОписаниеОповещения, , , Новый УточнениеИспользованияДиалогаПеремещенияФайлов, УникальныйИдентификатор);

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

&НаКлиенте
Процедура ЗагрузитьФайлЗавершение(ОписаниеПомещенногоФайла, ДополнительныеПараметры) Экспорт

    Если ОписаниеПомещенногоФайла = Неопределено Тогда
        Возврат; // Пользователь отменил выбор файла
    КонецЕсли;

    // Вызываем серверную процедуру, передавая адрес во временном хранилище
    ЗагрузитьИзExcelНаСервере(ОписаниеПомещенногоФайла.Адрес);
    
    ПоказатьОповещениеПользователю("Загрузка", , "Загрузка данных из Excel успешно завершена!");

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

Теперь разберем серверную часть обработки файла:

&НаСервере
Процедура ЗагрузитьИзExcelНаСервере(АдресХранилища)

    // Получаем двоичные данные из временного хранилища и сохраняем во временный файл сервера
    ДвоичныеДанные = ПолучитьИзВременногоХранилища(АдресХранилища);
    ИмяВременногоФайла = ПолучитьИмяВременногоФайла("xlsx");
    ДвоичныеДанные.Записать(ИмяВременногоФайла);

    // Считываем файл с помощью ТабличногоДокумента (не требует установки MS Excel)
    ТабДок = Новый ТабличныйДокумент;
    ТабДок.Прочитать(ИмяВременногоФайла, ТипФайлаТабличногоДокумента.XLSX);

    // Обходим строки табличного документа и обрабатываем данные
    Для НомерСтроки = 1 По ТабДок.ВысотаТаблицы Цикл
        // Логика поиска или создания элементов номенклатуры
    КонецЦикла;

    // Очищаем временный файл на сервере
    УдалитьФайлы(ИмяВременногоФайла);

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

Заполнение единиц измерения в конфигурации «Управление торговлей 11.2»

При загрузке номенклатуры часто возникает вопрос связывания создаваемого позиционирования с классификатором единиц измерения. Разберем особенности структуры данных в УТ 11.2:

1. Классификатор единиц измерения и упаковки содержатся в едином справочнике УпаковкиЕдиницыИзмерения.
2. Если у элемента реквизит Владелец не заполнен (содержит пустую ссылку), то данный элемент является базовой единицей измерения из ОКЕИ (например, «шт», «кг»).
3. Если реквизит Владелец заполнен (указывает на конкретный элемент справочника Номенклатура или набор упаковок), элемент считается индивидуальной упаковкой.

При загрузке номенклатуры из Excel алгоритм поиска и привязки единицы измерения следующий: сначала выполняем поиск элемента в справочнике Справочники.УпаковкиЕдиницыИзмерения по коду ОКЕИ или наименованию с отбором по пустому владельцу. Найденая базовая единица присваивается реквизиту ЕдиницаИзмерения нового объекта справочника Номенклатура.