実行時に Office ドキュメントにコントロールを追加する

  • [アーティクル]

コントロールは、実行時に、Microsoft Office Word 文書と Microsoft Office Excel ブックに追加できます。 それらを実行時に削除することもできます。 実行時にドキュメントに追加したりドキュメントから削除したりするコントロールのことを、 ダイナミック コントロールといいます。

対象: このトピックの情報は、Excel および Word のドキュメントレベルのプロジェクトおよび VSTO アドインのプロジェクトに適用されます。 詳細については、「Office アプリケーションおよびプロジェクトの種類別の使用可能な機能」を参照してください。

このトピックでは、次の項目について説明します。

コントロール コレクションを使用して実行時にコントロールを管理する

実行時にコントロールを追加、取得、または削除するには、 ControlCollection オブジェクトと ControlCollection オブジェクトのヘルパー メソッドを使用します。

これらのオブジェクトにアクセスする方法は、開発しているプロジェクトの種類によって異なります。

  • Excel のドキュメント レベルのプロジェクトでは、 Controls クラス、 Sheet1クラス、および Sheet2クラスの Sheet3 プロパティを使用します。 これらのクラスについて詳しくは、「Worksheet ホスト項目」をご覧ください。

  • Word のドキュメント レベルのプロジェクトでは、 Controls クラスの ThisDocument プロパティを使用します。 このクラスについて詳しくは、「Document ホスト項目」をご覧ください。

  • Excel または Word の VSTO アドイン プロジェクトでは、実行時に生成した Worksheet または Document の Controls プロパティを使用します。 これらのオブジェクトを実行時に生成する方法について詳しくは、「実行時に VSTO アドインの Word 文書と Excel ブックを拡張する」をご覧ください。

コントロールの追加

ControlCollection 型と ControlCollection 型には、ドキュメントとワークシートにホスト コントロールや Windows フォームのコモン コントロールを追加するために使用できるヘルパー メソッドが含まれています。 各メソッドの名前は、 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 メソッドを呼び出すか、それぞれの Controls コレクションの Remove メソッドを呼び出します。 次のコード例では、Excel のドキュメント レベルのプロジェクトで Remove メソッドを使用して NamedRange を Sheet1 から削除します。

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

実行時にスタティック コントロールを削除することはできません。 Delete メソッドまたは Remove メソッドを使用してスタティック コントロールを削除しようとすると、CannotRemoveControlException がスローされます。

Note

ドキュメントの Shutdown イベント ハンドラーの中で、プログラムによってコントロールを削除しないでください。 Shutdown イベントが発生する時点では、ドキュメントの UI 要素は利用できなくなっています。 ドキュメントを閉じる前にコントロールを削除するには、Word では BeforeClose や BeforeSave 、Excel では BeforeCloseや BeforeSave など、別のイベントのイベント ハンドラーにコードを追加してください。

ドキュメントにホスト コントロールを追加する

ホスト コントロールをプログラムでドキュメントに追加するには、そのコントロールを一意に識別する名前を指定し、ドキュメント上にコントロールを追加する場所を指定する必要があります。 具体的な手順については、次のトピックを参照してください。

ホスト コントロールについて詳しくは、「ホスト項目とホスト コントロールの概要」をご覧ください。

ドキュメントを保存して閉じると、動的に作成したすべてのホスト コントロールはそれぞれイベントから切断され、データ バインディング機能も失われます。 ソリューションにコードを追加すれば、ドキュメントが再び開かれる時点でホスト コントロールを再作成するようにできます。 詳しくは、「Office ドキュメントでのダイナミック コントロールの永続化」をご覧ください。

Note

XmlMappedRange、 XMLNode、および XMLNodesの各ホスト コントロールは、プログラムでドキュメントに追加することができないため、ヘルパー メソッドは用意されていません。

Windows フォーム コントロールをドキュメントに追加する

Windows フォーム コントロールをプログラムでドキュメントに追加する場合は、コントロールの場所とコントロールを一意に識別する名前を指定する必要があります。 Visual Studio Tools for Office ランタイムでは、コントロールごとにヘルパー メソッドが提供されます。 これらのメソッドはオーバーロードされているため、コントロールの場所として範囲または特定の座標のいずれかを渡すことができます。

ドキュメントを保存して閉じると、動的に作成されたすべての Windows フォーム コントロールはドキュメントから削除されます。 ソリューションにコードを追加すれば、ドキュメントが再び開かれる時点でコントロールを再作成するようにできます。 VSTO アドインを使用して動的な Windows フォーム コントロールを作成した場合は、コントロールの ActiveX ラッパーがドキュメントに残されます。 詳しくは、「Office ドキュメントでのダイナミック コントロールの永続化」をご覧ください。

Note

Windows フォーム コントロールは、保護されているドキュメントにはプログラムで追加できません。 コントロールを追加するために、Word 文書または Excel ワークシートの保護をプログラムで解除する場合は、ドキュメントを閉じるときにコントロールの ActiveX ラッパーを削除するコードを追加で記述する必要があります。 コントロールの ActiveX ラッパーは、保護されたドキュメントから自動的には削除されません。

カスタム コントロールを追加する

カスタム ユーザー コントロールなど、使用可能なヘルパー メソッドによってサポートされていない Control を追加するには、次のメソッドを使用します。

  • Excel では、 AddControl オブジェクトの ControlCollection メソッドの 1 つを使用します。

  • Word では、 AddControl オブジェクトの ControlCollection メソッドの 1 つを使用します。

    コントロールを追加するには、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 メソッドの 1 つを使用してワークシートまたは文書にコントロールを追加すると、次の 2 つの異なるコントロール オブジェクトが存在するようになります。

  • カスタム コントロールを表す Control 。

  • ワークシートまたは文書に追加された後のコントロールを表す ControlSite、OLEObject、または OLEControl オブジェクト。

    これらのコントロールには、共有されているプロパティやメソッドが多数あります。 これらのメンバーには、適切なコントロールを介してアクセスすることが重要です。

  • カスタム コントロールのみに属するメンバーにアクセスするには、 Controlを使用します。

  • 複数のコントロールで共有されているメンバーにアクセスするには、ControlSite、OLEObject、または OLEControl オブジェクトを使用します。

    共有されているメンバーに Controlからアクセスすると、警告や通知なしに失敗したり、無効な結果が生成されたりすることがあります。 通常は ControlSite、OLEObject、または OLEControl オブジェクトのメソッドまたはプロパティを使用し、必要なメソッドやプロパティを使用できない場合に限って Control を参照してください。

    たとえば、Top プロパティは、ControlSite クラスと Control クラスの両方に存在します。 コントロールの上端からドキュメントの先頭までの間の距離を取得または設定するには、 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;

関連するコンテンツ