通过

项目文档级自定义项

  • 项目

在使用文档级自定义项扩展 Microsoft Office Word 或 Microsoft Office Excel 时，可以执行以下任务：

  • 通过使用应用程序的对象模型对其进行自动化。

  • 向文档图面添加控件。

  • 从自定义程序集调用文档中的 Visual Basic for Applications (VBA) 代码。

  • 从 VBA 调用自定义程序集中的代码。

  • 在文档位于未安装 Microsoft Office 的服务器上时管理其特定方面。

  • 自定义应用程序的用户界面 (UI)。

    适用于：本主题中的信息适用于 Excel 和 Word 的文档级项目。 有关详细信息，请参阅按 Office 应用程序和项目类型提供的功能。

    在文档级项目中编写代码与在 Visual Studio 中编写其他类型项目的代码在某些方面存在不同。 其中许多差异是由 Office 对象模型公开给托管代码的方式引起的。 有关详细信息，请参阅在 Office 解决方案中编写代码。

    有关文档级自定义项和可以使用 Visual Studio 中的 Office 开发工具创建的其他类型的解决方案的一般信息，请参阅 Office 解决方案开发概述 (VSTO)。

在文档级项目中使用生成的类

创建文档级项目时，Visual Studio 将在项目中自动生成一个可用开始编写代码的类。 Visual Studio 针对 Word 和 Excel 生成不同的类：

  • 在 Word 文档级项目中，默认情况下此类称为 ThisDocument 。

  • Excel 文档级项目具有多个生成的类：一个用于工作簿本身，一个用于每一工作表。 默认情况下，这些类具有以下名称：

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    生成的类包含在打开或关闭文档时调用的事件处理程序。 若要在打开文档时运行代码，请将代码添加到 Startup 事件处理程序。 若要在关闭文档后立即运行代码，请将代码添加到 Shutdown 事件处理程序。 有关详细信息，请参阅 Office 项目中的事件。

了解生成的类的设计

在面向 .NET Framework 4 或 .NET Framework 4.5 的项目中，Visual Studio Tools for Office Runtime 中的主机项类型是接口，因此生成的类无法从中派生其实现。 相反，生成的类从以下基类中派生其大多数成员：

  • ThisDocument：派生自 DocumentBase。

  • ThisWorkbook：派生自 WorkbookBase。

  • Sheet n：派生自 WorksheetBase。

    这些基类将对其成员的所有调用重定向到 Visual Studio Tools for Office Runtime 中相应主机项接口的内部实现。 例如，如果你调用 ThisDocument 类的 Protect 方法，则 DocumentBase 类将此调用重定向到 Visual Studio Tools for Office Runtime 中 Document 接口的内部实现。

访问主机应用程序的对象模型

若要访问主机应用程序的对象模型，请在项目中使用生成的类的成员。 每个类均对应于 Excel 或 Word 对象模型中一个对象，并包含大多数相同的属性、方法和事件。 例如，Word 文档级别项目中的 ThisDocument 类提供与 Word 对象模型中的 Document 对象所提供的大多数相同的成员。

以下代码示例演示如何使用 Word 对象模型来保存作为 Word 文档级自定义项的一部分的文档。 此示例应从 ThisDocument 类运行。

this.Save();

若要从 ThisDocument 类的外部执行相同操作，请使用 Globals 对象访问 ThisDocument 类。 例如，如果希望在操作窗格 UI 中包括“保存” 按钮，你可以将此代码添加到操作窗格代码文件中。

Globals.ThisDocument.Save();

由于 ThisDocument 类从 Document 宿主项中获取了其大多数成员，所以在此代码中调用的 Save 方法实际上是 Save 宿主项的 Document 方法。 此方法与 Word 对象模型中 Save 对象的 Document 方法相对应。

有关使用 Word 和 Excel 对象模型的详细信息，请参阅 Word 对象模型概述和 Excel 对象模型概述。

有关 Globals 对象的详细信息，请参阅对 Office 项目中对象的全局访问。

向文档添加控件

若要自定义文档的 UI，可以向文档图面添加 Windows 窗体控件或 宿主控件 。 通过组合不同的控件集并编写代码，可将控件绑定到数据、从用户处收集信息并响应用户操作。

宿主控件是用于扩展 Word 和 Excel 对象模型中某些对象的类。 例如， ListObject 宿主控件提供了 Excel 中的 ListObject 的所有功能。 但是， ListObject 宿主控件还具有其他事件和数据绑定功能。

有关详细信息，请参阅主机项和主机控件概述 和 Office 文档上的 Windows 窗体控件概述。

结合 VBA 和文档级自定义项

可以在属于文档级自定义项的文档中使用 VBA 代码。 可以从自定义程序集文档中调用 VBA 代码，也可以将项目配置为使文档中的 VBA 代码能够调用自定义程序集中的代码。

有关详细信息，请参阅结合 VBA 和文档级自定义项。

在服务器上管理文档

你可以在未安装 Microsoft Office Word 或 Microsoft Office Excel 的服务器上管理文档级自定义项的几个不同方面。 例如，你可以访问和修改文档数据缓存中的数据。 还可以管理与文档相关联的自定义程序集。 例如，你可以以编程方式从文档中删除程序集以使该文档不再运行你的代码，或者以编程方式将程序集附加到文档。

有关详细信息，请参阅使用 ServerDocument 类管理服务器上的文档。

自定义 Microsoft Office 应用程序的用户界面

使用文档级自定义项，你可以通过下列方式自定义 Word 和 Excel 的 UI：

从文档级自定义项中的本机 Office 对象中获取扩展的对象

许多 Office 事件的事件处理程序可接受本机 Office 对象，这些对象表示工作簿、工作表或引发事件的文档。 在某些情况下，可能仅当工作簿或文档级自定义项中的文档引发事件时，才需要运行某些代码。 例如，在 Excel 文档级自定义项中，当用户激活自定义工作簿中的一个工作表时可能需要运行某些代码，而当用户激活当时恰好处于打开状态的其他工作簿中的工作表时则不运行。

具有本机 Office 对象时，你可以测试该对象是否已扩展为文档级自定义项中的 宿主项 或 宿主控件 。 主机项和主机控件是由 Visual Studio Tools for Office Runtime 提供的类型，该运行时可将功能添加到存在于 Word 或 Excel 对象模型中的本机对象（称为本机 Office 对象）。 宿主项和宿主控件又统称 扩展的对象。 有关主机项和主机控件的详细信息，请参阅主机项和主机控件概述。

了解 GetVstoObject 和 HasVstoObject 方法

若要测试本机 Office 对象，请在项目中使用 HasVstoObject 和 GetVstoObject 方法：

  • 如果你希望确定本机 Office 对象在自定义项中是否具有扩展的对象，请使用 HasVstoObject 方法。 如果本机 Office 对象具有扩展的对象，则此方法返回 true ，否则返回 false 。

  • 如果你希望获取本机 Office 对象的扩展对象，请使用 GetVstoObject 方法。 如果指定的本机 Office 对象具有扩展的对象，则此方法返回 ListObject、 Workbook、 Worksheet或 Document 对象。 否则，GetVstoObject 返回 null。 例如，如果指定的 Document 是 Word 文档项目中文档的基础对象，则 GetVstoObject 方法将返回 Document。

    在文档级项目中，不能使用 GetVstoObject 方法在运行时创建新的 Workbook、Worksheet 或 Document 主机项。 此方法仅用于在设计时访问项目中现有的已生成宿主项。 如果想要在运行时创建新的主机项，则必须开发 VSTO 外接程序项目。 有关详细信息，请参阅主机项和主机控件的编程限制和在运行时扩展 VSTO 外接程序中的 Word 文档和 Excel 工作簿。

使用 GetVstoObject 和 HasVstoObject 方法

若要调用 HasVstoObject 和 GetVstoObject 方法，请使用 Globals.Factory.GetVstoObject 或 Globals.Factory.HasVstoObject 方法，并传入要测试的本机 Word 或 Excel 对象（如 Document 或 Worksheet）。

相关内容