程式檔層級自訂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 物件模型公開給 Managed 程式碼的方式。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 方案開發總覽 (VSTO)For 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:衍生自 WorksheetBaseSheet 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 類別會將此呼叫重新導向至 DocumentVisual 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 Forms 控制項或 「主控制項」 (host control) 加入文件介面。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 forms 控制項總覽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 物件時,可以測試該物件是否已擴充成為文件層級自訂中的 「主項目」 (host item) 或 「主控制項」 (host control)。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 物件」(native Office object)。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). 通常,主項目和主控制項也稱為 「擴充物件」(extended object)。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 方法 Workbook 在執行時間建立新的、 WorksheetDocument 主專案。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 物件 (例如 Document Worksheet 您要測試的或) 。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