a7rexcel — Документация

Excel-шаблоны отчетов. Структура, разметка

Шаблон отчета представляет собой один лист Microsoft Excel, содержащий уже готовые части и разметку отчета.

Первая колонка содержит текстовое имя бэнда (секции), причем если бэнд имеет больше одной строки в высоту, то его имя должно повторяться на каждой строке. Объединение ячеек для этой колонки использовать нельзя. После построения отчета эта колонка останется пустой, поэтому ее можно сделать очень узенькую, либо вообще скрыть — на работоспособность это не повлияет.

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

Что нужно знать для построения отчета

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

В начале построения отчета вызываем метод OpenTemplate(FileName: string), с указанием файла-шаблона. Далее происходит наполнение листа бэндами и данными, последовательными вызовами методов PasteBand и SetValue. В конце построения вызываем Show() и пользователю открывается экселевский отчет, в режиме «только чтение», это сделано для того чтобы он случайно не перезаписал шаблон. При попытке сохранить его, эксель предложит выбрать место сохранения и имя файла.

Метод PasteBand(Name: string) — добавляет на лист нужный нам бэнд (бэнд — это одна или несколько строк, имеющих в первой ячейке одно и тоже имя).

Метод SetValue(VarName: string; Value: Variant) находит в последнем установленном бэнде переменную с именем VarName и заменяет это имя на его значение Value. Этот метод можно вызывать столько раз, сколько предполагается различных переменных в нужном бэнде. Для строк длиной более 255 символов используйте SetValueAsText. Для обхода дурной привычки Excel преобразовывать данные вида «10.10» или «9/10″ в дату следует имя переменной в ячейке сцепить с текстом, например с предваряющим пробелом: » #D#». В случае если это не приемлемо можно использовать метод SetValueAsText.

Дополнительные возможности при построении отчетов

Метод SetValueAsText(varName: string; Value: string) работает медленнее метода SetValue и не способен найти имя переменной внутри текстовой строки, но нужен для обхода дурной привычки Excel автоматически форматировать текст в виде даты там где этого не нужно. Например значение «10.10» подменяется экселем на «10 окт.», а этот метод позволяет этого избежать.

Метод SetValueF(VarName: string; Value: Variant) служит для вставки значения в форматированную строку ячейки, когда нужно сохранить формат части строки (например ячейка выглядит так: «дата:#DATE#» — в этом случае жирный курсив сохранится).

OpenTemplate есть вариант вызова с указанием нужно ли давать пользователю видеть как в экселе происходит заполнение отчета, при этом если параметр равен Visible=True то окно прогресса не показывается.

OpenWorkSheet(Name: string) переключает вывод отчета на новый лист. Используется если вам нужно делать много-листовые отчеты.

SetSumFormula(VarName: string; FirstLine, LastLine: Integer) вставляет в ячейку VarName формулу суммирования по строкам FirstLine..LastLine (по типу «=СУММ(C10:C25)»). Значения FirstLine и LastLine нужно сохранить предварительно самостоятельно, взяв номер строки из переменной CurrentLine в начале и в конце вывода нужной секции.

SetColor(VarName: string; Color:Variant) устанавливает цвет ячейки, либо очищает если Color=null;

Для всего что не предусмотрено можно пойти путем прямого управления экселем, например:

Закрепить область можно таким кодом:

  Rep.TemplateSheet.Cells[3, 2].Select;
  Rep.Excel.ActiveWindow.FreezePanes := True;

Работа с комментариями:

SetComment(VarName: string; Value: Variant) — позволяет установить комментарий для ячейки с меткой VarName.

GetComment(VarName: string): string — позволяет прочитать содержимое комментария над ячейкой с меткой VarName.

GetAndClearComment(VarName: string): string — тоже что и предыдущий вариант, но после чтения комментарий уничтожается. Это удобно если в комментарии нужно разместить какие-либо контекстные параметры, видеть которые конечному пользователю в отчете не нужно.

Важно помнить, что пользоваться этими функциями нужно ДО заполнения ячейки с комментарием, иначе процедура не найдет метку. Пример использования есть в прилагаемом демонстрационном приложении.

Поддерживаемые версии Excel и Delphi:

Не стоит пугаться, увидев в папке с компонентом только версию под Delphi 7 и Delphi XE2 — думаю при установке компонента и на другие версии проблем не возникнет.

Работа компонента была протестирована на компьютерах с установленным Microsoft Office 2003, 2007, 2010, 2013, но к сожалению без установленного офиса вывод информации в Excel работать не будет!