実行時に Office ドキュメントにコントロールを追加します。Add controls to Office documents at runtime

コントロールは、Microsoft Office Word 文書と実行時に Microsoft Office Excel ブックを追加することができます。You can add controls to a Microsoft Office Word document and Microsoft Office Excel workbook at runtime. 実行時にも削除できます。You can also remove them at runtime. コントロールを追加または削除時に呼び出されるダイナミック コントロールします。Controls that you add or remove at runtime are called dynamic controls.

適用対象: このトピックの情報は、ドキュメントに適用されます-レベルのプロジェクトおよび VSTO 追加-Excel および Word プロジェクトでします。Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for Excel and Word. 詳細については、「Office アプリケーションおよびプロジェクトの種類で使用できる機能」を参照してください。For more information, see Features available by Office application and project type.

このトピックでは、次のことについて説明します。This topic describes the following:

コントロールのコレクションを使用して実行時にコントロールを管理します。Manage controls at runtime by using control collections

追加、取得、または実行時にコントロールを削除してのヘルパー メソッドを使用して、ControlCollectionControlCollectionオブジェクト。To add, get, or remove controls at runtime, use helper methods of ControlCollection and ControlCollection objects.

これらのオブジェクトにアクセスする方法は、開発しているプロジェクトの種類によって異なります。The way that you access these objects depends on the type of project you are developing:

  • Excel のドキュメント レベルのプロジェクトでは、 Controls クラス、 Sheet1クラス、および Sheet2クラスの Sheet3 プロパティを使用します。In a document-level project for Excel, use the Controls property of the Sheet1, Sheet2, and Sheet3 classes. これらのクラスの詳細については、次を参照してください。 Worksheet ホスト項目します。For more information about these classes, see Worksheet host item.

  • Word のドキュメント レベルのプロジェクトでは、 Controls クラスの ThisDocument プロパティを使用します。In a document-level project for Word, use the Controls property of the ThisDocument class. このクラスの詳細については、次を参照してください。 Document ホスト項目します。For more information about this class, see Document host item.

  • Excel または Word の VSTO アドイン プロジェクトで使用して、ControlsのプロパティをWorksheetまたはDocument実行時に生成します。In a VSTO Add-in project for Excel or Word, use the Controls property of a Worksheet or Document that you generate at runtime. 実行時にこれらのオブジェクトを生成する詳細については、次を参照してください。拡張 Word 文書や Excel ブックを実行時に VSTO アドインでします。For more information about generating these objects at runtime, see Extend Word documents and Excel workbooks in VSTO Add-ins at runtime.

コントロールを追加します。Add controls

ControlCollection 型と ControlCollection 型には、ドキュメントとワークシートにホスト コントロールや Windows フォームのコモン コントロールを追加するために使用できるヘルパー メソッドが含まれています。The ControlCollection and ControlCollection types include helper methods that you can use to add host controls and common Windows Forms controls to documents and worksheets. 各メソッドの名前は、 Addコントロール クラスという形式になっています。ここで、 コントロール クラス は、追加するコントロールのクラス名です。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 メソッドを使用します。For example, to add a NamedRange control to your document, use the AddNamedRange method.

Excel のドキュメント レベルのプロジェクトで NamedRangeSheet1 に追加する方法を次のコード例に示します。The following code example adds a NamedRange to Sheet1 in a document-level project for Excel.

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");

アクセスと削除の制御Access and delete controls

Worksheet または DocumentControls プロパティを使用すると、デザイン時に追加したコントロールを含め、ドキュメント内のすべてのコントロールを反復処理できます。You can use the Controls property of a Worksheet or Document to iterate through all the controls in your document, including the controls you added at design time. デザイン時に追加するコントロールは、 スタティック コントロールとも呼ばれます。Controls that you add at design time are also called static controls.

ダイナミック コントロールを削除するには呼び出すことによって、Delete方法、コントロールのまたは呼び出すことによって、Removeメソッドの各コントロールのコレクション。You can remove dynamic controls by calling the Delete method of the control, or by calling the Remove method of each Controls collection. 次のコード例では、Excel のドキュメント レベルのプロジェクトで Remove メソッドを使用して NamedRangeSheet1 から削除します。The following code example uses the Remove method to remove a NamedRange from Sheet1 in a document-level project for Excel.

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

実行時にスタティック コントロールを削除することはできません。You cannot remove static controls at runtime. Delete メソッドまたは Remove メソッドを使用してスタティック コントロールを削除しようとすると、CannotRemoveControlException がスローされます。If you try to use the Delete or Remove method to remove a static control, a CannotRemoveControlException will be thrown.

Note

ドキュメントの Shutdown イベント ハンドラーの中で、プログラムによってコントロールを削除しないでください。Do not programmatically remove controls in the Shutdown event handler of the document. Shutdown イベントが発生する時点では、ドキュメントの UI 要素は利用できなくなっています。The UI elements of the document are no longer available when the Shutdown event is raised. ドキュメントを閉じる前にコントロールを削除するには、Word では BeforeCloseBeforeSave 、Excel では BeforeCloseBeforeSave など、別のイベントのイベント ハンドラーにコードを追加してください。If you want to remove controls before the document closes, add your code to the event handler for another event, such as BeforeClose or BeforeSave for Word, or BeforeClose, or BeforeSave for Excel.

ホスト コントロールをドキュメントに追加します。Add host controls to documents

ホスト コントロールをプログラムでドキュメントに追加するには、そのコントロールを一意に識別する名前を指定し、ドキュメント上にコントロールを追加する場所を指定する必要があります。When you programmatically add host controls to documents, you must provide a name that uniquely identifies the control, and you must specify where to add the control on the document. 具体的な手順については、次のトピックを参照してください。For specific instructions, see the following topics:

ホスト コントロールの詳細については、次を参照してください。ホスト項目とホスト コントロールの概要します。For more information about host controls, see Host items and host controls overview.

ドキュメントを保存して閉じると、動的に作成したすべてのホスト コントロールはそれぞれイベントから切断され、データ バインディング機能も失われます。When a document is saved and then closed, all dynamically created host controls are disconnected from their events and they lose their data binding functionality. ソリューションにコードを追加すれば、ドキュメントが再び開かれる時点でホスト コントロールを再作成するようにできます。You can add code to your solution to re-create the host controls when the document is reopened. 詳細については、次を参照してください。 Office ドキュメントでのダイナミック コントロールを永続化します。For more information, see Persist dynamic controls in Office documents.

Note

XmlMappedRangeXMLNode、および XMLNodesの各ホスト コントロールは、プログラムでドキュメントに追加することができないため、ヘルパー メソッドは用意されていません。Helper methods are not provided for the following host controls, because these controls cannot be added programmatically to documents: XmlMappedRange, XMLNode, and XMLNodes.

Windows フォーム コントロールをドキュメントに追加します。Add Windows Forms controls to documents

Windows フォーム コントロールをプログラムでドキュメントに追加する場合は、コントロールの場所とコントロールを一意に識別する名前を指定する必要があります。When you programmatically add a Windows Forms control to a document, you must provide the location of the control and a name that uniquely identifies the control. Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime が、各コントロールのヘルパー メソッドを提供します。The Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime provides helper methods for each control. これらのメソッドはオーバーロードされているため、コントロールの場所として範囲または特定の座標のいずれかを渡すことができます。These methods are overloaded so that you can pass either a range or specific coordinates for the location of the control.

ドキュメントを保存して閉じると、動的に作成されたすべての Windows フォーム コントロールはドキュメントから削除されます。When a document is saved and then closed, all dynamically created Windows Forms controls are removed from the document. ソリューションにコードを追加すれば、ドキュメントが再び開かれる時点でコントロールを再作成するようにできます。You can add code to your solution to re-create the controls when the document is reopened. VSTO アドインを使用してダイナミック Windows フォーム コントロールを作成する場合は、コントロールの ActiveX ラッパーがドキュメントに残されます。If you create dynamic Windows Forms controls by using a VSTO Add-in, the ActiveX wrappers for the controls are left in the document. 詳細については、次を参照してください。 Office ドキュメントでのダイナミック コントロールを永続化します。For more information, see Persist dynamic controls in Office documents.

Note

Windows フォーム コントロールは、保護されているドキュメントにはプログラムで追加できません。Windows Forms controls cannot be programmatically added to protected documents. コントロールを追加するために、Word 文書または Excel ワークシートの保護をプログラムで解除する場合は、ドキュメントを閉じるときにコントロールの ActiveX ラッパーを削除するコードを追加で記述する必要があります。If you programmatically unprotect a Word document or Excel worksheet to add a control, you must write additional code to remove the control's ActiveX wrapper when the document is closed. コントロールの ActiveX ラッパーは、保護されたドキュメントから自動的には削除されません。The control's ActiveX wrapper is not automatically deleted from protected documents.

カスタム コントロールの追加Add custom controls

カスタム ユーザー コントロールなど、使用可能なヘルパー メソッドによってサポートされていない Control を追加するには、次のメソッドを使用します。If you want to add a Control that is not supported by the available helper methods, such as a custom user control, use the following methods:

  • Excel では、 AddControl オブジェクトの ControlCollection メソッドの 1 つを使用します。For Excel, use one of the AddControl methods of a ControlCollection object.

  • Word では、 AddControl オブジェクトの ControlCollection メソッドの 1 つを使用します。For Word, use one of the AddControl methods of a ControlCollection object.

    コントロールを追加するには、Control、コントロールの場所、およびコントロールを一意に識別する名前を AddControl メソッドに渡します。To add the control, pass the Control, a location for the control, and a name that uniquely identifies the control to the AddControl method. AddControl メソッドは、コントロールがワークシートまたはドキュメントとどのようにやり取りするかを定義するオブジェクトを返します。The AddControl method returns an object that defines how the control interacts with the worksheet or document. AddControlメソッドを返します。 をControlSite(for Excel) またはControlSite(Word) のオブジェクト。The AddControl method returns a ControlSite (for Excel) or a ControlSite object (for Word).

    次のコード例は、 AddControl メソッドを使用して、ドキュメント レベルの Excel プロジェクトのワークシートにカスタム ユーザー コントロールを動的に追加する方法を示しています。The following code example demonstrates how to use the AddControl method to dynamically add a custom user control to a worksheet in a document-level Excel project. この例では、ユーザー コントロールの名前は UserControl1で、 Range の名前は range1です。In this example, the user control is named UserControl1, and the Range is named range1. このコード例を使用するには、プロジェクトの Sheetn クラスから実行します。To use this example, run it from a Sheetn class in the project.

    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");
    

カスタム コントロールのメンバーを使用します。Use members of custom controls

AddControl メソッドの 1 つを使用してワークシートまたは文書にコントロールを追加すると、次の 2 つの異なるコントロール オブジェクトが存在するようになります。After using one of the AddControl methods to add a control to a worksheet or document, you now have two different control objects:

  • カスタム コントロールを表す ControlThe Control that represents the custom control.

  • ワークシートまたは文書に追加された後のコントロールを表す ControlSiteOLEObject、または OLEControl オブジェクト。The ControlSite, OLEObject, or OLEControl object that represents the control after it was added to the worksheet or document.

    これらのコントロールには、共有されているプロパティやメソッドが多数あります。Many properties and methods are shared between these controls. これらのメンバーには、適切なコントロールを介してアクセスすることが重要です。It is important that you access these members through the appropriate control:

  • カスタム コントロールのみに属するメンバーにアクセスするには、 Controlを使用します。To access members that belong only to the custom control, use the Control.

  • 複数のコントロールで共有されているメンバーにアクセスするには、ControlSiteOLEObject、または OLEControl オブジェクトを使用します。To access members that are shared by the controls, use the ControlSite, OLEObject, or OLEControl object.

    共有されているメンバーに Controlからアクセスすると、警告や通知なしに失敗したり、無効な結果が生成されたりすることがあります。If you access a shared member from the Control, it might fail without warning or notification, or it can produce invalid results. 通常は ControlSiteOLEObject、または OLEControl オブジェクトのメソッドまたはプロパティを使用し、必要なメソッドやプロパティを使用できない場合に限って Control を参照してください。Always use methods or properties of the ControlSite, OLEObject, or OLEControl object unless the method or property needed is not available; only then should you reference the Control.

    たとえば、Top プロパティは、ControlSite クラスと Control クラスの両方に存在します。For example, both the ControlSite class and the Control class have a Top property. コントロールの上端からドキュメントの先頭までの間の距離を取得または設定するには、 TopControlSiteプロパティではなく、 TopControlプロパティを使用してください。To get or set the distance between the top of the control and the top of the document, use the Top property of the ControlSite, not the Top property of the Control.

    ' 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;
    

関連項目See also