动态报表API接口

动态报表API接口用于实现动态生成、修改报表定义对象，利用该对象可以生成报表、导出报表、保存对应对象到报表支撑库；也可以通过报表定义ID将已有的报表定义文件读取为对象并对该对象进行修改。

动态报表API接口多用于报表定义不确定情况下，其中包括报表行、列不固定，报表类型不固定、报表数据源不固定等场景，如即时报表。在多数情况下使用动态报表API接口创建报表是不需要报表定义文件(*.rdx)。

主要接口如下：

com.neusoft.report.common.design.DesignReportManager
com.neusoft.report.common.design.define.DesignCell
com.neusoft.report.common.design.define.DesignCells
com.neusoft.report.common.design.define.DesignColumn
com.neusoft.report.common.design.define.DesignDiagonalCell
com.neusoft.report.common.design.define.DesignGraphCell
com.neusoft.report.common.design.define.DesignPageHeaderFooter
com.neusoft.report.common.design.define.DesignPageSetup
com.neusoft.report.common.design.define.DesignPictureCell
com.neusoft.report.common.design.define.DesignReport
com.neusoft.report.common.design.define.DesignRow
com.neusoft.report.common.design.define.DesignTextCell

1 使用步骤

通过调用动态报表API生成报表定义对象具体步骤如下：

调用DesignReportManager类的createDesignReport方法，该方法用于创建一个报表对象DesignReport；
调用DesignReportManager类的调用createDesignText方法，该方法用于创建一个报表文本单元格对象DesignTextCell；
调用1中生成的DesignReport对象的addRow方法创建报表中的一个行对象DesignRow；
调用 3中生成的DesignRow对象的setCell方法，可以将2中生成的DesignTextCell对象设置进入到行对象中；
通过类似3、4中的方法，可以设置报表定义对象中的其它类型单元格；

2 DesignReportManager接口

2.1 简介

DesignReportManager是动态API实现的入口，通过该入口可以获取创建动态报表需要的所有对象。

2.2 方法说明

public static DesignReportManager getInstance()

得到DesignReportManager类的实例对象；
public DesignReport createDesignReport()

创建一个DesignReport接口对象；
public DesignReport createDesignReport(int row, int column)

创建一个DesignReport接口对象，执行报表的初始行数、列数；
public DesignTextCell createDesignText()

创建一个文本类型单元格；
public DesignPictureCell createDesignPicture()

创建一个图片类型单元格；
public DesignGraphCell createDesignGraph(int type)

创建一个图表单元格；
public DesignDiagonalCell createDesignDiagonal()

创建一个包含斜线表头的单元格；
public DesignReport loadDesignReport(String id)

通过报表ID创建一个DesignReport接口对象。
public int saveDesignReport(DesignReport report, String parentId)

将DesignReport接口对象保存到支撑库目录ID为parentId的目录下；
public Report generateReport(DesignReport report, Map context)

通过DesignReport对象生成一个Report报表实例。

3 DesignReport接口

3.1 简介

DesignReport是报表定义接口，通过该接口可以操作一个报表定义。

3.2 方法说明

public void setName(String name)

设置报表名称；

name：报表名称；

返回值：报表名称；
public String getName()

读取报表名称；

返回值：报表名称；
public void setDescription(String desc)

设置报表描述；

desc：报表描述；
public String getDescription()

读取报表描述；

返回值：报表描述；
public void setAuthor(String author)

设置作者；

author：作者名；
public String getAuthor()

读取作者；

返回值：作者名；
public void setCategory(String category);

设置报表分类；

category：报表分类；
public String getCategory()

读取报表分类；

返回值：报表分类；
public String getTemplateID()

获得该模板的ID；

返回值：模板ID；
public DesignPageSetup getPageSetup()

获得页面设置对象，以进行页面设置；

返回值：页面设置对象；
public void addSQLSource(String dsName, String datasource, String statement)

添加关系数据库SQL来源数据集；

dsName：数据集名称；

datasource：数据源名；

statement：SQL查询语句
public String getSQLSourceName(String dsName)

读取数据源名；

dsName：数据集名称；

返回值：数据源名；
public String getSQLSourceStatement(String dsName)

读取数据集的SQL语句；

dsName：数据集名；

返回值：SQL语句；
public String[] getSQLSources()

读取已定义的数据集；

返回值：已定义的数据集名；
public void setLinage(int linage)

设置报表每页展现行数；

linage：每页行数；
public DesignRow addRow()

在报表末尾添加一个行；

返回值：添加的行；
public DesignRow getRow(int row)

读取指定的一行；

row：行号；

返回值：相应的行；
public void removeRow(int row)

删除指定的一行；

row：行号；
public void swapRow(int row1, int row2)

交换两行位置；

row1：行1；

row2：行2
public int getRowCount()

获得当前总行数；

返回值：当前行数；
public DesignColumn addColumn()

在报表末尾添加一个列；

返回值：添加的列；
public DesignColumn getColumn(int col)

读取指定的一列；

col：列号；

返回值：相应的列；
public void removeColumn(int col)

删除指定的一列；

col：列号；
public void swapColumn(int col1, int col2)

交换两列位置；

col1:列1；

col2:列2；
public int getColumnCount()

获得当前总列数；

返回值：当前列数；
public void setCell(int row, int col, DesignCell cell)

设置一个单元格于指定坐标；

row：行坐标；

col：列坐标；

cell：单元格对象。

4 DesignPageSetup接口

4.1 简介

DesignPageSetup是报表的页面设置接口，其中包含纸张类型、页边距、页眉页脚等相关功能。

4.2 方法说明

public void setPageVertical()

定义页面为垂直布局；
public void setPageHorizontal()

定义页面为水平布局；
public boolean isPageVertical()

判断报表页面是否为垂直布局；
public boolean isPageHorizontal()

判断报表页面是否为水平布局；
public void setPaper(String type, double width, double height)

设置页面纸张类型以及纸张尺寸；

type：纸张类型，如A4、B5等；

width：纸张宽度，单位为毫米；

height：纸张高度，单位为毫米；

【注意】width、height与纸张方向相关，width始终代表纸张的左右方向的长度，height始终代表纸张垂直方向的长度。即如果修改纸张方向，需要交换width和height的值。

public double getPaperHeight()

读取纸张高度；
public double getPaperWidth()

读取纸张宽度；
public String getPaperType()

读取纸张类型；
public void setTopMargin(float margin)

设置纸张的上边距；
public void setRightMargin(float margin)

设置纸张的右边距；
public void setLeftMargin(float margin)

设置纸张的左边距；
public void setBottomMargin(float margin)

设置纸张的的下边距；
public float getTopMargin()

读取纸张的上边距；
public float getRightMargin()

读取纸张的右边距；
public float getLeftMargin()

读取纸张的左边距；
public float getBottomMargin()

读取纸张的下边距；
public void setPageHeader(DesignCell leftcell, DesignCell midcell, DesignCell rightCell)

直接定义页眉内容，页眉使用默认设置；

leftcell：页面左侧内容单元格；

midcell：页眉中间内容单元格；

rightCell：页眉右侧内容单元格；
public void setPageFooter(DesignCell leftcell, DesignCell midcell, DesignCell rightCell)

直接定义页脚内容，页脚使用默认设置；

leftcell：页脚左侧内容单元格；

midcell：页脚中间内容单元格；

rightCell：页脚右侧内容单元格；
public DesignPageHeaderFooter getPageHeader()

获得页眉对象，进行页眉及其内容的设置；

返回值：页眉对象；
public DesignPageHeaderFooter getPageFooter()

获得页脚对象，进行页脚及其内容的设置；

返回值：页脚对象。

5 DesignPageHeaderFooter接口

5.1 简介

DesignPageHeaderFooter中显示方式常量的定义

常量含义	常量名称
全部显示	SHOWTYPE_ALL
偶数页显示	SHOWTYPE_EVEN
奇数页显示	SHOWTYPE_ODD
首页显示	SHOWTYPE_FIRST
尾页显示	SHOWTYPE_LAST

public void setShowType(int showType)

设置显示方式；

showType：显示方式常量；
public int getShowType()

读取显示方式；

返回值：显示方式常量；
public void setMargin(double margin)

设置位置边距；

Margin：边距值；
public double getMargin()

读取位置边距；

返回值：边距值；
public void setHeight(double height)

设置高度；

Height：高度值；
public double getHeight()

读取高度；

返回值：高度值；
public void setCells(DesignCell[] cells)

设置一组单元格于该页眉或页脚，仅会使用其中的前3个；

返回值：DesignCell数组；
public DesignCell getCell(int index)

读取页眉页脚中的某个单元格；

Index：单元格位置，从1开始至3；

返回值：相应单元格。

6 DesignCell接口

6.1 简介

DesignCell是报表所有类型单元格实现的接口，已知单元格类型包括图片单元格（DesignPictrueCell）、图表单元格（DesignGraphCell）、斜线表头单元格（DesignDiagonalCell）和文本单元格（DesignTextCell）。

6.2 方法说明

public String getTopMaster()

读取列依赖单元格格名称；
public String getLeftMaster()

读取行依赖单元格名称；
public int getRowSpan()

读取行合并；
public int getColSpan()

读取列合并；
public String getLink()

读取单元格超链接；
public void setTopMaster(String topmaster)

设置列依赖；
public void setLeftMaster(String leftmaster)

设置行依赖；
public void setRowSpan(int rspan)

设置行合并，会合并该格的下方单元格；

rspan：合并到一起的单元格数；
public void setColSpan(int cspan)

设置列合并，会合并该格的右方单元格；

cspan：合并到一起的单元格数；
public void setLink(String link)

设置超链接；

link：超链接，可以为公式串。

7 DesignTextCell接口

7.1 简介

DesignTextCell文本类型单元格接口；

7.2 方法说明

DesignTextCell中扩展方向常量的定义：

常量含义	常量名称
不扩展	NO_EXTEND
横向扩展	HORIZONTAL_EXTEND
纵向扩展	VERTICAL_EXTEND

DesignTextCell中对齐方式常量的定义：

常量含义	常量名称
水平对齐方式-居左	LEFT_ALIGN
水平对齐方式-居中	CENTERH_ALIGN
水平对齐方式-居右	RIGHT_ALIGN
垂直对齐方式-靠下	BOTTOM_ALIGN
垂直对齐方式-居中	CENTERV_ALIGN
垂直对齐方式-靠上	TOP_ALIGN

DesignTextCell中单元格文本格式的常量定义：

常量含义	常量名称
数值	FORMAT_TYPE_NUMERICAL
货币	FORMAT_TYPE_CURRENCY
日期	FORMAT_TYPE_DATE
百分数	FORMAT_TYPE_PERCENTAGE
分数	FORMAT_TYPE_FRACTION
科学计数法	FORMAT_TYPE_SCIENCE
特殊	FORMAT_TYPE_SPECIAL

public void setCaption(String caption)

设置单元格标题；
public String getCaption()

读取单元格标题；
public void setValue(String value)

设置单元格的值；
public String getValue()

读取单元格的值；
public void setAlign(int hAlign, int vAlign)

设置单元格文字的对齐方式；

hAlign：水平对齐方式，参见对齐方式的常量定义；

vAlign：垂直对齐方式，参见对齐方式的常量定义；
public void setExtend(int extend)

设置扩展方向；

extend：扩展方向常量；
public int getExtend()

获取扩展方向
public void setFormat(int type, String format)

设置单元格格式

type：单元格格式类型；

format：指定单元格的格式串；
public int getFormatType()

读取单元格类型；
public String getFormatString()

读取单元格格式串；
public void setFont(Font font)

设置单元格文字字体；

font：字体；
public void setFont(Font font, boolean underline, boolean strikeout)

设置单元格字体；

font：字体对象；

underline：下划线；

strikeout：中划线；
public Font getFont()

读取单元格字体；

返回值：字体对象
public void setBgColor(Color color)

设置单元格背景色；

color：单元格背景色；
public void setBgColor(String formula);

通过公式设置单元格背景色；

formula：公式字符串；
public Color getBgColor();

读取单元格背景色；

返回值：单元格背景色；
public void setFgColor(Color color)

设置文字颜色；

color：单元格文字颜色
public void setFgColor(String formula)

通过公式设置文字颜色；

formula：文字颜色公式字符串；
public Color getFgColor()

读取单元格文字颜色。

8 DesignPictureCell接口

8.1 简介

DesignPictureCell是图片类型单元格接口。

8.2 方法说明

public void setFilePath(String path)

设置图片路径；

path：图片路径，参数中可能为常量，也可能为字符串公式，参考《UniEAP Report公式查询手册》中的FilePicture公式；
public String getFilePath()

读取图片路径。

9 DesignGraphCell接口

9.1 简介

DesignGraphCell是图表类型单元格接口。

9.2 方法说明

DesignGraphCell中图表类型常量的定义：

常量含义	常量名称
2D饼图	PIE2DCHART
3D饼图	PIE3DCHART
2D柱状图	COLUMN2DCHART
3D柱状图	COLUMN3DCHART
2D条形图	BAR2DCHART
3D条形图	BAR3DCHART
2D线图	LINE2DCHART
3D线图	LINE3DCHART
2D面积图	AREACHART

DesignGraphCell中图例位置常量的定义：

常量含义	常量名称
不扩展	LEGEND_RIGHT
横向扩展	LEGEND_BOTTOM

DesignGraphCell中文字旋转方向量的定义：

常量含义	常量名称
默认正常旋转方向（无旋转）	ROTATION_DEFAULT
倾斜旋转（45度）	ROTATION_SLANT
垂直旋转（90度）	ROTATION_VERTICAL

DesignGraphCell中文本格式化类型的定义：

常量含义	常量名称
常规	FORMAT_TYPE_GENERAL
数值	FORMAT_TYPE_NUMERICAL
货币	FORMAT_TYPE_CURRENCY
百分数	FORMAT_TYPE_PERCENTAGE

public void setGraphType(int type)

更改图表的类型；

type：代表图表类型的常量；
public int getGraphType()

获得该图表的类型；

返回值：代表图表类型的常量；
public void setCategoryValue(String value)

定义分类值；

Value：分类值；
public void setCategoryCaption(String caption)

定义分类标题；

caption：分类标题；
public void addSeries(String name, String value)

添加图表系列，该系列会缺省关联到主Y轴；

name:系列名；

value:系列值；
public void setSeriesAxis(int index, String axisName)

设置系列关联轴；

index：系列的序号，按照添加的顺序从0开始；

axisName：关联的坐标轴名称，参见常量标识；
public void setSeriesColor(int index, Color color)

设置系列的颜色；

index：系列的序号，按照添加的顺序从0开始；

color：设置的颜色；
public void setxAxisCaption(String caption)

设置X轴标题；

caption：标题；
public void setxAxisFont(Font font)

设置X轴字体；

Font：字体
public void setxAxisLabelRotation(int rotation)

设置X轴标签旋转方向；

rotation：X轴标签旋转方向，可以为正常、倾斜或垂直旋转，参见常量定义；
public void setxAxisLabelPadding(int padding)

设置X轴标签位置；

Padding：位置填充量；
public void setYAxisCaption(String caption)

设置Y轴标题；

Caption：标题；
public void setYAxisFont(Font font)

设置Y轴字体；

Font：字体；
public void setYAxisTitleRotation(int rotation)

设置Y轴标题的旋转方向；

rotation：Y轴标题旋转方向，可以为正常或垂直旋转，参见常量定义；
public void setYAxisDataFormat(int formatType, String formatString)

设置Y轴的数据格式；

formatType：格式类型，参见常量定义；

formatString：格式串；
public void setSYAxisCaption(String caption)

设置从Y轴标题；

Caption：标题；
public void setSYAxisFont(Font font)

设置从Y轴字体；

font：字体；
public void setSYAxisDataFormat(int formatType, String formatString)

设置从Y轴的数据格式；

formatType：格式类型，参见常量定义；

formatString：格式串；
public void setLegendPosition(int position)

更改图例位置；

Position：图例位置，参见常量定义；
public void addTrendLine(String name, double value)

添加一条趋势线；

Name：名称；

value：值；
public void setTrendLineColor(int index, Color color)

设置趋势线颜色；

index：趋势线的序号，按照添加的顺序从0开始；

color：颜色；
public void setTrendLineAxis(int index, String axisName)

设置趋势线；

index：趋势线的序号，按照添加的顺序从0开始；
public void setTitle(String title)

定义图表标题；

title：标题；
public void setTitleFont(Font font)

定义图表标题字体；

font：字体；
public void setSubTitle(String title)

定义副标题；

title：副标题；
public void setSubTitleFont(Font font)

定义副标题字体；

font：字体；
public void setShowValues(boolean show)

设置是否显示数据值；

show：true为显示， false不显示；
public void setBgColor(Color color)

设置图表背景颜色；

color：颜色。

10 DesignDiagonalCell接口

10.1 简介

DesignDiagonalCell是斜线表头类型单元格接口。

10.2 方法说明

public void setText(String text1, String text2)

设置单斜线表头内容；

text1：单元格左侧分割部分文字；

text2：单元格右侧分割部分文字；
public void setText(String text1, String text2, String text3)

设置双斜线表头内容；

text1：单元格左侧分割部分文字；

text2：单元格中间分割部分文字；

text3：单元格右侧分割部分文字
public void setFont(Font font)

设置单元格文字字体；

font：字体；
public void setFgColor(Color color)

设置单元格文字颜色；

color：颜色；
public void setBgColor(Color color)

设置单元格背景色；

color：颜色。

11 DesignCells接口

11.1 简介

DesignCells是一组单元格的集合，为报表行（DesignRow）、报表列（DesignColumn）需要实现的接口。

11.2 方法说明

public void setCell(int index, DesignCell cell)

设置一个单元格；

index：待放置的位置；

cell：待设置的单元格对象；
public void setBgColor(Color color)

设置背景色，应在完成该组单元格设置后使用；

color：背景色；
public void setBgColor(String formula)

设置背景色，应在完成该组单元格设置后使用；

formula:背景色颜色公式；
public void setFgColor(Color color);

设置前景色，应在完成该组单元格设置后使用；

color：前景色；
public void setFgColor(String formula);

设置前景色，应在完成该组单元格设置后使用；

formula：前景色颜色公式；
public DesignCell getCell(int index)

获得单元格；

index：指定的位置；

返回值：单元格对象；
public void setCategory(int category)

设置单元格区域类型；

category：区域类型常量，如数据区等，参见相应的常量定义；
public int getCategory()

获得区域类型；

返回值：区域类型常量。

12 DesignColumn接口

12.1 简介

DesignColumn是报表列接口。

12.2 方法说明

public void setWidth(float width)

设置宽度；

width：宽度值
public float getWidth()

读取宽度；

返回值：宽度值；
public void setTopMaster(String master)

设置列依赖；

master：列依赖单元格坐标；
public String getTopMaster()

获得列依赖；

返回值：列以来单元格坐标；
public int getColumnNo()

获得当前列号；

返回值：当前列号。

13 DesignRow接口

13.1 简介

DesignRow是报表行接口。

13.2 方法说明

public void setHeight(float height)

设置高度；

height：高度值；
public float getHeight()

读取高度；

返回值：高度值；
public void setLeftMaster(String master)

设置行依赖；

master：行依赖单元格坐标；
public String getLeftMaster()

获得行依赖；

返回值：行依赖单元格坐标；
public int getRowNo()

取得当前行号；

返回值：当前行。

14 通过动态报表API定义报表的样例

package com.neusoft.report.sample.reportdef;
import java.awt.Color;

import javax.servlet.http.HttpServletRequest;

import com.neusoft.report.design.DesignReportManager;
import com.neusoft.report.design.define.DesignGraphCell;
import com.neusoft.report.design.define.DesignReport;
import com.neusoft.report.design.define.DesignRow;
import com.neusoft.report.design.define.DesignTextCell;
public class ExampleRequestReportBuilder {
    public DesignReport buildDesignReport(HttpServletRequest request) {
        // 读取参数
        String dsName = request.getParameter("dsname");
        dsName = dsName == null ? "ds1" : dsName;
        String sql = request.getParameter("sql");
        String datasource = request.getParameter("datasource");
        String name = request.getParameter("name");
        int cols = Integer.parseInt(request.getParameter("col"));
        DesignReport reportDef = DesignReportManager.getInstance()
                .createDesignReport(2, cols);
        reportDef.setName(name == null ? "TestReport" : name);

        reportDef.addSQLSource(dsName, datasource, sql);
        DesignTextCell text = null;

        DesignRow row = reportDef.getRow(1);
        row.setHeight(40);
        for (int i = 1; i <= cols; i++) {
            text = DesignReportManager.getInstance().createDesignText();
            text.setValue("第" + String.valueOf(i) + "列");
            row.setCell(i, text);
        }
        row.setCategory(DesignRow.CATEGORY_HEADER);
        row.setBgColor(new Color(128, 255, 128, 128));// 后设置行列颜色

        row = reportDef.getRow(2);
        text = DesignReportManager.getInstance().createDesignText();
        text.setValue("=select('" + dsName + "', 1)");
        text.setExtend(DesignTextCell.VERTICAL_EXTEND);
        row.setCell(1, text);

        for (int j = 2; j <= cols; j++) {
            text = DesignReportManager.getInstance().createDesignText();
            text.setValue("=get('" + dsName + "', " + String.valueOf(j) + ")");
            text.setLeftMaster("a2");
            row.setCell(j, text);
        }

        DesignRow newRow = reportDef.addRow();
        newRow.setCategory(DesignRow.CATEGORY_FOOTER);
        newRow.setHeight(100);
        DesignGraphCell graph = DesignReportManager.getInstance()
                .createDesignGraph(DesignGraphCell.BAR2DCHART);
        graph.addSeries("Series1", "=list(1,2,3,4,5)");
        graph.setCategoryValue("=list('A','B','C','D','E')");
        graph.setColSpan(cols);
        newRow.setCell(1, graph);
        DesignTextCell leftCell = DesignReportManager.getInstance()
                .createDesignText();
        leftCell.setValue("左页眉页脚");
        DesignTextCell midCell = DesignReportManager.getInstance()
                .createDesignText();
        midCell.setValue("中页眉页脚");
        DesignTextCell rightCell = DesignReportManager.getInstance()
                .createDesignText();
        rightCell.setValue("右页眉页脚");
        reportDef.getPageSetup().setPageHeader(leftCell, midCell, rightCell);
        reportDef.getPageSetup().setPageFooter(leftCell, midCell, rightCell);

        return reportDef;
    }

}

本示例代码更多内容请参见UniEAP Report相关发布包内样例演示。

15 报表定义对象持久化

调用com.neusoft.report.common.entity.def.parser.SDLParserFacade接口的 public static ReportDefineParser getReportDefineParser()方法，获得报表定义持久化对象ReportDefineParser；
调用ReportDefineParser的 public String parse(DefineReport define, String rid, String caption)或者 public String parse(DefineReport define)方法将报表定义生成为报表定义文件的xml格式字符串；
调用3.3.2.4节中介绍的public boolean newDefineXML(String id, String define)方法将报表定义xml存入报表支撑数据库中。