在 Office 文档中保存动态控件
更新： 2008 年 7 月
适用对象 |
|---|
本主题中的信息仅适用于指定的 Visual Studio Tools for Office 项目和 Microsoft Office 版本。 文档级项目
应用程序级项目
有关更多信息，请参见按应用程序和项目类型提供的功能。 |
保存和关闭文档或工作簿时，将不会保持在运行时添加的控件。宿主控件和 Windows 窗体控件的确切行为与此不同。对于这两种控件，通过在解决方案中添加代码，可在用户重新打开文档时重新创建它们。
在运行时向文档添加的控件称为“动态控件”。有关动态控件的更多信息，请参见在运行时向 Office 文档添加控件。
在文档中保持宿主控件
保存并关闭文档时，将从文档中移除所有动态宿主控件。只有基础本机 Office 对象才会留在文档中。例如，Microsoft.Office.Tools.Excel.ListObject 宿主控件变成了 Microsoft.Office.Interop.Excel.ListObject。本机 Office 对象未连接至宿主控件事件，且不具备宿主控件的数据绑定功能。
下表列出了每种宿主控件留在文档中的本机 Office 对象。
在打开文档时重新创建动态宿主控件
每次用户打开文档时，都可以重新创建动态宿主控件以代替现有的本机控件。按此方式在打开文档时创建宿主控件可模拟用户可能期望的体验。
若要重新创建 Word 的宿主控件或者创建 Excel 的 Microsoft.Office.Tools.Excel.NamedRange 或 Microsoft.Office.Tools.Excel.ListObject 宿主控件，请使用 Microsoft.Office.Tools.Excel.ControlCollection 或 Microsoft.Office.Tools.Word.ControlCollection 类的具有本机 Office 对象参数的 Add<控件类> 方法。
例如，如果要在打开文档时基于现有的本机 Microsoft.Office.Interop.Excel.ListObject 创建 Microsoft.Office.Tools.Excel.ListObject 宿主控件，请使用 AddListObject(ListObject) 方法并传入现有的 Microsoft.Office.Interop.Excel.ListObject。下面的代码示例在 Excel 2007 的文档级项目中演示此操作。代码将在 Sheet1 类中重新创建一个基于名为 MyListObject 的现有 Microsoft.Office.Interop.Excel.ListObject 的动态 Microsoft.Office.Tools.Excel.ListObject。
Private vstoListObject As Microsoft.Office.Tools.Excel.ListObject
Private Const DISP_E_BADINDEX As Integer = CInt(&H8002000B)
Private Sub Sheet1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
Dim nativeListObject As Excel.ListObject = Nothing
Try
nativeListObject = Me.ListObjects("MyListObject")
Catch ex As System.Runtime.InteropServices.COMException
' "MyListObject" does not exist.
If ex.ErrorCode <> DISP_E_BADINDEX Then
Throw
End If
End Try
If nativeListObject IsNot Nothing Then
vstoListObject = Me.Controls.AddListObject(nativeListObject)
End If
End Sub
private Microsoft.Office.Tools.Excel.ListObject vstoListObject;
private const int DISP_E_BADINDEX = unchecked((int)0x8002000B);
private void Sheet1_Startup(object sender, System.EventArgs e)
{
Excel.ListObject nativeListObject = null;
try
{
nativeListObject = this.ListObjects.get_Item("MyListObject");
}
catch (System.Runtime.InteropServices.COMException ex)
{
// "MyListObject" does not exist.
if (ex.ErrorCode != DISP_E_BADINDEX)
throw;
}
if (nativeListObject != null)
{
vstoListObject = this.Controls.AddListObject(nativeListObject);
}
}
有关演示动态控件的文档级示例，请参见 Excel 动态控件示例和 Word 动态控件示例。
有关演示动态控件的应用程序级示例，请参见 Excel 外接程序动态控件示例和 Word 外接程序动态控件示例。
在 SP1 之前的版本中在 Excel 2003 项目和 Excel 2007 项目中重新创建 ListObject
在 Visual Studio 2008 Service Pack 1 (SP1) 中，AddListObject(ListObject) 方法对于 Excel 2007 项目是新增的。如果您使用的是 Excel 2007 项目并且没有安装 SP1，或者如果您使用的是 Excel 2003 项目，则您不能使用此方法重新创建动态 Microsoft.Office.Tools.Excel.ListObject。
相反，您必须首先删除本机 Microsoft.Office.Interop.Excel.ListObject，然后通过使用 AddListObject(Range, String) 方法重新创建动态 Microsoft.Office.Tools.Excel.ListObject。有关演示此操作的代码，请参见 Excel 动态控件示例。
如果您没有首先删除本机 Microsoft.Office.Interop.Excel.ListObject，您会在尝试重新创建 Microsoft.Office.Tools.Excel.ListObject 时收到 COMException，因为 Excel 不允许您创建重叠的列表对象。
重新创建图表
若要重新创建 Microsoft.Office.Tools.Excel.Chart 宿主控件，必须首先删除本机 Microsoft.Office.Interop.Excel.Chart，然后通过使用 AddChart(Range, String) 或 AddChart(Double, Double, Double, Double, String) 方法重新创建 Microsoft.Office.Tools.Excel.Chart。没有能够让您基于现有的 Microsoft.Office.Interop.Excel.Chart 创建新的 Microsoft.Office.Tools.Excel.Chart 的 Add<控件类> 方法。
如果您没有首先删除本机 Microsoft.Office.Interop.Excel.Chart，则在重新创建 Microsoft.Office.Tools.Excel.Chart 时会创建另一个重复的图表。
在文档中保持 Windows 窗体控件
保存并关闭文档时，Visual Studio Tools for Office 运行时将自动从文档中移除所有动态创建的 Windows 窗体控件。但是，此行为在文档级项目和应用程序级项目中却有所不同。
在文档级自定义项中，这些控件及其基础 ActiveX 包装（用于在文档中承载控件）将在下次打开文档时移除。文档中不会留下任何曾经存在这些控件的指示。
在应用程序级外接程序中，将移除这些控件，但 ActiveX 包装却留在文档中。当用户下次打开文档时，就会看到 ActiveX 包装。在 Excel 中，ActiveX 包装会按照这些控件在上次保存文档时的显示方式来显示它们的图像。在 Word 中，ActiveX 包装只有在用户单击它们时才会显示出来，其图像是一条表示控件边框的虚线。有多种方式可用于移除 ActiveX 包装。有关更多信息，请参见移除外接程序中的 ActiveX 包装。
在打开文档时重新创建 Windows 窗体控件
在用户重新打开文档时，可以重新创建已删除的 Windows 窗体控件。为此，解决方案必须执行下列任务：
存储有关这些控件在文档保存或关闭时的大小、位置和状态的信息。在文档级自定义项中，可以将此数据保存至文档的数据缓存中。在应用程序级外接程序中，可以将此数据保存至文档的自定义 XML 部件中。
在打开文档时引发的事件中重新创建这些控件。在文档级项目中，可在 Sheet编号_Startup 或 ThisDocument_Startup 事件处理程序中实现此目的。在应用程序级项目中，可在 WorkbookOpen 或 DocumentOpen 事件的事件处理程序中实现此目的。
有关演示动态控件的文档级示例，请参见 Excel 动态控件示例和 Word 动态控件示例。
有关应用程序级示例，请参见 Excel 外接程序动态控件示例和 Word 外接程序动态控件示例。
移除外接程序中的 ActiveX 包装
在使用外接程序向文档中添加动态 Windows 窗体控件时，可以防止控件的 ActiveX 包装在下次打开文档时显示在文档中，具体方法如下。
在打开文档时移除 ActiveX 包装
若要移除所有 ActiveX 包装，请调用表示新打开的文档的 Microsoft.Office.Interop.Word.Document 或 Microsoft.Office.Interop.Excel.Workbook 的 GetVstoObject 方法。例如，若要从某个 Word 文档中移除所有 ActiveX 包装，可以调用传递给 DocumentOpen 事件的事件处理程序的 Document 对象的 GetVstoObject 方法。
如果已知将只在安装了相应外接程序的计算机上打开该文档，此过程将十分有用。如果可能要将该文档传递给未安装相应外接程序的其他用户，请改为考虑在关闭文档前移除这些控件。
下面的代码示例演示如何在打开文档时调用 GetVstoObject 方法。
Private Sub Application_DocumentOpen_ClearActiveXWrappers( _
ByVal Doc As Word.Document) Handles Application.DocumentOpen
Dim vstoDocument As Microsoft.Office.Tools.Word.Document = Doc.GetVstoObject()
End Sub
private void Application_DocumentOpen_ClearActiveXWrappers(Word.Document Doc)
{
Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();
}
虽然 GetVstoObject 方法主要用于在运行时生成新的宿主项，但在首次针对特定文档调用此方法时，它还会清除该文档中的所有 ActiveX 包装。有关如何使用 GetVstoObject 方法的更多信息，请参见在运行时在应用程序级外接程序中扩展 Word 文档和 Excel 工作簿。
请注意，如果外接程序可在文档打开时创建动态控件，那么它在创建这些控件的过程中就已经在调用 GetVstoObject 方法。在此情况下，无需添加对 GetVstoObject 方法的单独调用即可移除 ActiveX 包装。
在关闭文档前移除动态控件
外接程序可在文档关闭前显式移除文档中的每个动态控件。如果可能要将文档传递给未安装该外接程序的用户，此过程将十分有用。
下面的代码示例演示如何在关闭 Word 文档时移除其中的所有 Windows 窗体控件。
Private Sub Application_DocumentBeforeClose(ByVal Doc As Word.Document, _
ByRef Cancel As Boolean) Handles Application.DocumentBeforeClose
If Doc.HasVstoObject() Then
Dim vstoDocument As Microsoft.Office.Tools.Word.Document = _
Doc.GetVstoObject()
Dim controlsToRemove As System.Collections.ArrayList = _
New System.Collections.ArrayList()
' Get all of the Windows Forms controls.
For Each control As Object In vstoDocument.Controls
If TypeOf control Is System.Windows.Forms.Control Then
controlsToRemove.Add(control)
End If
Next
' Remove all of the Windows Forms controls from the document.
For Each control As Object In controlsToRemove
vstoDocument.Controls.Remove(control)
Next
End If
End Sub
void Application_DocumentBeforeClose(Word.Document Doc, ref bool Cancel)
{
if (Doc.HasVstoObject())
{
Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();
System.Collections.ArrayList controlsToRemove =
new System.Collections.ArrayList();
// Get all of the Windows Forms controls.
foreach (object control in vstoDocument.Controls)
{
if (control is System.Windows.Forms.Control)
{
controlsToRemove.Add(control);
}
}
// Remove all of the Windows Forms controls from the document.
foreach (object control in controlsToRemove)
{
vstoDocument.Controls.Remove(control);
}
}
}
请参见
任务
概念
修订记录
日期 |
历史记录 |
原因 |
|---|---|---|
2008 年 7 月 |
增加了有关如何在应用程序级外接程序中保持动态控件的信息。 |
SP1 功能更改。 |