UAP报表开发手册.doc

UAP报表开发手册

说明：本手册是对报表帮助文档的补充，在看本手册前建议先看报表的帮助文档
1. 数据源定义
报表数据源可分为实体关系查询，SQL脚本查询和自定义查询三个类型，如下图所示：

图1.1
其中数据源名称和数据源描述是为了标识数据源以及说明数据源的功能。
1.1查看或修改现有数据源
“查看或修改现有数据源”是指对原先已经创建的数据源进行修改（系统预置的数据源不允许修改），或者可以在新建报表时选择已存在的数据源，如下图：

图1.2
选“下一步”：

图1.3
则列所有已存在的数据源，选择其中一个，按“下一步”：

图1.4
功能列表是数据引擎内部使用机制，直接选“下一步”：

图1.5
这个是设置报表数据源的最后一个步骤，由于选定的数据源为自定义查询类型，所以第一个页签为自定义查询组件的相关信息（关于自定义查询组件的具体情况，请查阅本手册1.3单元）；第二个页签如下图：

图1.6
查询结果列是指该数据查询结果的具体情况，包括列名称，列的数据类型，列的区域语言描述。这些信息将构成报表格式设计时的数据源信息（关于这部分内容的详细情况请参阅UAP报表设计时帮助文档）。
另一个页签为“过滤条件设置”，如下图：

图1.7
具体包括过滤条件名称，过滤条件的区域语言描述，这个将在过滤条件的数据源下拉列表中出现，这些信息将用来设置从过滤控件读去用户输入条件值来对查询的结果进行过滤（具体情况清参阅本手册2.2单元）。
之后，选择“完成”即结束数据源定义而进入报表格式定义。
1.2实体关系查询
在图1.1步骤中选定“实体关系查询”，点击“下一步”则进入实体关系查询类型的数据源定义：

图1.8
这里必须要添加至少一个关联实体，点击“添加”，则可选择系统已经定义好的实体：

图1.9
选定实体，然后点击“确定”：

图1.10
点击“下一步”（如果选择了多个实体，则还需要定义实体之间的关系。关于如何定义一个实体以及如何定义实体之间的关系，请参阅数据引擎的相关文档）：

图1.11
接着必须添加结果列，即图1.6中的“查询结果列”。点击“添加”：

图1.12
这里弹出的列表为选定的单个实体或多个实体能查询到的所有的结果列的信息。选定需要的查询结果列后，点击“确定”：

图1.13
这个步骤中，“行数据权限”可以用来限制用户查询某些具体行数据的权限（行数据权限的设置以及其他高级功能的使用方法请查阅数据引擎相关文档）。
1.3 SQL脚本查询(含存储过程)
在图1.1步骤中选定“SQL脚本查询”，点击“下一步”则进入SQL脚本查询类型的数据源定义：

图1.14
SQL脚本查询类型又分为SQL脚本和存储过程两个类别，可通过第一个页签的左上端的下拉列表中选择相应的类别（具体如何定义两种类别请查阅数据引擎相关文档）。其他三个页签中，“查询结果列”和“过滤条件设置”已经在前面的单元中说明，此处不在详述。其中，这种数据源类型有一个“查询参数设置”页签，如下图：

图1.15
如果脚本类型中选择的是“存储过程”，则此处可以使用“刷新”按钮来获取存储过程所需要的参数；而SQL脚本类型则需要手动填写参数的信息。需要注意的是，参数的名称必须与存储过程或SQL脚本的名称完全一致。运行时查询参数的具体值来源是通过过滤条件获得的，因此查询参数需要和过滤条件绑定在一起（绑定方法请参阅本手册2.2单元）。
由于很多存储过程的数据源内部处理时使用临时表，并且将此临时表的数据作为报表的数据源的物理表，因此，为提高效率，报表系统对此种类型的存储过程将直接使用其生成的临时表进行查询，而不再另外创建查询数据的临时表。为实现上述机制，存储过程需要提供一个名称为@tablename的字符串参数，报表系统在查询过程中调用该存储过程时，将对此参数传入一个数据库物理表名，存储过程内部处理数据时，需要将处理的最终结果填写到这个物理表中。需要注意的是，这个物理表需要在存储过程内部创建，从而可达到满足存储过程自身对表结构的控制。以下为一个存储过程例子：
CREATE PROCEDURE DataSourceBankInfo
(
@tablename NVARCHAR(200)
)
AS
-- 创建临时表
DECLARE @sql NVARCHAR(1000)
SET @sql = N'CREATE TABLE '+@tablename+'
(
银行编码 NVARCHAR(10) NOT NULL PRIMARY KEY,
银行名称 NVARCHAR(100) NOT NULL
)'
EXEC (@sql)

-- 向临时填入数据
SET @sql = N'INSERT INTO '+@tablename+' VALUES(N''01'', N''中国人民银行'')'
EXEC (@sql)

报表系统将以如下方式调用此存储过程(参数串仅为例子):
EXEC DataSourceBankInfo N'the_bank_name_0923485756'

而在获取数据时，报表系统进行如下查询：
select * from the_bank_name_0923485756

1.4 自定义查询
自定义查询是指提供一个COM组件（通常为VB6.0组件）或.NET组件（通常为C#组件）来提供获取数据的方法（SQL脚本，存储过程或数据库临时表）。关于自定义查询组件的建立方法请参阅本手册3.2单元。
在图1.1步骤中选定“自定义查询”，点击“下一步”则进入自定义查询类型的数据源定义：

图1.16
其中数据服务信息指的是自定义组件的相关信息，关于自定义查询组件的建立方法请参阅本手册3.2单元。
2. 报表过滤条件
2.1 过滤条件设计
除了UAP本身单独提供了过滤条件的设计工具，报表本身也提供了专门为报表设计过滤条件的快捷方式。以下是报表设计过滤条件的入口：

图 2.1

图 2.2
点击“标准条件”进入过滤条件设计器：

图 2.3
界面说明：
是否支持高级条件：选此项后，在运行时过滤窗口中会出现“高级条件”页签，用于用户自由选择过滤条件的组合。
规则组件：此项定义由过滤控件回调的规则组件类。
是否取消二次开发：此复选项只有在以“U870”项目进入UAP时才会显示，如果被选中，那么以其它项目进入UAP的过滤设计器不能新增和删除过滤条件。
此处可新增或修改一个过滤条件。双击某个已存在的过滤条件，则进入这个条件的修改界面：

图 2.4
界面说明：
语种：设置过滤条件项显示的语种。
中文简体名称：过滤条件项的键值，唯一标识此过滤条件项，不能重复。可以以字母、数字或汉字来命名。
标题：在运行时过滤窗口中显示的文字，支持多语种设置。
编辑类型：过滤条件项的类型，分别为文本框、参照、日期、数字、枚举、SQL语句、自定义。
参照ID：当编辑类型选择参照类型后，必须选定一个参照ID。
比较符：过滤条件项比较符号。
小数位数：当编辑类型为数字类型时，此选项可以设置小数位数。
分组：为过滤条件选定一个分组，在运行时将按照分组来显示过滤条件项。
数据源：为过滤条件项选定数据源，可以下拉选择或直接手工输入。
顺序号：指定过滤条件项在运行时显示的位置，如果不输入，将自动产生。
是否常用条件：如果选中，将在运行时显示在“常用”页签中。
是否必输：如果选中，在运行时必须输入值，否则会出现提示信息。
是否区间条件：如果选中，在运行时将显示为两个输入框组合而成的形式，表示从值1到值2的意思。在运行时，用户选择或输入的不是单值，而表示一个取值范围。
是否多选：如果选中，表示此过滤条件项可以选择多个值。
允许用户修改比较符：如果选中，用户在运行时可以通过滤设功能改变比较符。
作为或条件：如果选中，在运行时将以“或”条件来组合到过滤条件生成的SQL语句中，默认是以“与”条件组合的。
参照返回字段：当编辑类型为参照类型时，此选项表示参照返回的是哪个字段的值。编码对应参照中的主键字段，名称对应参照中的描述字段。也可以手工输入要返回的字段名，一定要与参照中的字段名一致。
默认值、到：设置过滤条件项的默认值，将在运行时自动显示。如果为区间条件，可以设置“到”默认值。
修改界面的第二个页签是过滤条件项窗口枚举：

图 2.5
界面说明：
枚举(aa_enum)：指在U861中使用的枚举型，此类型是在AA_Enum数据表中定义的。枚举类型，枚举类型名称，是EnumType字段值。默认显示，在运行时当用户点击下拉按钮后显示的可供选择的项，注意是以“,”分隔的EnumCode字段的值。
枚举类型：指明在Meta库中的MetaEnumDef表中的枚举，对应MetaID字段。
枚举串：如果没有在数据库中预制枚举类型，也可以通过此项输入一个枚举串。格式为“0{#}1{##}A{#}B”，在“{##}”前的为返回值，之后的则为显示值，并且在返回值与显示值中分别以“{#}”分隔。
只能定义以上三种枚举中的一种，否则会出现提示信息。
修改界面的第三个页签是过滤条件项窗口SQL语句：

图 2.6
界面说明：
SQL文本框：在SQL文本框中输入SQL语句，可以不用加别名。
标题：在运行时中显示的列标题，标题数量与上面的SQL的字段对应，并用“,”分隔，例如“标题1,标题2”。
返回字段：用此字段的值构成过滤控件返回调用者的过滤SQL语句。
显示字段：显示在运行时过滤窗口中的值。
在U870中，SQL语句类型的过滤条件主要为兼容以前版本，所以如果在U870中新建过滤条件时，请不要选用SQL语句类型，而改用参照类型。
修改界面的第四个页签是过滤条件项窗口SQL语句：

图 2.7
属性说明：
参照样式：当编辑类型选择为参照类型时，可以指定参照的样式，分别为弹出式和下拉式，默认为弹出式。
关于过滤最后值得特别指出的是，过滤条件之间可控制相互关系，例如两个过滤条件都有参照，则可控制其中一个过滤条件的参照取值范围由另一个过滤条件的取值来决定。此外还存在其他相关控制行为，这些功能都是通过规则组件来实现的。关于规则组件的详细实现，请参阅过滤条件的相关文档。
2.2 过滤条件与数据源的关系
此处主要说明如何把过滤条件跟数据源关联起来，以达到由用户输入来实现查询不同数据的目的。
对于实体关系类型的数据源，只要在过滤条件的基本属性页中选择数据源的相应列就能实现，如下图：

图 2.8
用户就可以在查询报表时进行过滤：

图 2.9
对于SQL脚本类型的数据源，无论是简单的sql脚本类型还是存储过程，都是通过将其参数与过滤条件进行绑定来实现的。如下图：

图 2.10
过滤条件与sql脚本或存储过程的联系可分别有两种方式：
1.从过滤条件传入单个参数。假如sql脚本或存储过程中有两个参数分别为：@planid和@depcode，则必须要在数据源设计时的“查询参数设置”页签中分别为每一个参数设置其相关信息。然后再设计过滤条件：

图 2.11
此处需要注意的是，“名称”必须以这样的规则命名：“查询参数设置”的参数为@pram，则“名称”为parm，两者之间相差一个符号“@”，并且同时可在数据源下拉列表里指定其对应某个数据源(数据源的下拉列表是由数据源设计的“过滤条件设置”页签中的内容决定的)。需要注意：此处过滤条件名称的命名方式与其指定哪数据源项没有必然的联系，各有各的作用，具体请参照方式2的例子。
2.整体参数传入。如果SQL脚本或存储过程提供了一个名称为@filterstring字符串参数，则调用时此参数的内容为组织好的的一个条件SQL串，其包括的组织项为上述方式1中指定的数据源项，其具体组织成的内容请参阅下述例子。此种方式的目的主要为了方便数据源提供者使用全部的过滤条件。
以下为一个存储过程例子（假设使用以上的参数设置）：
存储过程为：
Example_Procedure
(
@planid nvarchar(10),
@depcode nvarchar(10),
@filterstring nvarchar(200)
)
如果查询报表时的输入为：
planid 1000 depcode AZ786
则报表系统将以如下方式调用存储过程：
exec Example_Procedure
'1000',
'AZ786',
'1=1 and planid=''1000'' and depcode=''AZ786'''
数据源设计者可根据此种调用方式来设置参数的使用情况，其中需要指出的是，@filterstring中planid=''1000''的planid是数据源设计的“过滤条件设置”页签中的“过滤条件名称”，设计者需要正确的设置此名称才能使@filterstring在数据源内部能够正确使用。同时可归纳出，方式1中“名称”的命名影响存储过程具体参数的绑定，而数据源的指定影响@filterstring中具体内容的拼接。

3. 报表系统API
3.1 自定义报表查询入口
所谓自定义报表查询入口指的是用UAP设计了一张自定义报表，除了默认的查询入口：门户->视图->我的报表->自定义报表，另外为此报表设置单独的菜单节点来进行查询。只要在此节点的点击事件处理函数中调用报表系统的以下接口就可实现：
A.
Public Function OpenReport( _
sReportID As String, _
objU8Login As Object, _
Optional subid As String = "", _
Optional rawfilter As Object = Nothing) As Boolean

B.
Public Function OpenReportNoneFilterUI( _
sReportID As String, _
objU8Login As Object, _
Optional subid As String = "", _
Optional rawfilter As Object = Nothing) As Boolean

接口功能及使用说明：
这两个接口是对象ReportService.clsReportManager中的函数;
需要引用组件：
ReportService.dll
UFIDA.U8.UAP.Services.ReportFilterService.tlb
这两个接口的功能是打开一张报表，两个接口的差异在于前者在打开报表之前会先显示过滤界面，而后者不会（例如在使用联查报表的时候有时不需要进行过滤）。此接口在业务组在其需要打开一张报表时调用。

参数介绍：
sReportID：
报表的ID，即将要打开的报表标识。
objU8Login：
U8的Login对象，注意：这个对象必须是COM封装的Login。
subid：
报表所属的子产品号，这个参数是可选的。注意：当指定了此参数，接口会在随后的处理中按照subid[__]sReportID的规则拼接成真正的报表ID。
rawfilter：
可选过滤条件对象（UFGeneralFilter.FltSrv或自定义的过滤条件对象），此对象中必须是ISelfFilter（见第四个接口）的一个实现。这个参数通常报表的自定义行为（如联查）时，需要有过滤的情形时会使用到。
至于怎么在U8中设置自己的菜单节点，请参阅U8门户相关文档。
3.2 自定义数据源组件
报表的自定义数据源是指单独写一个组件来提供报表数据，这种数据源实现方法的优点强大的数据处理能力，这是其他类型的数据源所不具备的。实现方法为：
组件中必须实现以下接口:
public interface IGetSql
{
void GetSql(IFilterArgs e);
}

接口功能及使用说明：
此接口为报表提供自定义数据源。组件的提供方式为首先提供一个实现IGetSql的组件（COM组件只需有一个声明相同的GetSql函数的类即可），之后将其绑定到报表的数据源（具体方法是请参考本接口示例）。组件的工作方式为报表系统会在展现报表的过程中实例化一个此种类型的对象，通过调用GetSql函数来获取数据源。

参数介绍：
IFilterArgs参数是UFIDA.U8.UAP.Services.ReportFilterService.tlb中的类型，在报表系统调用自定义数据源组件的时通过此参数将组件需要的环境信息传入，而自定义数据源组件则将其处理结果通过此参数返回给报表系统。

IFilterArgs中包含的常用接口：
IFilterArgs.login：
U8的Login对象
IFilterArgs.RawFilter：
过滤对象
IFilterArgs.DataSource.Type：
组件数据源返回类型，其值与对应类型为
0：SQL脚本
1：存储过程
2：临时表
其默认值为2
IFilterArgs.DataSource.Sql：
SQL脚本或临时表名称
IFilterArgs.DataSource.StoreProcName：
存储过程名称
示例：
(1)以下提供一个名为CustomDataSample的vb6.0的dll，此组件中定义一个名为customData.cls类，其代码如下（IFilterArgs的）：
Public Sub GetSql(e As IFilterArgs)
e.DataSource.sql = “select * from AA_Bank”
e.DataSource.Type = 0
End Sub

构造好组件之后，需要将组件绑定到报表的数据源，绑定方法如下：
假设组件名称为：DataEngine.dll,而实现IGetSql的类型名称为：Engine
VB6.0组件的绑定方法：(注意：COM需要注册，不要求具体存放目录，一般推荐存放目录为：..U8SOFT\ufcomsql\)

图 2.12
C#组件的绑定方法：(注意：.NET组件不需要注册，但存放目录必须是：..U8SOFT\UAP\)

图 2.12
3.3 自定义行为组件
自定义行为是指在报表查询结束后，设计者提供额外的功能来进行相关处理，比如联查功能等。方法是实现以下接口：
public interface IExecute
{
void Execute(IActionArgs e);
}

接口功能及使用说明：
此接口用来完成报表自定义行为的业务操作。组件的提供方式与IGetSql接口类似，不同的是其绑定到报表系统的过程（示例将详细说明）。组件的工作方式为在自定义行为绑定到报表系统之后，报表展现界面的右键菜单中将相应的子菜单，触发此子菜单后报表系统将实例化此组件实现IExecute类型的一个对象，并调用此对象上的Execute方法。

参数介绍：
IActionArgs是在进行自定义行为的时候数据交互的媒介，IActionArgs中的常用参数:
IActionArgs.ReportID:
当前操作的报表ID
IActionArgs.Login:
U8的Login对象
IActionArgs.RelateData:
当前报表的相关数据对象，通过此对象中的接口GetData可获得相关的数据
IActionArgs.CurrentColumnName:触发自定义行为时报表所处的焦点行名称
IActionArgs.FltArgs:
IFilterArgs对象

自定义行为绑定到报表系统例子：(假设组件名为ExcuteSample，类型名为clsExc，定义方法参考IGetSql的示例)

图 2.13
在报表设计界面点击”自定义行为”的按钮，将打开自定义行为的定义界面：

图 2.14
点击”新增”:

图 2.15
设定ActionClass为”ExcuteSample.clsExc”,
Caption为”自定义例子”,点击”确定”即完成绑定操作。
保存之后打开报表，其右键菜单”其他”的子菜单中便出现定义的新菜单，

图 2.16
点击此子菜单，便会调用类型clsExc中的Execute方法。
3.4 自定义过滤
自定义过滤是指设计者可以自行构造一个过滤组件来实现报表的过滤，而不使用U8自身的过滤控件。实现方法是组建中实现以下接口：
public interface ISelfFilter
{
void ShowFilter(IFilterArgs e);
}
接口功能及使用说明：
为报表提供自定义的过滤条件界面。组件提供方式与前述相关组件类似。组件的工作方式为将实现ISelfFilter的类型的一个实例作为OpenReport或OpenReportNoneFilterUI的第四个参数传入，则在进行报表展现之前，报表系统将会调用此实例的ShowFilter方法，自定义过滤的结果使用e参数返回报表系统。

参数介绍：
IFilterArgs参数请参考IGetSql说明。

自定义过滤组件绑定到报表的方法例子(假设要绑定的组件名为CustomFilter，实现ISelfFilter的类型为clsFilter)：
在UAP中”报表定义”窗体的工具栏的”查询条件”按钮中选择”自定义条件”，或在”报表定义”窗体的右键菜单的”查询条件”菜单中选择”自定义条件”，如图：

图 2.17

图 2.18

之后再打开的定义窗体中输入组件信息，如：

图 2.19

点击”确定”即可完成绑定操作。