本主题阐述了如何把书签集合 (经常由“文档地图”或“目录引用) 添加到报表中。 这使得在一个特定区域中查看整个报表结构更容易。 注意，在默认情况下，没有书签被添加到报表中。 但是，在设计时刻或运行时刻，可以轻松地把书签添加到报表中。
本主题由下列小节组成：
书签概述
文档地图 (或 目录) 是以树状形式表示的所有报表书签的一个集合。 它被显示在报表的 打印预览 中 (在默认情况下，它被停靠在左侧)，并且也可以被 导出为 PDF，如下图所示。
可以为下列报表控件指定报表书签： XRLabel、XRCheckBox、XRRichText、XRPictureBox、XRPanel、XRTable、XRTableCell、XRShape、XRBarCode、XRZipCode、XRChart、XRPivotGrid、XRPageInfo。
通过下列属性表示控件的各个书签：
- XRControl.Bookmark - 这是主要的书签属性，指定书签文本。 要为控件创建书签，只需要把此属性的值设置为非空字符串，并且有指定文本的书签将被自动创建并添加到文档地图。 另外要注意，Bookmark 属性是 可绑定的。 这样就允许报表控件有若干书签实例被显示在报表的文档地图中，这取决于绑定的数据。
- XRControl.BookmarkParent - 此属性被用于创建文档地图的层次结构。 它指定哪个报表控件以及哪个书签或书签集 (如果控件被绑定到数据) 被用作当前控件的父控件。 注意，此属性值指定的控件应该在文档地图中有它的书签。 否则，当前书签将被链接到文档地图的根节点。
 注意 |
|---|
在 XtraReports 中不允许书签循环引用。 在把当前控件的父书签设置为另一个把当前控件设置为父书签的控件时，会发生书签循环引用。 在这种情况下，将抛出一个异常。 |
对于所有未指定父书签的书签，文档地图的根书签就成为它们的父书签。 根书签被链接到报表首个页面的起始处，并且使用 XtraReport.Bookmark 属性值作为它的文本。 注意，如果报表的 Bookmark 属性值被设置为 String.Empty (这是默认值)，那么报表的 Name 被用作根书签的文本。
显示或隐藏文档地图
如果报表中的任何控件至少包含一个书签，那么 打印预览工具栏 就显示 文档地图 按钮 (
)。 此外，在这种情况下，默认显示文档地图面板。 这样，最终用户可以通过工具栏上的“文档地图”按钮，来隐藏或显示此面板，如下图所示。
要以程序方式方式显示或隐藏文档地图，则使用预览窗体的 PrintControl 控件的 PrintControl.ExecCommand 方法。
| C# |  复制代码 |
|---|---|
using DevExpress.XtraPrinting; // ... // Create a report and generate its document. XtraReport1 report = new XtraReport1(); report.CreateDocument(); // Hide a document map. report.PrintingSystem.PreviewForm.PrintControl.ExecCommand (PrintingSystemCommand.DocumentMap, new object[] {false}); // Show a document map. report.PrintingSystem.PreviewForm.PrintControl.ExecCommand (PrintingSystemCommand.DocumentMap, new object[] {true}); | |
| Visual Basic | 复制代码 |
|---|---|
Imports DevExpress.XtraPrinting ' ... ' Create a report and generate its document. Dim Report As New XtraReport1() Report.CreateDocument() ' Hide a document map. Report.PrintingSystem.ExecCommand(PrintingSystemCommand.DocumentMap, _ New Object() {False}) ' Show a document map. Report.PrintingSystem.ExecCommand(PrintingSystemCommand.DocumentMap, _ New Object() {True}) | |
也可以隐藏工具栏中的“文档地图”按钮，那样最终用户将不能人为改变“文档地图”面板的可视性。 下列代码演示了如何完成此任务。
| C# | 复制代码 |
|---|---|
// Hide the Document Map button. report.PrintingSystem.SetCommandVisibility (PrintingSystemCommand.DocumentMap, CommandVisibility.None); // Show the Document Map button. report.PrintingSystem.SetCommandVisibility (PrintingSystemCommand.DocumentMap, CommandVisibility.All); | |
| Visual Basic | 复制代码 |
|---|---|
' Hide the Document Map button. Report.PrintingSystem.SetCommandVisibility (PrintingSystemCommand.DocumentMap, CommandVisibility.None) ' Show the Document Map button. Report.PrintingSystem.SetCommandVisibility (PrintingSystemCommand.DocumentMap, CommandVisibility.All) | |
示例
下列指南演示了如何添加书签。
