xls21c

Нативная внешняя компонента для 1С 8 для чтения файлов Excel. Позволяет открывать XLS и XLSX файлы и получать содержимое листов в виде ТаблицыЗначений или JSON-массива.

Поддерживает работу в:

• Windows x86
• Windows x64

Форматы файлов

Компонента поддерживает чтение двух форматов:

Формат файла определяется автоматически по сигнатуре (первые 8 байт файла), а не по расширению.

Кодировка текста

Все текстовые данные из файлов Excel конвертируются из UTF-8 (внутренний формат библиотек) в UTF-16 (внутренний формат 1С). Кириллические имена файлов в путях поддерживаются корректно — при необходимости файл временно копируется в системную папку с ASCII-именем.

Использование

Подключается как обычная нативная ВК:

ПутьКВК = "C:\path\to\xls21c.dll";

Если Не ПодключитьВнешнююКомпоненту(ПутьКВК, "xls21c", ТипВнешнейКомпоненты.Native) Тогда
    Предупреждение("Не удалось подключить внешнюю компоненту " + ПутьКВК);
    Возврат;
КонецЕсли;

После подключения доступен создание объект внешней компоненты:

xls = Новый("AddIn.xls21c.xls21c");

Свойства объекта

Версия / Version

Строка, только чтение. Версия компоненты.

БросатьОписаниеОшибки / ThrowErrorDescription

Булево, чтение/запись. По умолчанию Ложь.

Флаг, нужно ли при возникновении исключения добавлять текстовое описание ошибки штатным для ВК методом AddError. Если значение свойства Ложь, то текст ошибки не будет выдавать в исключении (будет просто штатное "Ошибка при вызове метода объекта"). Описание ошибки в этом случае можно прочитать в свойстве ОписаниеОшибки.

ОписаниеОшибки / ErrorDescription

Строка. Только чтение. Содержит текстовое описание последней ошибки.

Попытка
    xls.ОткрытьФайл("D:\Файл.xlsx");
Исключение
    Сообщить(xls.ОписаниеОшибки);
КонецПопытки;

ФайлОткрыт / IsFileOpen

Булево. Только чтение. Показывает, открыт ли в данный момент файл Excel.

КоличествоЛистов / SheetCount

Число. Только чтение. Возвращает количество листов в открытом файле.

Методы объекта

ОткрытьФайл(ИмяФайла) / OpenFile(FileName)

Открывает файл Excel. Формат определяется автоматически по сигнатуре файла (ZIP для xlsx, OLE2 для xls). Если ранее был открыт другой файл — он закрывается автоматически.

Параметры:

• ИмяФайла: Строка, обязательный. Путь к файлу Excel.

Возвращаемое значение — нет. При ошибке выбрасывает исключение.

Пример:

xls = Новый("AddIn.xls21c.xls21c");
xls.ОткрытьФайл("D:\База\Прайс.xlsx");
xls.ОткрытьФайл("D:\База\Заказ.xls");

ЗакрытьФайл() / CloseFile()

Закрывает ранее открытый файл и освобождает память. Параметров нет. Возвращаемого значения нет.

Пример:

xls.ЗакрытьФайл();

ПолучитьИмяЛиста(Индекс) / GetSheetName(Index)

Возвращает имя листа по его порядковому номеру.

Параметры:

• Индекс: Число, обязательный. Номер листа, нумерация с 0.

Возвращаемое значение: Строка — имя листа.

Пример:

xls = Новый("AddIn.xls21c.xls21c");
xls.ОткрытьФайл("D:\База\Прайс.xlsx");

Для Индекс = 0 По xls.КоличествоЛистов - 1 Цикл
    Сообщить("Лист " + Индекс + ": " + xls.ПолучитьИмяЛиста(Индекс));
КонецЦикла;

ПрочитатьЛист(ИндексЛиста, Формат [, Диапазон]) / ReadSheet(SheetIndex, Format [, Range])

Читает содержимое указанного листа и возвращает данные в выбранном формате.

Параметры:

• ИндексЛиста: Число, обязательный. Номер листа, нумерация с 0.
• Формат: Строка, обязательный. Задаёт формат результата:
  • "ТаблицаЗначений" / "ValueTable" — внутренний формат 1С, декодируется функцией ЗначениеИзСтрокиВнутр()
  • "JSON" — массив массивов для преобразования через СериализаторXDTO.ПрочитатьJSON()
• Диапазон: Строка, необязательный. Диапазон ячеек в формате Excel (например, "A1:C10"). Если не указан — читается весь лист (поведение по умолчанию). Возвращаются только заполненные строки в пределах указанного диапазона. Поддерживаемые форматы:
  • "A1:A10" — одна колонка, 10 строк
  • "B1:B1" — одна ячейка
  • "A1:C10" — блок 3 колонки × 10 строк
  • "AA1:AA100" — колонка с двубуквенным индексом

Возвращаемое значение: Строка с данными листа. При ошибке выбрасывает исключение.

Пример:

xls = Новый("AddIn.xls21c.xls21c");
xls.ОткрытьФайл("D:\База\Прайс.xlsx");

// Чтение всего листа
СтрокаВнутр = xls.ПрочитатьЛист(0, "ТаблицаЗначений");
ТЗ = ЗначениеИзСтрокиВнутр(СтрокаВнутр);

// Чтение одной колонки (например, только артикулы из колонки B)
СтрокаВнутр = xls.ПрочитатьЛист(0, "ТаблицаЗначений", "B1:B100");
Артикулы = ЗначениеИзСтрокиВнутр(СтрокаВнутр);

// Чтение одной ячейки (строка 9, колонка 4 = ячейка D9)
СтрокаВнутр = xls.ПрочитатьЛист(0, "ТаблицаЗначений", "D9:D9");
ТЗ = ЗначениеИзСтрокиВнутр(СтрокаВнутр);

// Чтение блока ячеек
СтрокаВнутр = xls.ПрочитатьЛист(0, "ТаблицаЗначений", "A1:C10");
ТЗ = ЗначениеИзСтрокиВнутр(СтрокаВнутр);

// Получение как JSON
Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(xls.ПрочитатьЛист(0, "JSON"));
Массив = СериализаторXDTO.ПрочитатьJSON(Чтение);

// Чтение диапазона как JSON
Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(xls.ПрочитатьЛист(0, "JSON", "A1:C10"));
Массив = СериализаторXDTO.ПрочитатьJSON(Чтение);

Формат выходных данных

ТаблицаЗначений

При выборе формата "ТаблицаЗначений" возвращается строка, которая методом ЗначениеИзСтрокиВнутр() преобразуется в ТаблицуЗначений.

Структура таблицы:

Все значения ячеек Excel преобразуются в строки. Пустые ячейки содержат Null. Колонка "НомерСтроки" добавляется автоматически и содержит порядковый номер строки начиная с 1.

Пример результата для файла с 3 колонками и 2 строками данных:

НомерСтроки | k_1        | k_2   | k_3
1            | Наименование | Артикул | Цена
2            | Товар       | A001   | 150.00

JSON

При выборе формата "JSON" возвращается строка, которая через XDTO преобразуется в массив. Первый элемент массива — массив с именами колонок. Последующие элементы — массивы со значениями строк.

[
  ["НомерСтроки", "k_1", "k_2", "k_3"],
  [1, "Наименование", "Артикул", "Цена"],
  [2, "Товар", "A001", "150.00"]
]

Преобразование типов ячеек:

• Текстовые значения — jxs:string
• Числовые значения — jxs:decimal
• Пустые ячейки — jv8:Null

Полный пример

// Подключение компоненты
Если Не ПодключитьВнешнююКомпоненту("C:\path\to\xls21c.dll", "xls21c", ТипВнешнейКомпоненты.Native) Тогда
    Предупреждение("Не удалось подключить xls21c");
    Возврат;
КонецЕсли;

xls = Новый("AddIn.xls21c.xls21c");

// Открытие файла
xls.ОткрытьФайл("D:\База\Прайс.xlsx");

// Вывод информации о листах
Сообщить("Количество листов: " + xls.КоличествоЛистов);
Для Индекс = 0 По xls.КоличествоЛистов - 1 Цикл
    Сообщить("  Лист " + Индекс + ": " + xls.ПолучитьИмяЛиста(Индекс));
КонецЦикла;

// Чтение данных первого листа
Попытка
    СтрокаВнутр = xls.ПрочитатьЛист(0, "ТаблицаЗначений");
    ТЗ = ЗначениеИзСтрокиВнутр(СтрокаВнутр);
    ТЗ.ВыбратьСтроку();
Исключение
    Сообщить("Ошибка: " + ОписаниеОшибки());
КонецПопытки;

// Закрытие файла
xls.ЗакрытьФайл();

Обработка ошибок

Попытка
    xls.ОткрытьФайл("D:\База\Существующий.xlsx");
Исключение
    Сообщить("Ошибка VK: " + xls.ОписаниеОшибки);
    Сообщить("Ошибка 1С: " + ОписаниеОшибки());
КонецПопытки;

Ссылка на github.com