本文档阐述了创建可用于 XtraReports 中的自定义控件的要点。 介绍了创建自定义报表控件主要方法，并提供了关于创建自定义控件实现的有用提示。 要学习如何在报表中使用自定义控件，请参阅 使用自定义控件 主题。
本文档由下列小节组成。
创建自定义控件
在 XtraReports 中，可以通过创建自定义控件来扩展原产报表控件集。 例如，如果需要标准的 XRLabel 控件实现某些特定的功能以满足要求 (例如检查它的 Text 属性值是否长于 8 个字符)，那么就可以使用自定义控件来实现此功能。
要创建自定义报表控件，可以选择下列方式之一。
从已有的报表控件派生。
这种方式用于只需要修改已有控件的少量功能时。 为此，需要从一个标准 报表控件 派生，并重写某些属性、方法和事件，或者添加自定义成员，以便于实现某些特定的行为。 例如，下列指南描述了如何从 XRLabel 控件派生，并且引入 Number 新属性，从而使此控件只接受和显示数字值 —— 如何： 创建数字标签。
从 XRControl 基本类派生。
在应用程序中，这种方式比上面提及的方式更复杂。 但是，使用这种方式可以完全定制控件的行为、以及创建有任意功能的自定义控件。 当从 XRControl 类派生时，通常需要重写下面的两个方法：
|
方法 |
说明 |
|---|---|
| CreateBrick |
这是一个受保护的方法，返回一个用于包含自定义控件的数据的 XtraPrinting VisualBrick。 当需要以适当的 XtraPrinting bricks 呈现所有报表控件时，XtraReport 每次生成 XtraPrinting Document (例如，当调用 XtraReport.CreateDocument 或 XtraReport.ShowPreview 方法时) 时，此方法都被调用。 |
| PutStateToBrick | 这是一个受保护的方法，为每个由 CreateBrick 方法创建的 brick 而调用，从而在报表文档生成 (例如预览、打印或导出报表) 期间，获得自定义控件的可视化呈现。 例如，如果自定义报表控件被放置在 Detail(细节) 报表带区中，那么每次为每个数据行生成 Detail 报表带区时，PutStateToBrick 方法都被调用。 因此，使用此方法可以反射对每个细节行改变自定义控件的属性时，自定义控件的外观如何变化。 |
要获得派生于 XRControl 类的真实自定义控件的示例，请参阅 如何： 创建进度条控件 指南。
 注意 |
|---|
自定义报表控件被声明为公共类是非常重要的，否则在许多公共场景中将不能正确操作它 (例如，在报表设计器中不能复制和粘贴非公共报表控件)。 这样做的目的是为了实现序列化。 |
创建自定义控件的最佳实践
当开发自定义报表控件时，下列建议非常有用。
1. 为自定义控件声明创建单独的程序集
虽然可以把自定义控件放置到与主应用程序相同的程序集中，但是，我们推荐把所有自定义控件声明放到单独的程序集中，并从项目中引用它。 这种方式有两个优势：
- 在Visual Studio 设计时刻预览报表时，可以正确生成自定义控件。
- 可以在其他应用程序中重用自定义控件 (而不需要在多个项目中复制和修改相同的代码)。
2. 为自定义控件提供工具箱图标
如果需要指定自定义图标，从而在工具箱中或 Report Explorer(报表资源管理器) 窗口中表示自定义控件，那么就需要创建一个自定义位图文件 (16x16 像素)，并把它添加到项目中。 注意，在把图像文件添加到项目中时，请确定其名称与类名称相匹配，并且把 生成操作(Build Action) 属性值设置为 嵌入的资源(Embedded Resource)。
然后，就可以使用 ToolboxBitmap attribute，把这个图标指派到自定义控件，如下所示。
| C# |  复制代码 |
|---|---|
using System.Drawing; using DevExpress.XtraReports.UI; //... namespace CustomControls { [ToolboxBitmap(typeof(XRNumericLabel))] public class XRNumericLabel: XRControl { // ... } } | |
| Visual Basic | 复制代码 |
|---|---|
Imports System.Drawing Imports DevExpress.XtraReports.UI '... Namespace CustomControls <ToolboxBitmap(GetType(XRNumericLabel))> _ Public Class XRNumericLabel Inherits XRControl ' ... End Class End Namespace | |
3. 指定默认的被绑定属性
每个报表控件都有一个默认的可绑定属性。 当使用 Field List(字段列表) 或 绑定 上下文链接 时，此属性被绑定到数据。 XRControl 类的默认的可绑定属性是 XRControl.Tag。 要把自定义控件的另一个属性设置为可绑定属性，就使用 DefaultBindableProperty attribute。
| C# | 复制代码 |
|---|---|
using DevExpress.XtraReports; using DevExpress.XtraReports.UI; // ... // Set the default bindable property. [DefaultBindableProperty("MyProperty")] public class MyControl : XRControl { // ... // Make the MyProperty bindable. [DefaultValue(0), Bindable(true)] public int MyProperty { // ... } // ... } | |
| Visual Basic | 复制代码 |
|---|---|
Imports DevExpress.XtraReports Imports DevExpress.XtraReports.UI ' ... ' Set the default bindable property. <DefaultBindableProperty("MyProperty")> _ Public Class ProgressBar Inherits XRControl ' ... ' Make the MyProperty bindable. <DefaultValue(0), Bindable(True)> _ Public Property MyProperty() As Integer ' ... End Property ' ... End Class | |
示例
下列指南演示了自定义控件的使用。
