How to: Customize the Export Action Behavior 如何:自定义导出按钮行为

In XAF WinForms and ASP.NET applications, data from List Views can be exported using the Export Action the built-in ExportController provides. This Action is activated by default if the List Editor that implements the IExportable interface presents the current List View. Currently, all built-in WinForms List Editors and most ASP.NET List Editors support this interface (excludes the built-in Mobile List Editors). The Action's ChoiceActionBase.Items collection is filled based on the IExportable.SupportedExportFormats collection of the current List View's List Editor.

在 XAF WinForms 和ASP.NET应用程序中，可以使用内置导出控制器提供的导出操作导出列表视图中的数据。如果实现"可导出"接口的列表编辑器显示当前列表视图，则默认情况下激活此操作。目前，所有内置的 WinForms 列表编辑器和大多数ASP.NET列表编辑器都支持此界面（不包括内置移动列表编辑器）。操作的选择操作Base.项集合基于当前列表视图列表编辑器的 Iexport.支持的导出格式集合填充。

You can customize this Action's behavior using the ExportController's events. Note that there are two ExportController descendants: the WinExportController is used in WinForms applications, exports data to a file stream and invokes a Save File Dialog before exporting; and the WebExportController is used in ASP.NET applications and exports data to a memory stream.

您可以使用导出控制器的事件自定义此操作的行为。请注意，有两个导出控制器后代：WinExportController 在 WinForms 应用程序中使用，将数据导出到文件流，并在导出之前调用保存文件对话框;WebExport控制器用于ASP.NET应用程序并将数据导出到内存流。

When customizing the export functionality, ensure that the changes are intended for the base or platform-specific Controller. In this topic, the ExportController.CustomGetDefaultFileName, ExportController.CustomExport and ExportController.Exported events are handled for Export Action customization, both in WinForms and ASP.NET applications.

自定义导出功能时，请确保更改用于基础控制器或特定于平台的控制器。在本主题中，导出控制器.CustomGetDefaultfileName、导出控制器.自定义导出和导出控制器.导出事件在 WinForms 和ASP.NET应用程序中为导出操作自定义处理。

The sections below describe how to access the ExportController and customize the Export Action behavior by handling the Controller's events.

以下各节介绍如何通过处理控制器的事件来访问导出控制器和自定义导出操作行为。

• Customize the Name of the File Used for Exporting Data
• Customize Export Options Using the CustomExport Event both in the WinForms and ASP.NET Applications
• Customize Export Options Using the CustomExport Event in the WinForms Application
• Customize Export Options Using the CustomExport Event in the ASP.NET Application
• Customize the Export Action Behavior Using the Exported Event in the WinForms Application
• 自定义用于导出数据的文件的名称
• 使用 WinForms 和ASP.NET应用程序中的自定义导出事件自定义导出选项
• 使用 WinForms 应用程序中的自定义导出事件自定义导出选项
• 使用ASP.NET应用程序中的自定义导出事件自定义导出选项
• 使用 WinForms 应用程序中的导出事件自定义导出操作行为

Tip 提示

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E2335

完整的示例项目可在 DevExpress 代码示例数据库中找到，http://www.devexpress.com/example=E2335

.

Customize the Name of the File Used for Exporting Data

自定义用于导出数据的文件的名称

In WinForms applications, a Save File Dialog is invoked before exporting data to a file. In this dialog, the default file name is specified. It is generated from the caption of the List View from which data is currently exported. In ASP.NET applications, data is exported to a Memory Stream which can be downloaded as a file. This file's default name is generated in the same way as in the WinForms application. Subscribe to the ExportController.CustomGetDefaultFileName event to customize this file name. The base platform-independent ExportController class exposes this event. So, the file name that you provide in this event's handler is used in WinForms and ASP.NET applications. The following code demonstrates how to access the ExportController and handle its event:

在 WinForms 应用程序中，在将数据导出到文件之前，将调用保存文件对话框。在此对话框中，指定了默认文件名。它由当前导出数据的列表视图的标题生成。在ASP.NET应用程序中，数据将导出到内存流，该内存流可以作为文件下载。此文件的默认名称生成方式与 WinForms 应用程序中相同。订阅导出控制器.自定义获取默认文件名事件以自定义此文件名。与基本平台无关的 ExportController 类公开此事件。因此，此事件处理程序中提供的文件名在 WinForms 和ASP.NET应用程序中使用。以下代码演示如何访问导出控制器并处理其事件：

using DevExpress.ExpressApp.SystemModule;
//...
public partial class CustomizeExportController : ViewController {
    public CustomizeExportController() {
        InitializeComponent();
        TargetViewType = ViewType.ListView;
    }
    private ExportController exportController;
    protected override void OnActivated() {
         base.OnActivated();
         exportController = Frame.GetController<ExportController>();
         if (exportController != null) {
             exportController.CustomGetDefaultFileName += exportController_CustomGetDefaultFileName;
         }
    }
    void exportController_CustomGetDefaultFileName(
        object sender, CustomGetDefaultFileNameEventArgs e) {
        //Provide a custom file name
        e.FileName = e.FileName + "_" + DateTime.Now.ToString("MM.dd.yy");
    }
    protected override void OnDeactivated() {
         if (exportController != null) {
             exportController.CustomGetDefaultFileName -= exportController_CustomGetDefaultFileName;
         }
        base.OnDeactivated();
    }
}

The following image illustrates that the name specified in the CustomGetDefaultFileName event handler is used as the exported file's default name:

下图说明在自定义获取默认文件名称事件处理程序中指定的名称用作导出文件的默认名称：

If you need to customize the default file name for WinForms or ASP.NET applications only, access the WinExportController or WebExportController, respectively. These Controllers are ExportController's descendants - they expose the CustomGetDefaultFileName event as well.

如果需要自定义 WinForms 的默认文件名或仅ASP.NET应用程序，请分别访问 WinExport 控制器或 WebExport 控制器。这些控制器是导出控制器的后代 - 它们也公开自定义获取默认文件名称事件。

Customize Export Options Using the CustomExport Event for both the WinForms and ASP.NET Applications

使用 WinForms 和ASP.NET应用程序的自定义导出事件自定义导出选项

You can customize the exporting options specified for the target export format using the ExportOptionsBase class descendants. To do this, subscribe to the ExportController.CustomExport event and use the handler's CustomExportEventArgs.ExportOptions parameter to access them. If you need to change options for both WinForms and ASP.NET applications, subscribe to the ExportController's CustomExport event. Use the handler's CustomExportEventArgs.ExportTarget parameter to get the export format currently used in the export operation. For example, you can change XSL export options as shown below.

您可以使用 ExportOptionsBase 类后代自定义为目标导出格式指定的导出选项。为此，请订阅 ExportController.自定义导出事件，并使用处理程序的"自定义导出事件"参数访问它们。如果需要更改 WinForms 和ASP.NET应用程序的选项，请订阅导出控制器的自定义导出事件。使用处理程序的自定义导出事件Args.ExportTarget 参数获取导出操作中当前使用的导出格式。例如，您可以更改 XSL 导出选项，如下所示。

using DevExpress.ExpressApp.SystemModule;
using DevExpress.XtraPrinting;
// ...
public partial class CustomizeExportController : ViewController {
    public CustomizeExportController() {
        InitializeComponent();
        TargetViewType = ViewType.ListView;
    }
    private ExportController exportController;
    protected override void OnActivated() {
        base.OnActivated();
        exportController = Frame.GetController<ExportController>();
        exportController.CustomExport += new EventHandler<CustomExportEventArgs>(CustomExport);
    }
    protected virtual void CustomExport(object sender, CustomExportEventArgs e) {
        //Customize Export Options
        if (e.ExportTarget == ExportTarget.Xls) {
            XlsExportOptions options = e.ExportOptions as XlsExportOptions;
            if (options == null) {
               options = new XlsExportOptions();
            }
            options.SheetName = View.Caption;
            options.ShowGridLines = true;
            e.ExportOptions = options;
        }
    }
    protected override void OnDeactivated() {
        exportController.CustomExport -= new EventHandler<CustomExportEventArgs>(CustomExport);
        base.OnDeactivated();
    }
}

In the code above, the exported View's caption is used as the sheet's name in the exported XLS file.

在上面的代码中，导出的视图的标题在导出的 XLS 文件中用作工作表的名称。

If you need to customize the exporting options in WinForms or ASP.NET applications only, access the WinExportController or WebExportController, respectively. These Controllers are ExportController's descendants, and they expose the CustomExport event as well.

如果您需要自定义 WinForms 中的导出选项或仅ASP.NET应用程序，请分别访问 WinExport 控制器或 WebExport 控制器。这些控制器是导出控制器的后代，它们也公开自定义导出事件。

You can customize export options using the XlsExportOptionsEx class members as an alternative to the XlsExportOptions's members.

您可以使用 XlsExportOptionsEx 类成员自定义导出选项，作为 XlsExportOptions 成员的替代项。

Customize Export Options Using the CustomExport Event for a WinForms Application

使用 WinForms 应用程序的自定义导出事件自定义导出选项

This section demonstrates how to customize exporting options specific to a particular export format, for example, the exporting options the built-in WinForms List Editors' controls provide. Subscribe to the CustomExport event and use the event handler's CustomExportEventArgs.Printable parameter to access these controls. For instance, when data is exported from the TreeListEditor, the Printable parameter provides access to the TreeList control. This control's TreeList.OptionsPrint property allows you to set the required exporting options.

本节演示如何自定义特定于特定导出格式的导出选项，例如，内置 WinForms 列表编辑器控件提供的导出选项。订阅自定义导出事件并使用事件处理程序的自定义导出事件。可打印参数访问这些控件。例如，当从 TreeListEditor 导出数据时，可打印参数提供对 TreeList 控件的访问。此控件的树列表.OptionsPrint 属性允许您设置所需的导出选项。

In a GridListEditor, the GridControl is used to export data. Use the GridView's GridView.OptionsPrint property to access the GridControl's exporting options.

在网格列表编辑器中，网格控制用于导出数据。使用网格视图的网格视图.选项打印属性访问网格控件的导出选项。

The code below demonstrates how to use the GridOptionsPrint.ExpandAllGroups property of the object returned by the GridView's OptionsPrint property.

下面的代码演示如何使用 GridOptionsPrint.展开由 GridView 的 OptionsPrint 属性返回的对象的所有组属性。

When a GridListEditor presents a List View, data rows can be grouped and the groups can be collapsed. The the Export Action's default behavior is to expand all the collapsed groups in the exported file. You can invoke a message to notify an end-user when GridListEditor has collapsed groups and then ask whether to keep them collapsed in the exported file. Handle the ExportController.CustomExport event to do this.

当 GridListEditor 提供列表视图时，可以对数据行进行分组，也可以折叠组。导出操作的默认行为是展开导出文件中的所有折叠组。您可以调用一条消息，以便在 GridListEditor 已折叠组时通知最终用户，然后询问是否将它们保留在导出文件中折叠。处理导出控制器.自定义导出事件以执行此操作。

It is necessary to iterate through grid group rows to detect collapsed groups. The group rows have negative handles in the Grid View (see Working with Groups in Code). The expansion status of a group row can be determined by the GridView.GetRowExpanded method. Display the message box using the Messaging.GetUserChoice method when a collapsed group is detected, and set the GridOptionsPrint.ExpandAllGroups property based on the user's selection.

有必要通过网格组行进行迭代以检测折叠的组。组行在网格视图中具有负句柄（请参阅在"代码中使用组"）。组行的扩展状态可以通过 GridView.GetRow 扩展方法确定。在检测到折叠组时使用"消息.GetUserChoice"方法显示消息框，并根据用户选择设置 GridOptionsPrint.ExpandAllGroups 属性。

Implement a Controller in a WinForms module to change the ExpandAllGroups export option of the grid control used in the WinForms application. In this Controller, access the WinExportController to subscribe to its CustomExport event.

在 WinForms 模块中实现控制器以更改 WinForms 应用程序中使用的网格控件的"展开所有组"导出选项。在此控制器中，访问 WinExport 控制器以订阅其自定义导出事件。

using DevExpress.XtraGrid.Views.Grid;
using DevExpress.ExpressApp.Win.SystemModule;
using DevExpress.ExpressApp.Win.Editors;
using DevExpress.ExpressApp.Win;
using System.Windows.Forms;
// ...
public partial class CustomizeExportControllerWin : ViewController {
     public CustomizeExportControllerWin() {
        InitializeComponent();
        TargetViewType = ViewType.ListView;
    }
    private WinExportController winExportController;
    protected override void OnActivated() {
        base.OnActivated();
        winExportController = Frame.GetController<WinExportController>();
        winExportController.CustomExport += winExportController_CustomExport;
    }
    void winExportController_CustomExport(object sender, CustomExportEventArgs e) {
        //Show a message before exporting a Grid List Editor
        GridListEditor gridListEditor = 
            ((DevExpress.ExpressApp.ListView)View).Editor as GridListEditor;
        if (gridListEditor != null) {
            GridView gridView = gridListEditor.GridView;
            if (HasCollapsedGroups(gridView)) {
                string message =
                   "There are collapsed groups in the grid. " +
                    "Expand all groups in the exported file?";
                gridView.OptionsPrint.ExpandAllGroups =
                   WinApplication.Messaging.GetUserChoice(message, GetMessageBoxCaption(),
                   MessageBoxButtons.YesNo)
                   == DialogResult.Yes;
            }
        }
    }
    private bool HasCollapsedGroups(GridView gridView) {
        if (gridView.GroupCount > 0) {
            int rowHandle = -1;
            while (gridView.IsValidRowHandle(rowHandle)) {
                if (!gridView.GetRowExpanded(rowHandle)) return true;
                rowHandle--;
            }
        }
        return false;
    }
    private string GetMessageBoxCaption() {
        return String.Format(
            "{0} {1}", winExportController.ExportAction.Caption,
                winExportController.ExportAction.SelectedItem);
    }
    protected override void OnDeactivated() {
        winExportController.CustomExport -= winExportController_CustomExport;
        base.OnDeactivated();
    }
}

End-users will see the following message box when exporting a List View containing collapsed groups:

在导出包含折叠组的列表视图时，最终用户将看到以下消息框：

Note 注意

Refer to the How to: Localize Custom String Constants topic to see how to make this message text localizable.

请参阅"如何：本地化自定义字符串常量"主题，了解如何使此消息文本可本地化。

If the choice is "Yes", all grid rows will be exported.

如果选项为"是"，则将导出所有网格行。

If the choice is "No", the rows belonging to the collapsed groups will not be included in the exported file.

如果选项为"否"，则属于折叠组的行将不会包含在导出文件中。

Customize Export Options Using the CustomExport Event for an ASP.NET Application

使用ASP.NET应用程序的自定义导出事件自定义导出选项

In ASP.NET applications, the controls that are used to export data from List Editors are so-called exporters. You can use them to change default export settings. Subscribe to the ExportController.CustomExport event and use the event handler's CustomExportEventArgs.Printable parameter to access the exporter of the currently exported List Editor. For instance, when data is exported from the ASPxGridListEditor, the Printable parameter provides access to the ASPxGridViewExporter exporter.

在ASP.NET应用程序中，用于从列表编辑器导出数据的控件是所谓的导出器。您可以使用它们来更改默认导出设置。订阅 ExportController.自定义导出事件，并使用事件处理程序的自定义导出事件.可打印参数访问当前导出的列表编辑器的导出器。例如，当从 ASPxGridListEditor 导出数据时，可打印参数提供对 ASPxGridView 导出器的访问。

The code below demonstrates how to use the ASPxGridViewExporter's ASPxGridViewExporter.ExportSelectedRowsOnly property. This property is set to the true value to export only rows that are the currently selected in the exported grid.

下面的代码演示如何使用 ASPxGridViewexporter.导出选定的行仅属性。此属性设置为 true 值，以便仅导出导出网格中当前选择的行。

Implement a Controller in a Web module to use an ASPxGridViewExporter export option, used by the ASPxGridListEditor in the ASP.NET application. In this Controller, access the WebExportController to subscribe to its CustomExport event.

在 Web 模块中实现控制器以使用 ASPxGridViewexporter 导出选项，该选项由 ASP.NET应用程序中的 ASPxGridList 编辑器使用。在此控制器中，访问 Web Export 控制器以订阅其自定义导出事件。

using DevExpress.ExpressApp.Web.SystemModule;
//add a reference to the DevExpress.Web.Export assembly
using DevExpress.Web;
// ...
public partial class CustomizeExportControllerWeb : ViewController {
    public CustomizeExportControllerWeb() {
        InitializeComponent();
        TargetViewType = ViewType.ListView;
    }
    private WebExportController webExportController;
    protected override void OnActivated() {
        base.OnActivated();
        webExportController = Frame.GetController<WebExportController>();
        webExportController.CustomExport += webExportController_CustomExport;
    }
    void webExportController_CustomExport(object sender, CustomExportEventArgs e) {
        //Export only selected rows
        ASPxGridViewExporter exporter = e.Printable as ASPxGridViewExporter;
        if (exporter != null) {
            exporter.ExportSelectedRowsOnly = true;
        }
    }
    protected override void OnDeactivated() {
        webExportController.CustomExport -= webExportController_CustomExport;
        base.OnDeactivated();
    }
}

With the code above, the Export Action exports only selected grid rows:

使用上述代码，导出操作仅导出选定的网格行：

Customize the Export Action Behavior Using the Exported Event for the WinForms Application

使用 WinForms 应用程序的导出事件自定义导出操作行为

After the export operation has finished, you can ask end-users whether or not the saved file should be opened. Handle the ExportController.Exported event to do this. The handler's CustomExportEventArgs.Stream parameter can be used to determine the exported file name.

导出操作完成后，您可以询问最终用户是否应打开保存的文件。处理导出控制器.导出事件以执行此操作。处理程序的自定义导出事件Args.Stream 参数可用于确定导出的文件名。

using System.IO;
using DevExpress.ExpressApp.Win;
using System.Windows.Forms;
using DevExpress.ExpressApp.Win.SystemModule;
//...
public partial class CustomizeExportControllerWin : ViewController {
    // ...
    private WinExportController winExportController;
    protected override void OnActivated() {
        base.OnActivated();
        // ...
        winExportController.Exported += 
            new EventHandler<CustomExportEventArgs>(winExportController_Exported);
    }
    void winExportController_Exported(object sender, 
            DevExpress.ExpressApp.SystemModule.CustomExportEventArgs e) {
        if (e.Stream is FileStream) {
            string fileName = ((FileStream)e.Stream).Name;
            if (File.Exists(fileName)) {
                e.Stream.Close();
                if (WinApplication.Messaging.GetUserChoice("Open the exported file?",
                        GetMessageBoxCaption(), MessageBoxButtons.YesNo) == DialogResult.Yes)
                    Process.Start(fileName);
            }
        }
    }
    protected override void OnDeactivated()  {
        winExportController.Exported -= 
            new EventHandler<CustomExportEventArgs>(winExportController_Exported);
        // ...
        base.OnDeactivated();
    }
}

The following image illustrates the message box shown after the export is finished.

下图说明了导出完成后显示的消息框。

Note 注意

Refer to the How to: Localize Custom String Constants topic to see how to localize the message text.

请参阅"如何：本地化自定义字符串常量"主题，了解如何本地化消息文本。

If the end-user clicks "Yes", the exported file opens in an application associated with its type.

如果最终用户单击"是"，则导出的文件将在与其类型关联的应用程序中打开。