当需要把确定类型的数据传递到报表时 (例如把特定值传递到它的 筛选字符串 或 计算字段)，可以使用 参数，从而避免编写任何代码。

XtraReport 类公开了 XtraReport.Parameters 属性，此属性用于访问其 Parameter 对象的集合。

同时，XtraReport.RequestParameters 属性指定是否只在提交了所有参数值之后才创建报表文档，还是使用默认的参数值立即创建报表文档。

注意
每个参数都是一个 组件，意思是可以通过 Modifiers 和 GenerateMember 属性，来控制在派生报表和报表外部是否可以访问它。

可以创建标准类型的参数 (Type 枚举值) 或者 自定义类型的参数 (例如枚举、或 XPCollection 对象等)。 同时，在参数 UI (当预览报表时对最终用户显示) 中，为每个可视的参数创建一个与参数类型对应的编辑器 (例如为字符串参数使用文本框，为 Boolean 值使用下拉列表)。

注意
因为任何报表都是 XtraReport 的子类，因此也可以在自定义报表类中声明公共属性，并使用它们接收来参数。 但是，我们不建议您这样做。 原因是，在 保存报表的定义 时，尽管这些属性随同报表会被持久化到 REPX 文件中，但是，要正确地加载这种 REPX 定义，则要求加载此文件的应用程序包含该报表类的声明 —— 并不是始终都能这样。

本文档中下面的小节阐明了如何在设计时刻使用参数。 要学习如何在代码中使用参数，请参阅 如何： 创建有参数的报表 (运行时刻示例)。

要在设计时刻添加报表参数，则执行下列操作之一。

• 访问报表的 Field List(字段列表)，使用鼠标右键单击 Parameters(参数) 节点，并选择 Add Parameter(添加参数) 或 Edit Parameters(编辑参数)... 上下文菜单项。

  

• 在 属性网格 中，单击 XtraReport.Parameters 属性的省略号按钮，并通过被调用的 Parameter Collection Editor(参数集合编辑器) 来维护参数的集合。

  

在创建参数之后，首先要通过 Parameter.Type 属性来指定它的类型。 此属性可以被设置为任一 Type 值。 同时，取决于所指定的类型，在 打印预览 中为参数提供了对应的编辑器。

然后，把适当类型的值指派到 Parameter.Value 属性。

如果在设计时刻该取值保持空白，那么应通过代码 (静默地) 或由最终用户提供参数值。 下面的小节阐明了把参数传递到报表的不同方式： 传递参数。

除了标准的 (Type) 参数类型之外，还可以轻松地提供自定义参数类型 (例如枚举或 XPCollection 成员)。

来学习如何使用自定义类型的参数，请参阅 如何： 传递自定义类型的参数。

要把参数传递到报表，则指定它的 Parameter.Value 属性值。

如果报表的 XtraReport.RequestParameters 属性被启用 (默认启用)，当预览报表文档时，除非在“参数用户界面”中提交了所有可视参数的取值，否则报表文档不被创建。 对于至少一有个可视参数的报表，“参数用户界面”是被自动创建的，并且包含了适合于参数类型的编辑器。

同时，当它的 Parameter.Visible 属性被禁用时，不要求最终用户提交参数值。 如果在报表的参数集合中没有可视参数，那么在打印预览期间不显示“参数用户界面”，直至 ReportPrintTool.AutoShowParametersPanel 属性被启用。

有不同的方式可供传递参数值，可以根据任务的特性进行选择。

• 最普遍的选项是允许最终用户输入自定义参数值。

  - 在 Windows 窗体应用程序的打印预览中，Parameters(参数) 停靠面板出现 (停靠在 文档地图 面板，若存在)。 它的可视性由 参数 按钮切换。

  

  - 如果不显示打印预览 (例如在网页上，或者直接把报表发送到打印机或导出为文件时 —— 更严格地说，是每当 XtraReport.CreateDocument 方法被调用时)，下列对话框被自动生成。

  

• 如果应用程序不包括输入参数值的任何最终用户交互，那么应该在设计时刻或通过代码来指定 Parameter.Value 属性值。 相关的运行时刻示例，请参阅 如何： 静默传递参数值。

  注意
  我们不推荐您在报表生成期间修改参数值，这是因为参数可以被用于 筛选报表数据、以及用于 计算字段 和 数据绑定 中，那样可能会导致无法预料的结果。 在报表生成期间，参数值被假定为常量，因此如果需要在代码中指派参数值，那么应该在报表的 XRControl.BeforePrint 事件处理程序中、或者在生成报表文档的方法中指派。

如果参数已经有任一取值 (通过它的 Parameter.Value 属性指派的)，那么在默认情况下，该取值被显示在参数的编辑器中。 参数的说明是通过 Parameter.Description 属性指定的。

参数 用户界面呈现了当前报表的所有可视参数。 因此，如果报表包含了 从报表带区 或 子报表，那么它们的所有参数同时也需要指定。 这意味着一个参数只使用一个取值，即使从报表带区 (或子报表) 被打印多次。

如有必要，也可以为参数提供自定义用户界面。 要学习更多相关内容，请参阅 如何： 为参数提供自定义编辑器。

在参数被创建并添加到 XtraReport.Parameters 集合中、并指派参数值之后，在报表生成期间就可以以不同的方式使用它。 下面列出了使用参数可以完成的任务的示例。

• 筛选

  也许，最普遍的使用参数的场景之一，是通过指定报表的 XtraReportBase.FilterString，从而根据当前的参数值来筛选报表数据。 在设计时刻，则可以使用 FilterString Editor 来达到此目的。

  

  注意
  筛选数据更具有生产力且高效的方式，是根据当前参数值来修改报表数据源的 SQL SELECT 语句 (若可能)。 在 如何： 在数据源级筛选数据 指南中描述了这种方法。

• 数据绑定

  要在报表中显示参数值，则从 Field List(字段列表) 中把它拖放到所需的带区。 这样将创建一个绑定到该参数的 XRLabel 控件，就像普通的数据字段那样。

  

  要使用 邮件合并 把参数值嵌入到控件的内容中，则应把参数名称放在 Parameters. 前缀之后：

  

• 计算字段

  和标准的数据字段一样，参数也可以加入“计算字段”的表达式。 唯一的区别是在被插入到 表达式 中的文本时，数据字段的名称只需要以 [中括号] 括起，而参数的名称前面还要加上“Parameters.”前缀。

  

  注意，在 Condition Editor 中，支持许多函数，允许轻松执行不同的 字符串、日期时间、逻辑 和 数学 数据运算。 完整的函数列表，请参阅 表达式。

• 附条件的格式设置

  与“计算字段”相同，参数可以被嵌入到由不同 格式设置规则 组成的表达式中，例如在下面的示例中展示的那样： 如何： 限定每个页面的记录数。

• 脚本

  通过参数被传递到报表中的取值，可以在比上述场景更复杂的场景中被调用。 通常，报表数据的复杂处理是以 创建脚本 为基础。 在脚本中，通过参数名称，参数像所有其他组件那样可以被轻松访问，并且 Value 属性返回相关联的取值。

  C#	复制代码
  private void OnBeforePrint(object sender, System.Drawing.Printing.PrintEventArgs e) { xrLabel1.Text = "User: " + XtraReport1.Parameters["param1"].Value; }

  Visual Basic	复制代码
  Private Sub OnBeforePrint(ByVal sender As Object, ByVal e As System.Drawing.Printing.PrintEventArgs) XRLabel1.Text = "User: " + XtraReport1.Parameters("param1").Value End Sub

下列指南演示了在不同环境中参数的使用。

• 如何： 把标签绑定到参数；
• 如何： 创建有参数的报表；
• 如何： 传递自定义类型的参数；
• 如何： 创建有参数的报表 (运行时刻示例)；
• 如何： 创建 Drill-Through 报表；
• 如何： 限定每个页面的记录数；
• 如何： 静默传递参数值；
• 如何： 把参数传递到 Web 报表；
• 如何： 为参数提供自定义编辑器。