Использование экспорта и импорта

Одной из самых распространенных задач, из встречающихся при работе над различными проектами, является задача по импортированию данных в систему и экспортированию данных в файл из неё. Для решения подобных задач в системе реализованы классы ImportFile и ExcelExport. С примером использования этих классов можно ознакомиться в демонстрационном проекте: http://gogs.lexema.ru/core/lexema-demo/src/master/source/beginner/imports/importsForm.js

Импорт данных

Класс ImportFile предоставляет два метода для импортирования файлов: в формате редакторов электронных таблиц Excel и OpenDocument и текстовом формате в различных кодировках.

В формате Excel

Первый метод - fromExcel.

В качестве первого параметра он принимает массив объектов со следующей структурой:

• sheetName - наименование листа в файле;
• columns - объект с полями, описывающими импортируемые столбцы;
  • <буквенный индекс столбца> - значением поля является строка, которая будет идентифицировать поля импортированных строк;
• startDataRow - номер строки, с которой начинается требуемый набор данных.

В качестве второго параметра он принимает объект со свойством:

• multiple - булевая переменная отвечающая за возможность загрузки нескольких файлов одновременно;

Пример метода формы, демонстрирующий импорт данных в контрол Grid:

Файл

fromExcelImport () {
  ImportFile.fromExcel([{
    sheetName: 'Sheet1',
    columns: {
      A: 'Number',
      B: 'FIO'
    },
    startDataRow: 2
  }]).done(rows => {
    this.controls.excelGrid.dataSource = ko.observableArray(rows.Sheet1)
  })
}

В примере происходит обращение к листу с идентификатором Sheet1 и двум колонкам с индексами A и B. Для этих колонок определяются имена, которые будут присвоены им в результатах импорта. Не рекомендуется передавать в массив параметров метода fromExcel объекты, описывающие один и тот же лист, поскольку в таком случае нет возможности гарантировать корректность возвращаемых результатов.

Примечание

Также важным требованием является строгое соответствие структуры импортируемого файла структуре, описанной в реализованном функционале.

Результаты импорта в данном конкретном примере представляют собой следующий объект:

Файл

rows = {
  Sheet1: [{
    Number: 1,
    FIO: 'Иванов И.И'
  }, {
    Number: 2,
    FIO: 'Петров П.П'
  }]
}

В объекте с результатами каждое поле соответствует использованным листам и содержит массив с найденными строками.

Пример метода формы, демонстрирующий импорт данных с переменной multiple:

Файл

fromExcelImport () {
  ImportFile.fromExcel([{
    sheetName: 'Sheet1',
    columns: {
      A: 'Number',
      B: 'FIO'
    },
    startDataRow: 2
  }], { multiple: true }).done(rows => {
    console.log('rows', rows)
  })
}

Результаты импорта в данном конкретном примере с переменной multiple:

Файл

rows = [
{
  Sheet1: [{
    Number: 1,
    FIO: 'Иванов И.И'
  }, {
    Number: 2,
    FIO: 'Петров П.П'
  }]
},
{
  Sheet2: [{
    Number: 1,
    FIO: 'Сидоров И.И'
  }, {
    Number: 2,
    FIO: 'Иванов П.П'
  }]
}
]

В объекте с результатами каждое поле соответствует использованным листам и содержит массив с найденными строками.

В текстовом формате

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

Пример

Файл

fromTextImport () {
  ImportFile.fromText('UTF-8').done(text => {
    this.controls.textMemo.value = text
  })
}

Экспорт данных

Как видно из наименования класса ExcelExport, он предназначен для экспорта данных только в формате электронных таблиц Excel.

Для экспортирования данных в классе реализован метод saveFile.

Также экспорт данных является частью функционала контрола Grid

Пример

Файл

exportToExcel () {
  let options = {
    caption: 'Экспортированные строки',
    groups: ['Text', 'Value'],
    columns: [{
      datafield: 'Index',
      text: 'Индекс',
      width: 100,
      type: 'numberinput'
    }, {
      datafield: 'Text',
      text: 'Текст',
      width: 100,
      type: 'textbox',
      parentGroupName: 'values'
    }, {
      datafield: 'Value',
      text: 'Значение',
      width: 100,
      type: 'textbox',
      parentGroupName: 'values'
    }],
    columnGroups: [{
      name: 'values',
      text: 'Значения'
    }]
  }
  ExcelExport.saveFile({
    data: ko.mapping.toJS(this.controls.exportSource.dataSource),
    options,
    fileName: 'exportedRows.xlsx'
  })
}

static get binding () {
  return class ExportRows extends DataAdapter {
    load () {
      return $.Deferred().resolve({
        exportRows: [{
          Index: 1,
          Text: 'Stamp',
          Value: 'Tools'
        }, {
          Index: 2,
          Text: 'Stomp',
          Value: 'Tracks'
        }, {
          Index: 3,
          Text: 'Start',
          Value: 'Tempo'
        }, {
          Index: 4,
          Text: 'Start',
          Value: 'Volume'
        }]
      })
    }
  }
}

Метод принимает объект с аргументами, которые задают:

• data - массив данных, который будет использоваться для формирования экспортируемой таблицы;
• options - объект, описывающий экспортируемые данные (полный список опций - в статье);
• fileName - строка с наименованием, с которым должен быть сохранён полученный файл. Расширение файла также необходимо указывать. В примере продемонстрирована настройка экспорта данных, задаваемых локально в свойстве binding класса формы. Контрол Grid exportSource на форме привязан к этим данным. Поэтому в качестве значения параметра data метода saveFile используется его источник данных.

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

Содержимое файла, полученного в результате экспорта:

---