在執行階段將控制項新增至 Office 文件

  • 發行項

您可以在執行階段將控制項加入 Microsoft Office Word 文件與 Microsoft Office Excel 活頁簿中。 您也可以在執行階段加以移除。 您在執行階段加入或移除的控制項稱為 動態控制項。

適用對象：本主題資訊適用於文件層級的專案和 Excel 和 Word的 VSTO 增益集專案。 如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

本主題說明下列項目：

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

若要在執行階段加入、取得或移除控制項，請使用 ControlCollection 與 ControlCollection 物件的 Helper 方法。

您存取這些物件的方式，取決於您所開發的專案類型：

新增控制項

ControlCollection 與 ControlCollection 類型包括 Helper 方法，其可用來將主控制項和通用 Windows Form 控制項加入文件與工作表中。 Each method name has the format Addcontrol class, where control class is the class name of the control that you want to add. 例如，若要將 NamedRange 控制項加入文件中，請使用 AddNamedRange 方法。

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

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

存取和刪除控制項

您可以使用 Worksheet 或 Document 的 Controls 屬性來逐一查看文件中的所有控制項，包括在設計階段加入的控制項。 您在設計階段加入的控制項也稱為 靜態控制項。

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

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

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

注意

在文件的 Shutdown 事件處理常式中，請勿以程式設計方式移除控制項。 當 Shutdown 事件受到引發時，文件的 UI 項目便無法再使用。 如果您想在文件關閉前移除控制項，請將程式碼加入另一個事件的事件處理常式中，例如 BeforeClose 或 BeforeSave (針對 Word)，或是 BeforeClose或 BeforeSave (針對 Excel)。

將主控制項加入文件中

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

如需主控制項的詳細資訊，請參閱 Host Items and Host Controls Overview。

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

注意

未替下列主控制項提供 Helper 方法，原因是這些控制項不能以程式設計方式加入文件中： XmlMappedRange、 XMLNode與 XMLNodes。

將 Windows Form 控制項加入文件中

在您以程式設計方式將 Windows Form 控制項加入文件中時，您必須提供控制項位置，以及控制項的唯一識別名稱。 Visual Studio Tools for Office Runtime 為每個控件項提供協助程式方法。 這些方法受到多載，以便讓您為控制項的位置傳遞一定範圍或特定的座標。

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

注意

Windows Form 控制項無法以程式設計方式加入受保護的文件中。 如果您以程式設計方式將 Word 文件或 Excel 工作表取消保護以加入控制項，則您必須撰寫額外的程式碼，以便在文件關閉時移除控制項的 ActiveX 包裝函式。 控制項的 ActiveX 包裝函式不會自動從受保護的文件刪除。

新增自訂控制項

如果您想要加入 Control ，而其不受可用的 Helper 方法支援 (例如自訂使用者控制項)，請使用下列方法：

  • 針對 Excel，請使用 AddControl 物件的其中一種 ControlCollection 方法 。

  • 針對 Word，請使用 AddControl 物件的其中一種 ControlCollection 方法 。

    若要加入控制項，請將 Control、控制項的位置，以及控制項的唯一識別名稱傳遞至 AddControl 方法。 AddControl 方法會傳回物件，其會定義控制項與工作表或文件互動的方式。 AddControl 方法會傳回 ControlSite (對於 Excel) 或 ControlSite 物件 (對於 Word)。

    下列程式碼範例示範如何使用 AddControl 方法，以動態方式將自訂使用者控制項加入文件層級 Excel 專案的工作表中。 在此範例中，使用者控制項名為 UserControl1，而 Range 名為 range1。 若要使用此範例，請從專案中的 Sheetn 類別加以執行。

    UserControl1 customControl = new UserControl1();

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

使用自訂控制項的成員

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

  • Control 代表自訂控制項。

  • ControlSite、OLEObject 或 OLEControl 物件，代表加入工作表或文件中後的控制項。

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

  • 若要存取僅屬於自訂控制項的成員，請使用 Control。

  • 若要存取控制項所共用的成員，請使用 ControlSite、OLEObject 或 OLEControl 物件。

    如果您從 Control存取共用的成員，其可能會在沒有警告或通知的情況下失敗，或產生無效的結果。 除非所需的方法或屬性無法使用，否則一律使用 ControlSite、OLEObject 或 OLEControl 物件的方法或屬性；只有在方法或屬性無法使用時參考 Control。

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

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

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

相關內容