Файл Excel

Элемент Файл Excel предоставляет возможность легкого доступа к файлам MS Excel (.xls, .xlsx) из моделей AnyLogic. С помощью этого объекта вы можете:

Демо модель: Reading and Writing Excel Files


  Чтобы создать объект Файл Excel
  1. Перетащите элемент Файл Excel  из палитры Внешние данные на диаграмму агента (или эксперимента).
  2. В панели Свойства, задайте Имя этого элемента. Это имя будет использоваться для идентификации элемента и доступа к нему из кода. 
  3. Укажите, с каким Excel файлом этот объект будет работать. Выберите файл в окне навигации, открываемом по нажатию на кнопку Выбрать. Путь к файлу будет отображен в поле Файл
  4. Перейдите в секцию Специфические. Оставьте выбранным флажок Загружать содержимое при запуске модели. Тем самым вы активируете автоматическую загрузку содержимого рабочей книги из файла при запуске модели, так что вы сможете сразу же начать работать с Excel файлом.
  5. Если вы планируете модифицировать содержимое файла Excel, оставьте выбранным флажок Сохранять при прекращении работы модели. Это избавит вас от необходимости вызывать метод writeFile() этого объекта для того, чтобы записать сделанные вами ранее изменения в файл Excel - это будет делаться автоматически при прекращении работы модели.

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

Пожалуйста, обратите внимание, что до выполнения каких бы то ни было операций с рабочей книгой вы должны будете вызвать метод readFile(). Другим (и более удобным) способом является установка флажка Загружать содержимое при запуске модели в свойствах объекта  - в этом случае содержимое рабочей книги будет автоматически загружаться при запуске модели.

Чтение из Excel файла

Чтение Excel файла - readFile()

void readFile() - Загружает содержимое рабочей книги из файла.
Внимание! Все несохраненные данные в рабочей книге (если такие есть) после вызова этого метода будут потеряны.

Получение типа ячейки - getCellType()

Метод getCellType() возвращает тип ячейки (численный, формула, текстовый...)

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

int getCellType(int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex 

int getCellType(String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

int getCellType(String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Чтение логического значения (boolean) из ячейки - getCellBooleanValue()

Метод getCellBooleanValue() считывает логическое (boolean) значение из ячейки. Для ячеек с текстовыми и численными значениями выдает ошибку. Для пустых ячеек возвращает false.

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

boolean getCellBooleanValue(int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex 

boolean getCellBooleanValue(String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

boolean getCellBooleanValue(String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Чтение численного значения из ячейки - getCellNumericValue()

Метод getCellNumericValue() считывает численное значение из ячейки. Для ячеек с текстовыми значениями выдает ошибку. Для пустых ячеек возвращает 0.

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

double getCellNumericValue(int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex 

double getCellNumericValue(String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

double getCellNumericValue(String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Чтение текста (String) из ячейки - getCellStringValue()

Метод getCellStringValue() считывает текст (String) из ячейки. Для численных значений выдает ошибку. Для пустых ячеек и ячеек с формулами выдает пустую строку.

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

String getCellStringValue(int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex 

String getCellStringValue(String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

String getCellStringValue(String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Чтение даты (Date) из ячейки - getCellDateValue()

Метод getCellDateValue() возвращает значение ячейки в виде даты (Date). Для ячеек с текстовыми значениями выдает ошибку. Для пустых ячеек возвращает null.

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

Date getCellDateValue(int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex 

Date getCellDateValue(String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

Date getCellDateValue(String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Получение формулы, заданной для определенной ячейки - getCellFormula() 

Метод getCellFormula() возвращает формулу, заданную для указанной ячейки, например, SUM(C4:E4)

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

String getCellFormula(int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex 

String getCellFormula(String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

String getCellFormula(String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Получение типа формулы, заданной для определенной ячейки - getCellFormulaType() 

Метод getCellFormulaType() возвращает тип формулы, заданной для указанной ячейки. Допустимо использование только с теми ячейками, в которых хранятся формулы.

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

int getCellFormulaType(int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex 

int getCellFormulaType(String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

int getCellFormulaType(String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Чтение значения ячейки в виде кода ошибки - getCellErrorValue()

Метод getCellErrorValue() возвращает значение ячейки в виде кода ошибки. Для ячеек с текстовыми значениями выдает ошибку. Для пустых ячеек возвращает null.

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

byte getCellErrorValue(int sheetIndex, int rowIndex, int columnIndex)- ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex 

byte getCellErrorValue(String sheetName, int rowIndex, int columnIndex)- ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

byte getCellErrorValue(String cellName)- ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Чтение данных из файла Excel в табличную функцию AnyLogic - readTableFunction()

Метод readTableFunction() считывает данные из файла Excel в заданную табличную функцию.

Если на листе недостаточно данных, чтобы считать заданное количество пар значений, то считывается меньше значений.
Метод возвращает действительное число считанных из рабочей книги пар значений.

Аргументы:
tableFunction - табличная функция, которая будет заполнена считанными из рабочей книги данными
length - количество пар значений, которые должны быть считаны и записаны в табличную функцию

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

int readTableFunction(TableFunction tableFunction, int sheetIndex, int rowIndex, int columnIndex, int length) - заполняет табличную функцию данными, считанными из файла Excel (с листа с номером sheetIndex, начиная с заданной ячейки):
- аргументы считываются из столбца с номером columnIndex
- значения считываются из столбца с номером columnndex + 1

int readTableFunction(TableFunction tableFunction, String sheetName, int rowIndex, int columnIndex, int length) - заполняет табличную функцию данными, считанными из файла Excel (с листа с именем sheetName, начиная с заданной ячейки):
- аргументы считываются из столбца с номером columnIndex
- значения считываются из столбца с номером columnndex + 1

int readTableFunction(TableFunction tableFunction, String cellName, int length) - заполняет табличную функцию данными, считанными из файла Excel (начиная с заданной ячейки):
- аргументы считываются из столбца ячейки
- значения считываются из следующего столбца
ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Чтение данных из файла Excel в массив AnyLogic - readHyperArray()

Метод readHyperArray() заполняет одно- или двумерный массив данными, считанными из файла Excel (начиная с заданной ячейки).

Аргументы:
array - массив, в который будут считаны данные, должен иметь одну или две размерности
dim1AcrossRows - если вы передадите true, то данные, соответствующие первой размерности, будут считываться путем прохода по строкам (то есть, для случая одноразмерного массива в этом случае данные будут считываться из столбца)

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

void readHyperArray(HyperArray array, int sheetIndex, int rowIndex, int columnIndex, boolean dim1AcrossRows) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex

void readHyperArray(HyperArray array, String sheetName, int rowIndex, int columnIndex, boolean dim1AcrossRows) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

void readHyperArray(HyperArray array, String cellName, boolean dim1AcrossRows) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Запись в файл Excel

Пожалуйста, обратите внимание, что для того, чтобы записать сделанные вами изменения в файле Excel, вы должны после произведения операций модификации вызвать метод writeFile(). Другим (и более удобным) способом является установка флажка Сохранять при прекращении работы модели в свойствах объекта  - в этом случае изменения будут автоматически записываться в файл при остановке работы модели.
Сохранение изменений в файле Excel - writeFile()

void writeFile() - Сохраняет все сделанные ранее изменения в файл Excel. Неизмененные рабочие книги не сохраняются. Если вы хотите сохранить изменения в другой файл, пожалуйста, вызовите метод setFileName(String) перед вызовом этого метода.

Создание ячейки с заданным индексом - createCell()

Метод createCell() создает новую ячейку в заданном местоположении.

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

void createCell(int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex

void createCell(String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

void createCell(String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Запись значения в ячейку - setCellValue()

Метод setCellValue() записывает заданное значение в указанную ячейку. Метод может записывать значения всех наиболее часто используемых типов: boolean, double, String, Date

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

void setCellValue(<тип значения> value, int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex

void setCellValue(<тип значения> value, String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

void setCellValue(<тип значения> value, String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Задание формулы для указанной ячейки - setCellFormula() 

Метод setCellFormula() задает формулу для указанной ячейки. Формула передается с помощью аргумента метода formula, например SUM(C4:E4). Если этот аргумент не задан (равен null), то текущая формула ячейки удаляется.

Этот метод только задает строку формулы, но не вычисляет ее значение. Чтобы задать ранее вычисленное значение, используйте метод  setCellValue(...). Чтобы вычислить все формулы рабочей книги, используйте метод evaluateFormuals().

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

void setCellFormula(String formula, int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex

void setCellFormula(String formula, String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

void setCellFormula(String formula, String cellName) - ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Запись данных из набора данных AnyLogic в файл Excel - writeDataSet()
Метод writeDataSet() записывает данные из заданного набора данных в рабочую книгу, начиная с указанной ячейки. Данные записываются построчно, в два столбца: отдельно X и Y составляющие каждой пары значений. 

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

int writeDataSet(DataSet dataset, int sheetIndex, int rowIndex, int columnIndex) - ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex

int writeDataSet(DataSet dataset, String sheetName, int rowIndex, int columnIndex) - ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

int writeDataSet(DataSet dataset, String cellName)- ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Методы валидации и вспомогательные методы

Получение количества листов в Excel файле - getNumberOfSheets()

int getNumberOfSheets() - Возвращает количество листов в рабочей книге.

Получение имени заданного листа - getSheetName()

String getSheetName(int sheetIndex) - Возвращает имя листа с заданным индексом sheetIndex.

Проверка существования ячейки - cellExists()

Метод cellExists() возвращает true, если в рабочей книге существует ячейка с заданным индексом.

У метода есть три нотации с различными наборами аргументов. Они отличаются способом задания ячейки.

boolean cellExists(int sheetIndex, int rowIndex, int columnIndex)
- ячейка задается с помощью 3 чисел (нумерация начинается с единицы): номер листа sheetIndex, номер строки rowIndex и номер столбца columnIndex

boolean cellExists(String sheetName, int rowIndex, int columnIndex)- ячейка задается с помощью имени листа sheetName и 2 чисел (нумерация начинается с единицы): номера строки rowIndex и номера столбца columnIndex

boolean cellExists(String cellName)- ячейка задается по имени в следующем формате: <имяЛиста>!<имяСтолбца><номерСтроки>, например, Лист1!A3 (Имя листа может быть опущено, в этом случае будет подразумеваться первый лист)

Получение номера первой строки на листе - getFirstRowNum()

Метод getFirstRowNum() возвращает номер первой логической строки на листе (нумерация начинается с единицы).

У метода есть две нотации с различными наборами аргументов. Они отличаются способом задания листа.

int getFirstRowNum(int sheetIndex)
- лист задан номером sheetIndex.

int getFirstRowNum(String sheetName) - лист задан именем sheetName.

Получение номера последней строки на листе - getLastRowNum()

Метод getLastRowNum() возвращает номер последней логической строки на листе (нумерация начинается с единицы).

У метода есть две нотации с различными наборами аргументов. Они отличаются способом задания листа.

int getLastRowNum(int sheetIndex)
- лист задан номером sheetIndex.

int getLastRowNum(String sheetName) - лист задан именем sheetName.

Получение номера первой ячейки в строке - getFirstCellNum()

Метод getFirstCellNum() возвращает номер первой ячейки в заданной строке. Если быть точнее, возвращает номер столбца (нумерация начинается с единицы), содержащего первую логическую ячейку в строке, если строка не содержит ячеек, то возвращает 0. 

У метода есть две нотации с различными наборами аргументов. Они отличаются способом задания листа.

int getFirstCellNum(int sheetIndex
, int rowIndex) - и лист, и столбец заданы номерами (sheetIndex и rowIndex соответственно).

int getFirstCellNum(String sheetName, int rowIndex) - лист задан именем sheetName, а столбец - номером rowIndex.

Получение номера последней ячейки в строке - getLastCellNum()

Метод getLastCellNum() возвращает номер последней ячейки в заданной строке. Если быть точнее, возвращает номер столбца (нумерация начинается с единицы), содержащего последнюю логическую ячейку в строке, если строка не содержит ячеек, то возвращает 0

У метода есть две нотации с различными наборами аргументов. Они отличаются способом задания листа.

int getLastCellNum(int sheetIndex
, int rowIndex) - и лист, и столбец заданы номерами (sheetIndex и rowIndex соответственно).

int getLastCellNum(String sheetName, int rowIndex) - лист задан именем sheetName, а столбец - номером rowIndex.

Вычисление формул в файле Excel - evaluateFormulas()

void evaluateFormulas(int sheetIndex, int rowIndex) - Вычисляет формулы и сохраняет результат их вычисления в соответствующих ячейках рабочей книги.

Ячейки остаются ячейками, хранящими формулы (и их результат). Если вам нужно, чтобы формула ячейки была перезаписана результатом ее вычисления, используйте метод org.apache.poi.ss.usermodel.Cell.evaluateInCell(org.apache.poi.ss.usermodel.Cell)