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

發行項
02/28/2013

您可以將控制項加入至 Microsoft Office Word 文件和 Microsoft Office Excel 活頁簿快取。您也可以移除它們在執行階段。您新增或移除在執行階段的控制項稱為動態控制項。

**適用於：**本主題中的資訊適用於下列應用程式的文件層級專案和應用程式層級專案：Excel 2013 和 Excel 2010、Word 2013 和 Word 2010。如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

本主題描述下列:

在執行階段管理控制項使用控制項集合。
將主控制項加入至文件。
將 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控制類別，其中控制類別是您要加入控制項的類別名稱。例如，若要將 NamedRange 控制項加入文件，請使用 AddNamedRange 方法。

下列程式碼範例會將 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 Runtime 會為每個控制項提供 Helper 方法。這些方法多載，所以您可以將範圍或特定座標做為控制項的位置。

當儲存並關閉文件時，所有動態建立的 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 方法。AddControl 方法會傳回物件，該物件會定義控制項與工作表或文件互動的方式。AddControl 方法傳回 Microsoft.Office.Tools.Excel.ControlSite (適用於 Excel) 或 Microsoft.Office.Tools.Word.ControlSite 物件 (適用於 Word)。

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

Dim customControl As New UserControl1()

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

UserControl1 customControl = new UserControl1();

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

使用自訂控制項的成員

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

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

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

若要存取只屬於自訂控制項的成員，請使用 System.Windows.Forms.Control。
若要存取控制項共用的成員，請使用 ControlSite、OLEObject 或 OLEControl 物件。

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

例如，ControlSite 類別和 System.Windows.Forms.Control 類別都有 Top 屬性。若要取得或設定控制項頂端與文件頂端之間的距離，請使用 ControlSite 的 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;

請參閱

共用方式為