Общее описание расширения "Excel"
Расширение Excel представляет собой универсальный механизм для загрузки данных из файлов Microsoft Excel в систему 1С. Это не просто обработка для импорта, а полноценный фреймворк, который позволяет разработчикам легко встраивать функцию загрузки данных из Excel в любые объекты конфигурации (обработки, документы и т.д.).
Основная идея расширения — предоставить гибкий и переиспользуемый инструмент, который можно настроить для загрузки различных данных без необходимости каждый раз писать код для чтения Excel-файла, сопоставления колонок и отображения пользовательского интерфейса.
Ключевые компоненты и их назначение
- Общий модуль экс_Клиент:
- Это клиентский программный интерфейс (API) расширения. Он содержит набор экспортных процедур и функций, которые позволяют разработчику описать структуру данных, ожидаемых из Excel-файла.
- С помощью функций СоздатьМассивСтруктур и ДобавитьСтруктуруКолонки можно определить, какие колонки должны быть в файле, их заголовки, типы данных и какие из них являются ключевыми.
- Также модуль позволяет определять дополнительные поля (ДопПоля), которые могут понадобиться для передачи в форму загрузки и обратно.
- Общая форма экс_ФормаПолученияДанных:
- Это главный пользовательский интерфейс расширения. Форма является универсальной и динамически настраивается на основе параметров, переданных при ее открытии.
- Функционал формы:
- Выбор Excel-файла (.xls, .xlsx).
- Предварительный просмотр содержимого выбранного листа.
- Выбор листа для загрузки.
- Указание диапазона строк для импорта ("Первая строка", "Последняя строка").
- Динамическое создание полей для сопоставления колонок. Разработчик определяет, какие данные нужны (например, "Код номенклатуры", "Количество"), а форма автоматически создает поля, где пользователь может указать номера соответствующих колонок в Excel-файле.
- Возможность добавления на форму дополнительных полей для ввода параметров загрузки.
- Сохранение настроек: форма автоматически сохраняет последние использованные настройки (путь к файлу, номера колонок) для каждого сценария загрузки, что очень удобно при повторных операциях.
- Обработка экс_ПримерЗагрузки:
- Это пример, демонстрирующий, как использовать фреймворк.
- В модуле формы этой обработки показано, как:
- С помощью общего модуля экс_Клиент описать необходимую структуру колонок (например, для загрузки контрагентов и счетов учета или для загрузки номенклатуры).
- Передать эту структуру в общую форму экс_ФормаПолученияДанных.
- Получить результат из общей формы (уже готовую таблицу данных).
- Реализовать функцию обратного вызова ОбработатьЗаполнениеТабличнойЧасти. Эта функция вызывается из общей формы после считывания данных, но до их возврата. В ней можно выполнить предварительную проверку и обработку данных (например, найти контрагента по коду и сообщить об ошибке, если он не найден).
- Обработать полученные данные и загрузить их в табличные части своей обработки.
Сценарий использования
- Разработчик создает свою обработку (или дорабатывает существующий объект).
- На форму обработки он добавляет кнопку, например, "Загрузить из Excel".
- В обработчике нажатия этой кнопки он с помощью функций модуля экс_Клиент описывает, какие данные ему нужны.
- Затем он открывает общую форму экс_ФормаПолученияДанных, передавая ей созданную структуру колонок и имя для сохранения настроек.
- Пользователь в открывшейся форме выбирает файл, сопоставляет колонки и нажимает "ОК".
- Обработка-владелец получает готовую таблицу значений с данными из файла и может дальше использовать их по своему усмотрению.
Заключение
Расширение Excel — это мощный и гибкий инструмент для разработчиков, который значительно упрощает и стандартизирует задачи по импорту данных из Excel. Оно позволяет сосредоточиться на бизнес-логике обработки данных, а не на рутинных операциях чтения файла и настройки интерфейса.
Пример кода из формы обработки загрузки из Excel. В форме пример загрузки в две разные табличные части. Определяется состав загружаемых колонок и способы распознавания.
// Процедура открывает форму загрузки данных из Excel для контрагентов и счетов учета.
// Настраивает колонки для загрузки контрагентов, счетов учета и дополнительных полей.
//
// Параметры:
// Команда - КомандаФормы - команда формы, вызвавшая процедуру
//
&НаКлиенте
Процедура Заполнить(Команда)
// Создание массива колонок для загрузки данных
// Колонка 1: Код контрагента (обязательное поле, приоритет 1)
МассивКолонок = экс_Клиент.СоздатьМассивСтруктур("КодКонтрагента", "Код Контрагента", "Контрагент Ссылка", Новый ОписаниеТипов("СправочникСсылка.Контрагенты"), 1);
// Колонка 2: Код счета учета (обязательное поле, приоритет 1)
экс_Клиент.ДобавитьСтруктуруКолонки(МассивКолонок, "КодСчетаУчета", "Код Счета учета", "Счет учета ссылка", Новый ОписаниеТипов("ПланСчетовСсылка.Хозрасчетный"),1);
// Добавление дополнительных полей (приоритет 2 - необязательные)
экс_Клиент.ДобавитьСтруктуруКолонки(МассивКолонок, "Поле1", "Поле 1",,, 2);
экс_Клиент.ДобавитьСтруктуруКолонки(МассивКолонок, "Поле2", "Поле 2",,, 2);
// Настройка дополнительных полей для формы загрузки
ДопПоля = Новый Массив;
ДопПоля.Добавить(экс_Клиент.ПолучитьСтруктуруДопПолейЗначения("Параметр1", "Параметр 1", Новый ОписаниеТипов("СправочникСсылка.Номенклатура")));
ДопПоля.Добавить(экс_Клиент.ПолучитьСтруктуруДопПолейЗначения("Параметр2", "Параметр 2", Новый ОписаниеТипов("Булево")));
// Формирование параметров для формы загрузки
Пар = экс_Клиент.ПолучитьСтруктуруПараметровЗначения(МассивКолонок, Истина, "Обработка_ЗагрузкаЗастрахованныхОС", ДопПоля);
// Открытие формы получения данных из Excel с оповещением о завершении
Оповещение = Новый ОписаниеОповещения("ПолучитьДанныеЭксельЗавершение", ЭтотОбъект, Пар);
ОткрытьФорму("ОбщаяФорма.экс_ФормаПолученияДанных", Пар, ЭтотОбъект,,,,Оповещение, РежимОткрытияОкнаФормы.БлокироватьОкноВладельца);
КонецПроцедуры
// Процедура открывает форму загрузки данных из Excel для номенклатуры и количества.
// Настраивает колонки для загрузки номенклатуры с количественными показателями.
//
// Параметры:
// Команда - КомандаФормы - команда формы, вызвавшая процедуру
//
&НаКлиенте
Процедура Заполнить2(Команда)
// Создание массива колонок для загрузки номенклатуры
МассивКолонок = экс_Клиент.СоздатьМассивСтруктур("КодНоменклатуры", "Код номенклатуры", "Номенклатура Ссылка", Новый ОписаниеТипов("СправочникСсылка.Номенклатура"));
экс_Клиент.ДобавитьСтруктуруКолонки(МассивКолонок, "Количество", "Количество", "Количество Число", Новый ОписаниеТипов("Число"));
// Настройка дополнительных полей для формы загрузки
ДопПоля = Новый Массив;
ДопПоля.Добавить(экс_Клиент.ПолучитьСтруктуруДопПолейЗначения("Параметр1", "Параметр 1", Новый ОписаниеТипов("Число")));
ДопПоля.Добавить(экс_Клиент.ПолучитьСтруктуруДопПолейЗначения("Параметр2", "Параметр 2", Новый ОписаниеТипов("Булево")));
// Формирование параметров для формы загрузки номенклатуры
Пар = экс_Клиент.ПолучитьСтруктуруПараметровЗначения(МассивКолонок, Истина, "Обработка_ЗагрузкаЗастрахованныхОС_ЗагрузкаНоменклатуры", ДопПоля);
// Открытие формы получения данных из Excel с оповещением о завершении
Оповещение = Новый ОписаниеОповещения("ПолучитьДанныеЭксельЗавершение", ЭтотОбъект, Пар);
ОткрытьФорму("ОбщаяФорма.экс_ФормаПолученияДанных", Пар, ЭтотОбъект,,,,Оповещение, РежимОткрытияОкнаФормы.БлокироватьОкноВладельца);
КонецПроцедуры
// Функция выполняет валидацию и обработку данных загруженных из Excel файла.
// Проверяет существование контрагентов, счетов учета или номенклатуры в базе данных.
// Формирует массив ошибок при обнаружении проблем с данными.
//
// Параметры:
// ДанныеОбработки - Структура - данные из формы загрузки, содержит:
// * ТаблицаФайла - АдресВременногоХранилища - адрес таблицы значений с данными из Excel
// * ИмяСохранения - Строка - идентификатор типа загрузки данных
//
// Возвращаемое значение:
// АдресВременногоХранилища - адрес структуры с результатами обработки:
// * ДанныеФайла - ТаблицаЗначений - обработанные данные с расчетными полями
// * МассивОшибок - Массив - массив текстов обнаруженных ошибок
//
Функция ОбработатьЗаполнениеТабличнойЧасти(ДанныеОбработки) Экспорт
Рез = Новый Структура;
МассивОшибок = Новый Массив;
// Проверка корректности переданных данных
Если Не ТипЗнч(ДанныеОбработки) = Тип("Структура") Тогда
Рез.Вставить("МассивОшибок", МассивОшибок);
Возврат Рез;
КонецЕсли;
// Получение данных из временного хранилища
ДанныеФайла = ПолучитьИзВременногоХранилища(ДанныеОбработки.ТаблицаФайла);
ЕстьОщибка = Ложь;
// Обработка данных для загрузки контрагентов и счетов учета
Если ДанныеОбработки.ИмяСохранения = "Обработка_ЗагрузкаЗастрахованныхОС" Тогда
Для каждого стр из ДанныеФайла Цикл
// Поиск контрагента по коду и проверка существования
КодКонтрагента = стр.КодКонтрагента;
стр.КодКонтрагента_Расчет = Справочники.Контрагенты.НайтиПоКоду(КодКонтрагента);
Если Не ЗначениеЗаполнено(стр.КодКонтрагента_Расчет) Тогда
ЕстьОщибка = Истина;
ТекстОшибки = "В строке файла " + стр.НомерСтроки + " не определено Контрагент с кодом " + КодКонтрагента;
МассивОшибок.Добавить(ТекстОшибки);
КонецЕсли;
// Поиск счета учета по коду и проверка существования
КодСчетаУчета = стр.КодСчетаУчета;
стр.КодСчетаУчета_Расчет = ПланыСчетов.Хозрасчетный.НайтиПоКоду(КодСчетаУчета);
Если Не ЗначениеЗаполнено(стр.КодСчетаУчета_Расчет) Тогда
ЕстьОщибка = Истина;
ТекстОшибки = "В строке файла " + стр.НомерСтроки + " не определен Счет учета с кодом " + КодСчетаУчета;
МассивОшибок.Добавить(ТекстОшибки);
КонецЕсли;
КонецЦикла;
Рез.Вставить("ДанныеФайла", ДанныеФайла);
Рез.Вставить("МассивОшибок", МассивОшибок);
// Обработка данных для загрузки номенклатуры
ИначеЕсли ДанныеОбработки.ИмяСохранения = "Обработка_ЗагрузкаЗастрахованныхОС_ЗагрузкаНоменклатуры" Тогда
Для каждого стр из ДанныеФайла Цикл
// Поиск номенклатуры по коду и проверка существования
стр.КодНоменклатуры_Расчет = Справочники.Номенклатура.НайтиПоКоду(стр.КодНоменклатуры);
Если Не ЗначениеЗаполнено(стр.КодНоменклатуры_Расчет) Тогда
ЕстьОщибка = Истина;
ТекстОшибки = "В строке файла " + стр.НомерСтроки + " не определена Номенклатура с кодом " + стр.КодНоменклатуры;
МассивОшибок.Добавить(ТекстОшибки);
КонецЕсли;
// Преобразование количества в числовое значение с проверкой корректности
Попытка
стр.Количество_Расчет = Число(стр.Количество);
Исключение
ЕстьОщибка = Истина;
ТекстОшибки = "В строке файла " + стр.НомерСтроки + " не определено Количество " + стр.Количество;
МассивОшибок.Добавить(ТекстОшибки);
КонецПопытки;
КонецЦикла;
Рез.Вставить("ДанныеФайла", ДанныеФайла);
Рез.Вставить("МассивОшибок", МассивОшибок);
КонецЕсли;
// Помещение результата во временное хранилище для передачи на клиент
Возврат ПоместитьВоВременноеХранилище(Рез, УникальныйИдентификатор);
КонецФункции
// Процедура-обработчик завершения выбора данных из Excel.
// Вызывается после закрытия формы загрузки данных и направляет данные
// в соответствующую процедуру обработки в зависимости от типа загрузки.
//
// Параметры:
// РезультатЗакрытия - Структура - данные, возвращенные формой загрузки, содержит:
// * ИмяСохранения - Строка - идентификатор типа загрузки данных
// * ТаблицаФайла - АдресВременногоХранилища - данные из Excel
// ДополнительныеПараметры - Произвольный - дополнительные параметры оповещения
//
&НаКлиенте
Процедура ПолучитьДанныеЭксельЗавершение(РезультатЗакрытия, ДополнительныеПараметры) Экспорт
// Определение типа загрузки и вызов соответствующей процедуры обработки
Если РезультатЗакрытия.ИмяСохранения = "Обработка_ЗагрузкаЗастрахованныхОС" Тогда
ОбработатьДанныеЭксель(РезультатЗакрытия);
ИначеЕсли РезультатЗакрытия.ИмяСохранения = "Обработка_ЗагрузкаЗастрахованныхОС_ЗагрузкаНоменклатуры" Тогда
ОбработатьДанныеЭксель_ЗагрузкаНоменклатуры(РезультатЗакрытия);
КонецЕсли;
КонецПроцедуры
// Процедура заполняет табличную часть ТабЧасть2 данными номенклатуры из Excel.
// Очищает существующие данные и заполняет табличную часть проверенными данными.
//
// Параметры:
// ДанныеОбработки - Структура - обработанные данные из Excel, содержит:
// * ТаблицаФайла - АдресВременногоХранилища - адрес таблицы с данными номенклатуры
//
Процедура ОбработатьДанныеЭксель_ЗагрузкаНоменклатуры(ДанныеОбработки)
// Очистка табличной части перед заполнением
Объект.ТабЧасть.Очистить();
// Проверка корректности переданных данных
Если Не ТипЗнч(ДанныеОбработки) = Тип("Структура") Тогда
Возврат;
КонецЕсли;
// Получение данных из временного хранилища
ДанныеЭксель = ДанныеОбработки.ТаблицаФайла;
Если ДанныеЭксель.Количество() = 0 Тогда
Возврат;
КонецЕсли;
// Перебор строк и заполнение табличной части
Для й = 0 по ДанныеЭксель.Количество() - 1 Цикл
// Добавление строки только если номенклатура найдена
Если ЗначениеЗаполнено(ДанныеЭксель[й].КодНоменклатуры_Расчет) Тогда
стр = Объект.ТабЧасть2.Добавить();
стр.Номенклатура = ДанныеЭксель[й].КодНоменклатуры_Расчет;
стр.Количество = ДанныеЭксель[й].Количество_Расчет;
КонецЕсли;
КонецЦикла;
// Установка признака модифицированности формы
Модифицированность = Истина;
КонецПроцедуры
// Процедура заполняет табличную часть ТабЧасть данными контрагентов и счетов учета из Excel.
// Очищает существующие данные и заполняет табличную часть проверенными данными.
//
// Параметры:
// ДанныеОбработки - Структура - обработанные данные из Excel, содержит:
// * ТаблицаФайла - АдресВременногоХранилища - адрес таблицы с данными контрагентов
//
Процедура ОбработатьДанныеЭксель(ДанныеОбработки)
// Очистка табличной части перед заполнением
Объект.ТабЧасть.Очистить();
// Проверка корректности переданных данных
Если Не ТипЗнч(ДанныеОбработки) = Тип("Структура") Тогда
Возврат;
КонецЕсли;
// Получение данных из временного хранилища
ДанныеЭксель = ДанныеОбработки.ТаблицаФайла;
Если ДанныеЭксель.Количество() = 0 Тогда
Возврат;
КонецЕсли;
// Перебор строк и заполнение табличной части
Для й = 0 по ДанныеЭксель.Количество() - 1 Цикл
// Добавление строки только если контрагент найден
Если ЗначениеЗаполнено(ДанныеЭксель[й].КодКонтрагента_Расчет) Тогда
стр = Объект.ТабЧасть.Добавить();
стр.Контрагент = ДанныеЭксель[й].КодКонтрагента_Расчет;
стр.СчетУчета = ДанныеЭксель[й].КодСчетаУчета_Расчет;
// Пример заполнениея данных
стр.Строка1 =ДанныеЭксель[й].Поле1 + " " + ДанныеЭксель[й].Поле2;
// Установка признака необходимости обработки строки
стр.Обрабатывать = Истина;
КонецЕсли;
КонецЦикла;
// Установка признака модифицированности формы
Модифицированность = Истина;
КонецПроцедуры
Проверено на следующих конфигурациях и релизах:
- 1С:Библиотека стандартных подсистем, редакция 3.1, релизы 3.1.10.645
Вступайте в нашу телеграмм-группу Инфостарт
