程序文档级自定义项Program document-level customizations

在使用文档级自定义项扩展 Microsoft Office Word 或 Microsoft Office Excel 时,可以执行以下任务:When you extend Microsoft Office Word or Microsoft Office Excel by using a document-level customization, you can perform the following tasks:

  • 通过使用应用程序的对象模型对其进行自动化。Automate the application by using its object model.

  • 向文档图面添加控件。Add controls to the surface of the document.

  • 从自定义程序集调用文档中的 Visual Basic for Applications (VBA) 代码。Call Visual Basic for Applications (VBA) code in the document from the customization assembly.

  • 从 VBA 调用自定义程序集中的代码。Call code in the customization assembly from VBA.

  • 在文档位于未安装 Microsoft Office 的服务器上时管理其特定方面。Manage certain aspects of the document while it is on a server that does not have Microsoft Office installed.

  • 自定义应用程序的用户界面 (UI)。Customize the user interface (UI) of the application.

    适用于: 本主题中的信息适用于文档-级别 Excel 和 Word 的项目。Applies to: The information in this topic applies to document-level projects for Excel and Word. 有关详细信息,请参阅按 Office 应用程序和项目类型提供的功能For more information, see Features available by Office application and project type.

    在文档级项目中编写代码与在 Visual Studio 中编写其他类型项目的代码在某些方面存在不同。Some aspects of writing code in document-level projects are different from other types of projects in Visual Studio. 其中许多差异是由 Office 对象模型公开给托管代码的方式引起的。Many of these differences are caused by the way the Office object models are exposed to managed code. 有关详细信息,请参阅在 Office 解决方案中编写代码For more information, see Write code in Office solutions.

    有关可以通过使用 Visual Studio 中的 Office 开发工具创建的文档级自定义项和其他类型的解决方案的常规信息,请参阅office 解决方案(开发)概述 VSTOFor general information about document-level customizations and other types of solutions you can create by using the Office development tools in Visual Studio, see Office solutions development overview (VSTO).

使用文档级项目中生成的类Use the generated classes in document-level projects

创建文档级项目时,Visual Studio 将在项目中自动生成一个可用开始编写代码的类。When you create a document-level project, Visual Studio automatically generates a class in the project that you can use to start writing your code. Visual Studio 针对 Word 和 Excel 生成不同的类:Visual Studio generates different classes for Word and Excel:

  • 在 Word 文档级项目中,默认情况下此类称为 ThisDocumentIn document-level projects for Word, the class is called ThisDocument by default.

  • Excel 文档级项目具有多个生成的类:一个用于工作簿本身,一个用于每一工作表。Document-level projects for Excel have multiple generated classes: one for the workbook itself, and one for each worksheet. 默认情况下,这些类具有以下名称:By default, these classes have the following names:

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    生成的类包含在打开或关闭文档时调用的事件处理程序。The generated class includes event handlers that are called when the document is opened or closed. 若要在打开文档时运行代码,请将代码添加到 Startup 事件处理程序。To run code when the document is opened, add code to the Startup event handler. 若要在关闭文档后立即运行代码,请将代码添加到 Shutdown 事件处理程序。To run code just before the document is closed, add code to the Shutdown event handler. 有关详细信息,请参阅Office 项目中的事件For more information, see Events in Office projects.

了解生成的类的设计Understand the design of the generated classes

在目标为 .NET Framework 4.NET Framework 4.NET Framework 4.5.NET Framework 4.5的项目中, Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 中的宿主项类型为接口,因此生成的类不能从中派生其实现。In projects that target the .NET Framework 4.NET Framework 4 or the .NET Framework 4.5.NET Framework 4.5, the host item types in the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime are interfaces, so the generated classes cannot derive their implementation from them. 相反,生成的类从以下基类中派生其大多数成员:Instead, the generated classes derive most of their members from the following base classes:

  • ThisDocument:派生自 DocumentBaseThisDocument: derives from DocumentBase.

  • ThisWorkbook:派生自 WorkbookBaseThisWorkbook: derives from WorkbookBase.

  • Sheetn:派生WorksheetBase自。Sheet n: derives from WorksheetBase.

    这些基类将对其成员的所有调用重定向到 Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime中相应宿主项接口的内部实现。These base classes redirect all calls to their members to internal implementations of the corresponding host item interfaces in the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime. 例如,如果你调用 Protect 类的 ThisDocument 方法,则 DocumentBase 类将此调用重定向搭配 Document 中的 Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime接口的内部实现。For example, if you call the Protect method of the ThisDocument class, the DocumentBase class redirects this call to the internal implementation of the Document interface in the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime.

访问主机应用程序的对象模型Access the object model of the host application

若要访问主机应用程序的对象模型,请在项目中使用生成的类的成员。To access the object model of the host application, use members of the generated class in your project. 每个类均对应于 Excel 或 Word 对象模型中一个对象,并包含大多数相同的属性、方法和事件。Each of these classes corresponds to an object in the object model of Excel or Word, and they contain most of the same properties, methods, and events. 例如,Word 文档级别项目中的 ThisDocument 类提供与 Word 对象模型中的 Document 对象所提供的大多数相同的成员。For example, the ThisDocument class in a document-level project for Word provides most of the same members as the Document object in the Word object model.

以下代码示例演示如何使用 Word 对象模型来保存作为 Word 文档级自定义项的一部分的文档。The following code example shows how to use the Word object model to save the document that is part of a document-level customization for Word. 此示例应从 ThisDocument 类运行。This example is intended to be run from the ThisDocument class.

Me.Save()
this.Save();

若要从 ThisDocument 类的外部执行相同操作,请使用 Globals 对象访问 ThisDocument 类。To do the same thing from outside the ThisDocument class, use the Globals object to access the ThisDocument class. 例如,如果希望在操作窗格 UI 中包括“保存” 按钮,你可以将此代码添加到操作窗格代码文件中。For example, you can add this code to an actions pane code file if you want to include a Save button in the actions pane UI.

Globals.ThisDocument.Save()
Globals.ThisDocument.Save();

由于 ThisDocument 类从 Document 宿主项中获取了其大多数成员,所以在此代码中调用的 Save 方法实际上是 Save 宿主项的 Document 方法。Because the ThisDocument class obtains most of its members from the Document host item, the Save method that is called in this code is really the Save method of the Document host item. 此方法与 Word 对象模型中 Save 对象的 Document 方法相对应。This method corresponds to the Save method of the Document object in the Word object model.

有关使用 Word 和 Excel 对象模型的详细信息,请参阅word 对象模型概述excel 对象模型概述For more information about using the object models of Word and Excel, see Word object model overview and Excel object model overview.

有关Globals对象的详细信息,请参阅对 Office 项目中对象的全局访问For more information about the Globals object, see Global access to objects in Office projects.

向文档添加控件Add controls to documents

若要自定义文档的 UI,可以向文档图面添加 Windows 窗体控件或 宿主控件To customize the UI of the document, you can add Windows Forms controls or host controls to the document surface. 通过组合不同的控件集并编写代码,可将控件绑定到数据、从用户处收集信息并响应用户操作。By combining different sets of controls and writing code, you can bind the controls to data, collect information from the user, and respond to user actions.

宿主控件是用于扩展 Word 和 Excel 对象模型中某些对象的类。Host controls are classes that extend some of the objects in the Word and Excel object model. 例如, ListObject 宿主控件提供了 Excel 中的 ListObject 的所有功能。For example, the ListObject host control provides all of the functionality of the ListObject in Excel. 但是, ListObject 宿主控件还具有其他事件和数据绑定功能。However, the ListObject host control also has additional events and data binding capabilities.

有关详细信息,请参阅主机项和主机控件概述Office 文档上的 Windows 窗体控件概述For more information, see Host items and host controls overview and Windows forms controls on Office documents overview.

合并 VBA 和文档级自定义项Combine VBA and document-level customizations

可以在属于文档级自定义项的文档中使用 VBA 代码。You can use VBA code in a document that is part of a document-level customization. 可以从自定义程序集文档中调用 VBA 代码,也可以将项目配置为使文档中的 VBA 代码能够调用自定义程序集中的代码。You can call VBA code in the document from the customization assembly, and you can also configure your project to enable VBA code in the document to call code in the customization assembly.

有关详细信息,请参阅合并 VBA 和文档级自定义项For more information, see Combine VBA and document-level customizations.

管理服务器上的文档Manage documents on a server

你可以在未安装 Microsoft Office Word 或 Microsoft Office Excel 的服务器上管理文档级自定义项的几个不同方面。You can manage several different aspects of document-level customizations on a server that does not have Microsoft Office Word or Microsoft Office Excel installed. 例如,你可以访问和修改文档数据缓存中的数据。For example, you can access and modify data in the data cache of the document. 还可以管理与文档相关联的自定义程序集。You can also manage the customization assembly that is associated with the document. 例如,你可以以编程方式从文档中删除程序集以使该文档不再运行你的代码,或者以编程方式将程序集附加到文档。For example, you can programmatically remove the assembly from the document so that the document no longer runs your code, or you can programmatically attach an assembly to a document.

有关详细信息,请参阅使用 ServerDocument 类管理服务器上的文档For more information, see Manage documents on a server by using the ServerDocument class.

自定义 Microsoft Office 应用程序的用户界面Customize the user interface of Microsoft Office applications

使用文档级自定义项,你可以通过下列方式自定义 Word 和 Excel 的 UI:You can customize the UI of Word and Excel in the following ways by using a document-level customization:

从文档级自定义项中的本机 Office 对象中获取扩展的对象Get extended objects from native Office objects in document-level customizations

许多 Office 事件的事件处理程序可接受本机 Office 对象,这些对象表示工作簿、工作表或引发事件的文档。Many event handlers for Office events receive a native Office object that represents the workbook, worksheet, or document that raised the event. 在某些情况下,可能仅当工作簿或文档级自定义项中的文档引发事件时,才需要运行某些代码。In some cases, you might want to run some code only if the workbook or document in your document-level customization raised the event. 例如,在 Excel 文档级自定义项中,当用户激活自定义工作簿中的一个工作表时可能需要运行某些代码,而当用户激活当时恰好处于打开状态的其他工作簿中的工作表时则不运行。For example, in a document-level customization for Excel, you might want to run some code when the user activates one of the worksheets in the customized workbook, but not when the user activates a worksheet in some other workbook that happens to be open at the same time.

具有本机 Office 对象时,你可以测试该对象是否已扩展为文档级自定义项中的 宿主项宿主控件When you have a native Office object, you can test whether that object has been extended into a host item or host control in a document-level customization. 宿主项和宿主控件是由 Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime 提供的类型,可向以本机方式存在于 Word 或 Excel 对象模型中的对象(称为 本机 Office 对象)添加功能。Host items and host controls are types provided by the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime that add functionality to objects that exist natively in the Word or Excel object models (called native Office objects). 宿主项和宿主控件又统称 扩展的对象Collectively, host items and host controls are also called extended objects. 有关宿主项和宿主控件的详细信息,请参阅主机项和主机控件概述For more information about host items and host controls, see Host items and host controls overview.

了解 GetVstoObject 和 HasVstoObject 方法Understand the GetVstoObject and HasVstoObject methods

若要测试本机 Office 对象,请在项目中使用 HasVstoObjectGetVstoObject 方法:To test a native Office object, use the HasVstoObject and GetVstoObject methods in your project:

  • 如果你希望确定本机 Office 对象在自定义项中是否具有扩展的对象,请使用 HasVstoObject 方法。Use the HasVstoObject method if you want to determine whether the native Office object has an extended object in your customization. 如果本机 Office 对象具有扩展的对象,则此方法返回 true ,否则返回 falseThis method returns true if the native Office object has an extended object, and false otherwise.

  • 如果你希望获取本机 Office 对象的扩展对象,请使用 GetVstoObject 方法。Use the GetVstoObject method if you want to get the extended object for a native Office object. 如果指定的本机 Office 对象具有扩展的对象,则此方法返回 ListObjectWorkbookWorksheetDocument 对象。This method returns a ListObject, Workbook, Worksheet, or Document object if the specified native Office object has one. 否则, GetVstoObject将返回nullOtherwise, GetVstoObject returns null. 例如,如果指定的 Document 是 Word 文档项目中文档的基础对象,则 GetVstoObject 方法将返回 DocumentFor example, the GetVstoObject method returns a Document if the specified Document is the underlying object for the document in your Word document project.

    在文档级项目中,不能在运行时使用 GetVstoObject 方法创建新的 WorkbookWorksheetDocument 宿主项。In document-level projects, you cannot use the GetVstoObject method to create a new Workbook, Worksheet, or Document host item at run time. 此方法仅用于在设计时访问项目中现有的已生成宿主项。You can use this method only to access existing host items that are generated in your project at design time. 如果要在运行时创建新的宿主项,则必须开发 VSTO 外接程序项目。If you want to create new host items at run time, you must develop a VSTO Add-in project. 有关详细信息,请参阅主机项和主机控件的编程限制在运行时在 VSTO 外接程序中扩展 Word 文档和 Excel 工作簿For more information, see Programmatic limitations of host items and host controls and Extend Word documents and Excel workbooks in VSTO Add-ins at run time.

使用 GetVstoObject 和 HasVstoObject 方法Use the GetVstoObject and HasVstoObject methods

若要调用HasVstoObjectGetVstoObject方法,请使用Globals.Factory.GetVstoObjectGlobals.Factory.HasVstoObject方法,并传入要测试的本机 Word 或 Excel 对象(例如DocumentWorksheet)。To call the HasVstoObject and GetVstoObject method, use the Globals.Factory.GetVstoObject or Globals.Factory.HasVstoObject method, and pass in the native Word or Excel object (such as a Document or Worksheet) that you want to test.

请参阅See also