file

Это интерфейс создания и заполнения файлов отчетов и смет: таблиц Excel (XLSX, XLS), документов MS Word (DOCX), PDF и текстовых файлов (TXT). Интерфейс доступен в плагинах типов «Отчет», «Смета», «Ворм», «Бизнес-процесс» и «Виджет». Готовый файл система сама отдает пользователю после выполнения start(). В нем доступны следующие функции:

Создание файла

• create - функция конструктор, создает и подготавливает файл для приема данных
• getResource - возвращает сформированный файл (вызывается системой автоматически)

Таблицы Excel (XLSX, XLS)

• addSheet - создание дополнительного листа таблицы
• renameCurrentSheet - редактирование названия текущего / активного листа
• renameSheet - редактирование названия листа
• setCurrentSheet - установка активного листа таблицы
• addHeaderRow - функция, которая формирует заголовок на странице Excel файла
• addRow - функция, которая формирует строку на странице Excel файла
• insertRow - функция, которая вставляет строку на указанную позицию на странице Excel файла
• replaceRow - функция, которая замещает строку на указанной позиции на странице Excel файла
• deleteRow - функция, которая удаляет строку с указанной позиции на странице Excel файла
• addCell - создание ячейки в указанном столбце
• addCellWrap - создание ячейки с переносом текста в указанном столбце и строке
• addMatrix - добавление в таблицу Excel строк из набора List или Map
• merge - объединение ячеек
• autoSizeColumns - функция установки автоматической ширины колонок страницы Excel файла
• setSizeColumns - устанавливает ширину и высоту для ячеек заданной колонки
• setSizeAndWrapColumns - устанавливает ширину и перенос текста для ячеек заданной колонки
• setCenterAlignment - устанавливает выравнивание по центру для всех ячеек заданной колонки
• setAlignment - устанавливает выбранное выравнивание для всех ячеек заданной колонки
• setBorder - устанавливает границы для указанного диапазона ячеек
• createStyle - создание нового стиля для форматирования текста ячеек Excel
• setStyle - применение указанного стиля к тексту указанной ячейки Excel файла
• sortASC - сортировка таблицы в порядке возрастания по значению в указанном столбце
• sortDESC - сортировка таблицы в порядке убывания по значению в указанном столбце
• getWorkbook - получение интерфейса текущего табличного документа Workbook
• getSheet - получение интерфейса текущей страницы с таблицей

Документы MS Word (DOCX) и PDF

• addTitle - добавление заголовка в документ
• addParagraph - функция создания нового параграфа в документе
• addCenterParagraph - функция создания нового параграфа с размещением текста посередине, с указанием размера шрифта и указанием жирный/простой
• addRightParagraph - функция создания нового параграфа с размещением текста справа, с указанием размера шрифта и указанием жирный/простой
• addLeftParagraph - функция создания нового параграфа с размещением текста слева, с указанием размера шрифта и указанием жирный/простой
• addText - функция добавления строки с данными в документ
• addTextBreak - функция перевода каретки указателя на новую строку в документе MS Word (DOCX)
• addAreaBreak - добавление разрыва области PDF документа или разрыва страницы MS Word (DOCX)
• getDocument - получение интерфейса текущего документа XWPFDocument (DOCX)
• getParagraph - получение интерфейса текущего параграфа XWPFParagraph (DOCX)

Изображения

• addImage - добавление изображения в документ MS Word (DOCX), PDF или в ячейку XLSX
• getImage - получение картинки из общей коллекции
• addDrawing - добавление чертежа с пронумерованными метками в документ PDF

Генерация документа с использованием шаблона

• templateToPdf - генерация pdf документа из шаблона (устарел)

Генерация отчета по коллизиям

• collisionsToPdf - генерация pdf по списку коллизий

Служебные методы

• saveTempTable - сохранение таблицы Excel во временный файл по указанному пути
• xlsxToJSON - преобразование содержимого документа Excel в формат JSON
• makeGrandSmetaExelTable - создание документа Excel для отчета о гранд-смете (не использовать)

Общий пример использования интерфейса file в плагинах

Создание файла

• file.create(String type) - type: "XLSX", "XLS", "DOCX", "PDF" или "TXT" (регистр не важен). Повторный вызов закрывает ранее созданный документ и начинает новый

Пример использования:

file.create("XLSX")
// или
file.create("TXT")

• file.getResource() → ResponseEntity<?> - записывает документ и возвращает его как ответ с файлом plugin_result_<uuid плагина>.<расширение>

Таблицы Excel (XLSX, XLS)

• file.addSheet(String sheetName) - созданный новый лист становится активным

Пример использования:

file.addSheet("Лист2")

• file.renameCurrentSheet(String newSheetName) - редактирование названия текущего / активного листа

Пример использования:

file.renameCurrentSheet("Лист3")

• file.renameSheet(int id, String newSheetName) - редактирование названия листа, ID листа - это его порядковый номер, отсчет начинается с нуля
• file.renameSheet(String oldSheetName, String newSheetName) - редактирование названия листа

Пример использования:

file.renameSheet(0, "Лист2")
file.renameSheet("Лист2", "Лист3")

• file.setCurrentSheet(String sheetName) - установка активного листа таблицы по его названию
• file.setCurrentSheet(int id) - ID листа - это его порядковый номер, отсчет начинается с нуля

Пример использования:

file.setCurrentSheet("Лист2")
file.setCurrentSheet(1)

• file.addHeaderRow(Object... inp) - добавляет строку заголовков в конец текущего листа (текст жирный, по центру). Значения записываются строками

Пример использования:

file.addHeaderRow("Код", "Название", "Ед. изм.", "Кол. во.")

• file.addRow(Object... inp) - добавляет строку со значениями в конец текущего листа
• file.addRow(Map<Object, Object>... inp) - добавляет строку, раскладывая значения по столбцам: ключ — текст заголовка в первой строке листа или индекс столбца (Integer)

Тип значения определяет формат ячейки: Integer/Long — целое число; Double/Float/BigDecimal — число с 2 знаками после запятой; Date/Calendar/Instant — дата dd.mm.yyyy hh:mm:ss; null — пустая ячейка; остальное записывается текстом (toString()), текст с переводом строки получает перенос. Чтобы в Excel получилось число, передавайте число, а не строку.

Пример использования:

file.addRow(row.get("code"), row.get("title"), row.get("units"), row.get("quantityAll"))

// по заголовкам
file.addHeaderRow("Этаж", "Объём, м3")
file.addRow(["Этаж": "1", "Объём, м3": 12.5])

• file.insertRow(int indexRow, Object... inp) - вставляет строку на позицию indexRow, строки ниже сдвигаются вниз
• file.insertRow(int indexRow, Map<Object, Object>... inp) - то же, значения раскладываются по заголовкам (как в addRow)

Пример использования:

file.insertRow(6, "Вставленная строка", 1, 2.453, new Date(), Calendar.getInstance())

• file.replaceRow(int indexRow, Object... inp) - замена значений указанной строки новыми значениями (прежние ячейки строки удаляются)
• file.replaceRow(int indexRow, Map<Object, Object>... inp) - замена значений по заголовкам указанной строки новыми значениями

Пример использования:

file.replaceRow(7, "Замещенная строка", 4, 5.678, new Date(), Calendar.getInstance())

• file.deleteRow(int indexRow) - строки ниже сдвигаются вверх

Пример использования:

file.deleteRow(3)

• file.addCell(int indexColumn, int indexRow, Object value) - создание ячейки в указанном столбце и строке текущего листа с указанным значением (строка создается при необходимости)
• file.addCell(int indexColumn, Object value) - создание ячейки в указанном столбце последней существующей строки текущего листа

Пример использования:

file.addCell(0, 5, "Итого")
file.addCell(3, 125.5)   // в последнюю строку

• file.addCellWrap(int indexColumn, int indexRow, Object value) - создание ячейки с переносом текста в указанном столбце и строке текущего листа с указанным значением

Пример использования:

file.addCellWrap(0, row, taskTitle)

• file.addMatrix(List... matrix) - каждый List добавляется отдельной строкой, но целиком в одну ячейку
• file.addMatrix(Map... matrix) - каждый Map добавляется отдельной строкой с раскладкой значений по заголовкам (как addRow с Map)

Пример использования:

file.addHeaderRow("Код", "Название")
def rows = [["Код": "01", "Название": "Стена"], ["Код": "02", "Название": "Плита"]]
file.addMatrix(rows as Map[])

// для списка списков используйте цикл
def matrix = [["01", "Стена"], ["02", "Плита"]]
matrix.each { r -> file.addRow(r as Object[]) }

• file.merge(int firstRow, int lastRow, int firstCol, int lastCol) - объединяет диапазон ячеек текущего листа; содержимое первой ячейки выравнивается по центру

Пример использования:

file.addHeaderRow("Наименование", "Количество", "")
file.merge(0, 0, 1, 2)   // строка 0, столбцы 1..2

• file.autoSizeColumns() - для всех колонок на всех листах (по ячейкам первой строки листа)
• file.autoSizeColumns(int indexColumn) - для конкретной колонки текущего листа

Пример использования:

file.autoSizeColumns()

• file.setSizeColumns(int indexColumn, int indexRowStart, int width, int height) - устанавливает ширину колонки и высоту всех строк начиная с indexRowStart
• file.setSizeColumns(int indexColumn, int width) - устанавливает ширину для ячеек заданной колонки

Ширина задается в единицах Apache POI (1/256 ширины символа, 256 = 1 символ), высота строки — в 1/20 пункта.

Пример использования:

file.setSizeColumns(1, 1, 18000, 5000)
file.setSizeColumns(2, 20 * 256)

• file.setSizeAndWrapColumns(int indexColumn, int width) - устанавливает ширину колонки (в единицах 1/256 символа) и перенос текста во всех ее ячейках

Пример использования:

file.setSizeAndWrapColumns(1, 40 * 256)

• file.setCenterAlignment(int indexColumn) - устанавливает выравнивание по центру для всех ячеек заданной колонки

Пример использования:

file.setCenterAlignment(2)

• file.setAlignment(int indexColumn, String alignment) - alignment: "LEFT", "CENTER" или "RIGHT" (регистр не важен); по вертикали ячейки выравниваются по центру

Пример использования:

file.setAlignment(3, "RIGHT")

• file.setBorder(int startColumn, int endColumn, int startRow, int endRow) - рамка по внешнему контуру диапазона
• file.setBorder(int startColumn, int endColumn, int startRow, int endRow, boolean isFillAll) - при isFillAll = true границы рисуются у каждой ячейки диапазона

Значение endRow = -1 означает «до последней строки листа».

Пример использования:

file.setBorder(0, 3, startRow, row - 1)
file.setBorder(0, 3, 0, -1, true)

• file.createStyle(String font, String sizeFont, String colorFont, boolean isBold) → ExcelStyleManager - создает стиль: название шрифта, размер шрифта (строкой), цвет шрифта, жирный/простой

Цвета: black, white, red, blue, green, yellow, orange, pink, gray (другое значение — черный).

Пример использования:

def style = file.createStyle("Arial", "12", "red", true)

• file.setStyle(int indexRow, int indexColumn, ExcelStyleManager style) - применяет стиль, созданный createStyle, к ячейке текущего листа

Пример использования:

file.addRow("Итого", 125.5)
def style = file.createStyle("Arial", "12", "red", true)
file.setStyle(1, 0, style)   // строка 1, столбец 0

• file.sortASC(int indexColumn) → Map<Integer, Integer> - сортирует строки текущего листа, кроме первой (заголовка). Возвращает соответствие «старая позиция строки → новая позиция» (позиции считаются от 0 без учета заголовка)

Пример использования:

file.sortASC(2)

• file.sortDESC(int indexColumn) → Map<Integer, Integer> - то же, что sortASC, в порядке убывания

Пример использования:

file.sortDESC(2)

• file.getWorkbook() → Workbook - см. документацию Apache POI

• file.getSheet() → Sheet - см. документацию Apache POI

Пример использования:

def sheet = file.getSheet()
sheet.createFreezePane(0, 1)   // закрепить строку заголовка

Общий пример (смета):

def start() {
    file.create("XLS")
    file.addHeaderRow("Код", "Название", "Ед. изм.", "Кол. во.")
    def data = params.get("data") ?: []
    for (def row : data) {
        file.addRow(
            row.get("code"),
            row.get("title"),
            row.get("units"),
            row.get("quantityAll"))
    }
    file.autoSizeColumns()
}

Ключи строк сметы, используемые в row.get:

Состав ключей зависит от сметы — читайте значения через row.get(...) с учетом того, что ключа может не быть.

Документы MS Word (DOCX) и PDF

Методы этого раздела работают для документов DOCX и PDF (в PDF используется шрифт Times New Roman с кириллицей). Для TXT текст записывается отдельной строкой.

• file.addTitle(String text) - с базовыми настройками (20 pt, жирный, по центру)
• file.addTitle(String text, int fontSize, boolean bold) - с указанием размера шрифта, и указанием жирный/простой

Примеры использования:

file.addTitle("Заголовок")

file.addTitle("Заголовок", 30, true)

• file.addParagraph(String text) - с базовыми настройками (12 pt, отступ первой строки)
• file.addParagraph(String text, int indent, int fontSize, boolean bold) - с указанием отступа, размера шрифта, и указанием жирный/простой. Отступ первой строки indent (в пунктах) учитывается только в PDF, в DOCX используется стандартный отступ

Примеры использования:

file.addParagraph("Текст")
file.addText(" Продолжение текста")

file.addParagraph("Текст", 20, 10, true)
file.addText(" Продолжение текста")

• file.addCenterParagraph(String text, int fontSize, boolean bold)

Пример использования:

file.addCenterParagraph("Текст", 10, true)

• file.addRightParagraph(String text, int fontSize, boolean bold)

Пример использования:

file.addRightParagraph("Подпись: ____________", 10, false)

• file.addLeftParagraph(String text, int fontSize, boolean bold)

Пример использования:

file.addLeftParagraph("Текст", 10, true)

• file.addText(String text) - добавление текста
• file.addText(String text, int fontSize, boolean bold) - добавление текста с указанием размера шрифта и указанием жирный/простой (только DOCX, PDF, TXT)
• file.addText(Object objectValue) - добавление объекта в строковом представлении
• file.addText(long longValue) - добавление числа типа long в строковом представлении
• file.addText(double doubleValue) - добавление числа типа double в строковом представлении

Поведение зависит от типа файла: в DOCX текст дописывается в текущий абзац (новый абзац начинают addParagraph, add*Paragraph, addTitle); в PDF добавляется отдельным абзацем; в TXT каждая запись дополняется переводом строки; в XLS/XLSX addText(String) добавляет строку с одной ячейкой.

Примеры использования:

file.addText("Строка, которая появится в файле", 10, false)

file.addText("Строка, которая появится в файле")

• file.addTextBreak() - в DOCX — перенос строки внутри текущего абзаца, в TXT — перевод строки; в PDF не действует

Пример использования:

file.addTextBreak()

• file.addAreaBreak() - в PDF — разрыв области (новая страница), в DOCX — разрыв страницы; для других типов не действует

Пример использования:

file.addAreaBreak()

• file.getDocument() → XWPFDocument - см. документацию Apache POI. Например, таблицы в DOCX создаются через file.getDocument().createTable(...)

Пример использования:

def docTable = file.getDocument().createTable(2, 2)
docTable.getRow(0).getCell(0).setText("Параметр")
docTable.getRow(0).getCell(1).setText("Значение")

• file.getParagraph() → XWPFParagraph - см. документацию Apache POI

Пример документа DOCX:

def start() {
    def project = bim.getProject()
    file.create("DOCX")
    file.addTitle("Отчёт по проекту " + project.title)
    file.addParagraph("Текст с отступом", 0, 12, false)
    file.addText(" продолжение того же абзаца")
    file.addTextBreak()
    file.addLeftParagraph("Слева", 11, true)
    file.addCenterParagraph("По центру", 11, false)
    file.addRightParagraph("Подпись: ____________", 11, false)
    file.addAreaBreak()
}

Изображения

• file.addImage(byte[] imageFile) - добавление изображения в документ PDF (масштабируется по размеру области, по центру). Для других типов файлов не действует
• file.addImage(String imageFile) - добавление изображения в документ DOCX (в текущий абзац, 300×200 pt); imageFile — имя файла из вложений (/collections/attachments/). Для других типов файлов не действует
• file.addImage(int colI, int rowI, String fileName) - добавление изображения вложения задачи в ячейку (colI, rowI) файла XLSX
• file.addImage(int colI, int rowI, String fileUrl, int widthInPixels) - добавление картинки из общей коллекции в ячейку файла XLSX с шириной widthInPixels; ширина колонки и высота строки подгоняются под картинку
• file.addImage(int colI, int rowI, PluginImage img, int widthInPixels) - то же для картинки, полученной через getImage

Пример использования:

// PDF
file.create("PDF")
def img = file.getImage("collections/images/Arm/О_(23).png")
file.addImage(img.ToByteArray())

// XLSX
file.create("XLSX")
file.addHeaderRow("Наименование", "Эскиз")
file.addRow("Кольцо", "")
file.addImage(1, 1, file.getImage("collections/images/Arm/О_(23).png"), 120)

• file.getImage(String fileUrl) → PluginImage - получение картинки в формате png или jpg (jpeg); если файл не удалось прочитать, выполнение завершается ошибкой. Картинки svg и webp в документы не вставляются, для них используйте png или jpg

Для работы с картинками доступны вспомогательные методы:

• img.crop(int x, int y, int width, int height) → PluginImage - вырезать область: левый верхний угол (x, y), ширина и высота в пикселях
• img.ToByteArray() → byte[] - картинка в виде массива байтов (например, для addImage в PDF)
• Images.joinHorizontal(PluginImage... images) → PluginImage - склеивание картинок по горизонтали
• Images.joinVertical(PluginImage... images) → PluginImage - склеивание картинок по вертикали

Пример использования:

def img1 = file.getImage("collections/images/Arm/IFC_Арматура_Кольцо_ГОСТ_5781-82.png")
def img2 = file.getImage("collections/images/Arm/О_(23).png")
def img3 = Images.joinHorizontal(img1, img2.crop(10, 10, 400, 200))
def img4 = Images.joinVertical(img1, img2.crop(10, 10, 400, 200))

• file.addDrawing(byte[] drawingPage, double[][] arr) - на изображение чертежа наносятся метки с номерами 1, 2, 3…; координаты каждой метки [x, y] задаются в процентах от ширины и высоты изображения. В DOCX и других типах файлов метод не действует

Пример использования:

file.create("PDF")
def drawingPage = file.getImage("collections/images/plan.png").ToByteArray()
def points = [[25.0, 40.0], [70.5, 55.0]] as double[][]
file.addDrawing(drawingPage, points)

Генерация документа с использованием шаблона

• template.add("название тега в шаблоне", данные)
• file.templateToPdf(TemplateService template)

Пример использования:

def project = bim.getProject()
template.add("project", project)
file.templateToPdf(template)

Генерация отчета по коллизиям

• file.collisionsToPdf(CollisionsReport collisionsList) - создание PDF документа (отчета) на основе списка коллизий
• file.collisionsToPdf(CollisionsReport collisionsList, Map<String, String> params) - то же с дополнительными параметрами
• file.collisionsToPdf(TemplateService template, CollisionsReport collisionsList, Map<String, String> params) - таблица коллизий добавляется в конец текста шаблона

Параметры:

• template - шаблон (template), если таблицу коллизий необходимо добавить в конец шаблона. В вариантах без шаблона создается новый пустой файл, в который заносится таблица коллизий
• collisionsList - список коллизий. Обязательный параметр. Получить его необходимо командой bim.getCollisionsForReport()
• params - дополнительные параметры отчета:
  • pageSize - "1", "2", "3" или "4" (размер страницы А1, А2, А3, А4, альбомная ориентация); без pageSize — А4 книжной ориентации
  • fontSize - размер шрифта в pt; по умолчанию — "8"

Пример использования:

def collisionList = bim.getCollisionsForReport()
def param = [:]
param.put("pageSize", "3")
param.put("fontSize", "12")
template.add("project", bim.getProject())
file.collisionsToPdf(template, collisionList, param)

def collisionList = bim.getCollisionsForReport()
file.collisionsToPdf(collisionList)

Служебные методы

• file.saveTempTable(String tablesTempLocation) - записывает книгу в файл <uuid плагина>.xlsx в каталоге сервера tablesTempLocation и закрывает книгу

Пример использования:

file.saveTempTable(tablesTempLocation)

• file.xlsxToJSON(int page, int pageSize) → ObjectNode - преобразование первого листа текущей книги с указанной страницы (нумерация с 1), с указанным количеством строк
• file.xlsxToJSON(String tablesTempLocation, int page, int pageSize) → ObjectNode - то же для файла <tablesTempLocation><uuid плагина>.xlsx, сохраненного saveTempTable

Результат содержит headers (тексты первой строки), elements (строки страницы в виде объектов с ключами "0", "1", … по номерам столбцов) и pagination (page, pageSize, total).

Пример использования:

def json = file.xlsxToJSON(1, 50)

• file.makeGrandSmetaExelTable() → int - создает книгу XLS с трехстрочной шапкой «Гранд-Сметы» и возвращает количество строк шапки (3)

Пример использования:

file.makeGrandSmetaExelTable()

Общий пример использования интерфейса file в плагинах

Плагин создает Excel файл с расширением .xlsx. В данном файле первая строка создается в виде заголовка. Затем генерируются 11 строк с содержимым в ячейках разного формата: строка, целое число, дробное число, даты. Строка с индексом 7 замещается иным содержимым. Происходит вставка строки на 6 позицию (строки ниже сдвигаются) и удаление строки с индексом 3. После заполнения страницы данными вызывается метод автоматического выравнивания столбцов.

def start() {
    file.create("XLSX")
    file.addHeaderRow("Название", "Целое число", "Дробное число", "Дата", "Дата")
    for (def i in 0..10) {
        file.addRow("Строка №" + i, 10, 3.14, new Date(), Calendar.getInstance())
    }
    file.replaceRow(7, "Замещенная строка", 4, 5.678, new Date(), Calendar.getInstance())
    file.insertRow(6, "Вставленная строка", 1, 2.453, new Date(), Calendar.getInstance())
    file.deleteRow(3)

    file.autoSizeColumns()
}