在執行階段將控制項加入至 Office 文件

發行項
08/21/2008

更新： 2008 年 7 月

適用於
本主題中的資訊僅適用於指定的 Visual Studio Tools for Office 專案和 Microsoft Office 版本。文件層級專案 Excel 2003 Excel 2007 Word 2003 Word 2007 應用程式層級專案 Excel 2007 Word 2007 如需詳細資訊，請參閱依應用程式和專案類型提供的功能。

本主題中的資訊僅適用於指定的 Visual Studio Tools for Office 專案和 Microsoft Office 版本。

文件層級專案

Excel 2003
Excel 2007
Word 2003
Word 2007

應用程式層級專案

Excel 2007
Word 2007

您可以在執行階段於 Microsoft Office Word 文件和 Microsoft Office Excel 活頁簿中加入和移除控制項。在執行階段加入至文件的控制項稱為「動態控制項」(Dynamic Control)。從 Visual Studio 2008 Service Pack 1 (SP1) 開始，您可以使用應用程式層級的增益集，將動態控制項加入至文件和活頁簿。

本主題提供下列資訊：

在執行階段使用控制項集合管理控制項
將主控制項加入至文件
將 Windows Form 控制項加入至文件

在執行階段使用控制項集合管理控制項

若要在執行階段加入、取得或移除控制項，請使用 Microsoft.Office.Tools.Excel.ControlCollection 和 Microsoft.Office.Tools.Word.ControlCollection 類別的 Helper 方法。

存取控制項集合的方式，取決於您所開發的專案類型：

在 Excel 文件層級專案中，請使用 Sheet1、Sheet2 和 Sheet3 類別的 Worksheet.Controls 屬性。如需這些類別的詳細資訊，請參閱Worksheet 主項目。
在 Word 文件層級專案中，請使用 ThisDocument 類別的 Document.Controls 屬性。如需這個類別的詳細資訊，請參閱Document 主項目。
在 Excel 或 Word 應用程式層級專案中，請使用您在執行階段產生之 Microsoft.Office.Tools.Excel.Worksheet 或 Microsoft.Office.Tools.Word.Document 的 Controls 屬性。如需在執行階段產生這些物件的詳細資訊，請參閱在應用程式層級增益集的執行階段中擴充 Word 文件和 Excel 活頁簿。

加入控制項

Microsoft.Office.Tools.Excel.ControlCollection 和 Microsoft.Office.Tools.Word.ControlCollection 類別包含可將主控制項和通用 Windows Form 控制項加入至文件和工作表的 Helper 方法。每個方法的名稱都是 Add<control class> 格式，其中 control class 是您要加入的控制項類別名稱。例如，若要將 NamedRange 控制項加入文件，請使用 AddNamedRange 方法。如需完整的 Helper 方法清單，請參閱主控制項的 Helper 方法和 Windows Form 控制項的 Helper 方法。

下列程式碼範例會將 NamedRange 加入至 Excel 文件層級專案中的 Sheet1。

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

存取及刪除控制項

您可以使用 Microsoft.Office.Tools.Excel.Worksheet 或 Microsoft.Office.Tools.Word.Document 的 Controls 屬性，逐一查看文件中的所有控制項，包括您在設計階段加入的控制項。在設計階段加入的控制項也稱為「靜態控制項」(Static Control)。

您可以呼叫控制項的 Delete 方法，或呼叫每個 Controls 集合的 Remove 方法，以移除動態控制項。下列程式碼範例會使用 Remove 方法，從 Excel 文件層級專案中的 Sheet1 移除 NamedRange。

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

您不能在執行階段移除靜態控制項。如果您嘗試使用 Delete 或 Remove 方法移除靜態控制項，就會擲回 CannotRemoveControlException。

注意事項：
請勿以程式設計方式移除文件之 Shutdown 事件處理常式中的控制項。引發 Shutdown 事件時，文件的 UI 項目便無法再使用。如果您想要在文件關閉前移除控制項，請將程式碼加入其他事件的這個事件處理常式，例如 Word 的 Document.BeforeClose 或 Document.BeforeSave，或者是 Excel 的 Workbook.BeforeClose 或 Workbook.BeforeSave。

請勿以程式設計方式移除文件之 Shutdown 事件處理常式中的控制項。引發 Shutdown 事件時，文件的 UI 項目便無法再使用。如果您想要在文件關閉前移除控制項，請將程式碼加入其他事件的這個事件處理常式，例如 Word 的 Document.BeforeClose 或 Document.BeforeSave，或者是 Excel 的 Workbook.BeforeClose 或 Workbook.BeforeSave。

將主控制項加入至文件

當您以程式設計方式將主控制項加入至文件時，必須提供能夠唯一識別控制項的名稱，而且必須指定要將控制項加入至文件中的哪個位置。如需特定指示，請參閱下列主題：

如需主控制項的詳細資訊，請參閱主項目和主控制項概觀。

當儲存並關閉文件時，所有動態建立的主控制項都會中斷與其事件的連接，而且也會失去資料繫結功能。您可以在方案中加入程式碼，在重新開啟文件時重新建立主控制項。如需詳細資訊，請參閱在 Office 文件中保存動態控制項。

注意事項：
針對下列主控制項，並不會提供 Helper 方法，因為這些控制項無法以程式設計方式加入至文件：XmlMappedRange、XMLNode 和 XMLNodes。

將 Windows Form 控制項加入至文件

當您以程式設計方式將 Windows Form 控制項加入至文件時，必須提供控制項位置和該控制項的唯一識別名稱。Visual Studio Tools for Office 會為每個控制項提供 Helper 方法。這些方法都是多載，所以您可以傳遞範圍或特定座標做為控制項的位置。如需特定指示，請參閱 HOW TO：將 Windows Form 控制項加入至 Office 文件。

當儲存並關閉文件時，所有動態建立的 Windows Form 控制項都會從文件移除。您可以在方案中加入程式碼，在重新開啟文件時重新建立控制項。如果您使用應用程式層級的增益集來建立動態 Windows Form 控制項，則控制項的 ActiveX 包裝函式會遺留在文件中。如需詳細資訊，請參閱在 Office 文件中保存動態控制項。

注意事項：
Windows Form 控制項不能以程式設計的方式加入至受保護的文件。如果您以程式設計方式取消保護 Word 文件或 Excel 工作表以加入控制項，就必須撰寫其他程式碼以在文件關閉時移除控制項的 ActiveX 包裝函式。控制項的 ActiveX 包裝函式並不會自動從受保護的文件刪除。

加入自訂控制項

如果您要加入這些可用之 Helper 方法不支援的 System.Windows.Forms.Control (例如，自訂使用者控制項)，請使用下列方法：

對於 Excel，請使用 Microsoft.Office.Tools.Excel.ControlCollection 類別的其中一個 AddControl() 方法。
對於 Word，請使用 Microsoft.Office.Tools.Word.ControlCollection 類別的其中一個 AddControl() 方法。

若要加入控制項，請將 System.Windows.Forms.Control、控制項位置以及可唯一識別該控制項的名稱傳遞至 AddControl 方法。對於 Excel，這個方法會傳回 OLEObject。對於 Word，這個方法會傳回 OLEControl。這些物件會定義控制項與工作表或文件的互動方式。

下列程式碼範例會示範如何使用 AddControl(Control, Range, String) 方法，動態將自訂控使用者制項加入至工作表。在這個範例中，使用者控制項名為 UserControl1，而 Range 名為 range1。這個範例會假設是從 Excel 文件層級專案的其中一個 Sheetn 類別執行。

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.OLEObject = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.OLEObject dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

使用自訂控制項的成員

使用其中一個 AddControl 方法將控制項加入至工作表或文件之後，您現在就有兩個不同的控制項物件：

表示自訂控制項的 System.Windows.Forms.Control。
表示已加入至工作表或文件之控制項的 OLEObject 或 OLEControl。

這些控制項會共用許多屬性與方法。請務必透過適當的控制項存取這些方法與屬性：

若要存取只屬於自訂控制項的屬性與方法，請使用 System.Windows.Forms.Control。
若要存取這些控制項共用的屬性與方法，請使用 OLEObject 或 OLEControl。

如果從 System.Windows.Forms.Control 存取共用方法或屬性，則會在沒有警告或通知的情況下失敗，或產生無效的結果。請務必使用 OLEObject 或 OLEControl 的方法或屬性，除非所需的方法或屬性無法使用，那時才能參考 System.Windows.Forms.Control。

例如，OLEObject 類別和 System.Windows.Forms.Control 類別都有 Top 屬性。若要取得或設定控制項頂端與文件頂端之間的距離，請使用 OLEObject 的 Top 屬性，而非 System.Windows.Forms.Control 的 Top 屬性。

' Property is set in relation to the document.
dynamicControl.Top = 100

' Property is set in relation to the container control.
customControl.Top = 100

// Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

請參閱

變更記錄

日期	記錄	原因
2008 年 7 月	加入新資訊，說明如何使用應用程式層級增益集將控制項加入至文件。	SP1 功能變更。

2008 年 7 月

加入新資訊，說明如何使用應用程式層級增益集將控制項加入至文件。

SP1 功能變更。