ホスト項目とホストコントロールのプログラム上の制限事項Programmatic limitations of host items and host controls

それぞれのホスト項目やホスト コントロールは、それに対応するネイティブな Microsoft Office Word オブジェクトや Microsoft Office Excel オブジェクトと同様に動作するように設計され、さらに追加の機能が備えられています。Each host item and host control is designed to behave like a corresponding native Microsoft Office Word or Microsoft Office Excel object, with additional functionality. ただし、ホスト項目やホスト コントロールと、ネイティブな Office オブジェクトの実行時の動作には、基本的な相違点がいくつかあります。However, there are some fundamental differences between the behavior of host items and host controls and native Office objects at run time.

ホスト項目とホストコントロールに関する一般的な情報については、「ホスト項目とホストコントロールの概要」を参照してください。For general information about host items and host controls, see Host items and host controls overview.

適用対象: このトピックの情報は、ドキュメントに適用されます-レベルのプロジェクトおよび 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.

プログラムによるホスト項目の作成Programmatically create host items

Word または Excel オブジェクト モデルを使用することで、文書、ブック、またはワークシートをプログラムで実行時に作成したり、開いたりする場合、その項目はホスト項目ではありません。When you programmatically create or open a document, workbook, or worksheet at run time by using the Word or Excel object model, the item is not a host item. その新しいオブジェクトは、ネイティブな Office オブジェクトです。Instead, the new object is a native Office object. たとえば、 Add メソッドを使用して実行時に新しい Word 文書を作成すると、その文書は、 Document ホスト項目ではなく、ネイティブな Document オブジェクトになります。For example, if you use the Add method to create a new Word document at run time, it will be a native Document object rather than a Document host item. 同様に、 Add メソッドを使用して実行時に新しいワークシートを作成すると、 Worksheet ホスト項目ではなく、ネイティブな Worksheet オブジェクトが作成されます。Similarly, when you create a new worksheet at run time using the Add method, you get a native Worksheet object rather than a Worksheet host item.

ドキュメント レベルのプロジェクトでは、実行時にホスト項目を作成することはできません。In document-level projects, you cannot create host items at run time. ドキュメント レベルのプロジェクトでは、デザイン時にのみ、ホスト項目を作成できますHost items can be created only at design time in document-level projects. 詳細については、「 Document host item」、「 Workbook host item」、および「 Worksheet host item」を参照してください。For more information, see Document host item, Workbook host item, and Worksheet host item.

VSTO アドイン プロジェクトでは、実行時に DocumentWorkbook、または Worksheet のホスト項目を作成できます。In VSTO Add-in projects, you can create Document, Workbook, or Worksheet host items at run time. 詳細については、「 VSTO アドインでの実行時の Word 文書と Excel ブックの拡張」を参照してください。For more information, see Extend Word documents and Excel workbooks in VSTO Add-ins at run time.

プログラムによるホストコントロールの作成Programmatically create host controls

実行時に、プログラムによって、 Document ホスト項目または Worksheet ホスト項目にホスト コントロールを追加できます。You can programmatically add host controls to a Document or Worksheet host item at run time. 詳細については、「実行時に Office ドキュメントにコントロールを追加する」を参照してください。For more information, see Add controls to Office documents at run time.

ネイティブな DocumentWorksheetに、ホスト コントロールを追加することはできません。You cannot add host controls to a native Document or Worksheet.

Note

ホスト コントロールの XmlMappedRangeXMLNode、および XMLNodesは、プログラムによってワークシートや文書に追加することはできません。The following host controls cannot be added programmatically to worksheets or documents: XmlMappedRange, XMLNode, and XMLNodes.

ホスト項目、ホストコントロール、およびネイティブ Office オブジェクトの型の違いを理解するUnderstand type differences between host items, host controls, and native Office objects

それぞれのホスト項目やホスト コントロールには、基になるネイティブな Microsoft Office Word オブジェクトまたは Microsoft Office Excel オブジェクトがあります。For each host item and host control, there is an underlying native Microsoft Office Word or Microsoft Office Excel object. ホスト項目またはホストコントロールの InnerObject プロパティを使用して、基になるオブジェクトにアクセスできます。You can access the underlying object by using the InnerObject property of the host item or host control. ただし、ネイティブな Office オブジェクトをそれに対応するホスト項目またはホスト コントロールにキャストする方法はありません。However, there is no way to cast a native Office object to its corresponding host item or host control. ネイティブな Office オブジェクトをホスト項目またはホスト コントロールの型にキャストしようとすると、 InvalidCastException がスローされます。If you try to cast a native Office object into the type of a host item or host control, an InvalidCastException is thrown.

ホスト項目とホスト コントロールの型、および基になるネイティブな Office オブジェクトの違いがコードに影響を及ぼす可能性について、いくつかのシナリオを挙げて説明します。There are several scenarios where the differences between the types of host items and host controls and the underlying native Office objects can affect your code.

メソッドおよびプロパティへのホストコントロールの引き渡しPass host controls to methods and properties

Word では、パラメーターとしてネイティブな Word オブジェクトを要求するメソッドまたはプロパティに、ホスト コントロールを渡すことはできません。In Word, you cannot pass a host control to a method or property that requires a native Word object as a parameter. ホストコントロールの InnerObject プロパティを使用して、基になるネイティブ Word オブジェクトを返す必要があります。You must use the InnerObject property of the host control to return the underlying native Word object. たとえば、メソッドに Bookmark オブジェクトを渡す場合は、 InnerObject ホスト コントロールの Bookmark プロパティを渡します。For example, you can pass a Bookmark object to a method by passing the InnerObject property of the Bookmark host control to the method.

Excel では、メソッドまたはプロパティが基になる Excel オブジェクトを必要とする場合に、ホストコントロールの InnerObject プロパティを使用して、ホストコントロールをメソッドまたはプロパティに渡す必要があります。In Excel, you must use the InnerObject property of the host control to pass the host control to a method or property when the method or property expects the underlying Excel object.

次に示す例では、 NamedRange コントロールを作成して、そのコントロールを AutoFill メソッドに渡しています。The following example creates a NamedRange control and passes it to the AutoFill method. このコードでは、名前付き範囲の InnerObject プロパティを使用して、 Range メソッドが要求する、基になる Office の AutoFill を返します。The code uses the InnerObject property of the named range to return the underlying Office Range that is required by the AutoFill method.

this.Range["A1"].Value2 = "Monday";
this.Range["A2"].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange = 
    this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");
this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);
Me.Range("A1").Value2 = "Monday"
Me.Range("A2").Value2 = "Tuesday"

Dim dayRange As Microsoft.Office.Tools.Excel.NamedRange = _
    Me.Controls.AddNamedRange(Me.Range("A1", "A7"), "dayRange")
Me.Range("A1", "A2").AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays)

ネイティブの Office メソッドとプロパティの戻り値の型Return types of native Office methods and properties

ホスト項目のほとんどのメソッドとプロパティは、そのホスト項目の基になっているネイティブな Office オブジェクトを返します。Most methods and properties of host items return the underlying native Office object upon which the host item is based. たとえば、Excel の Parent ホスト コントロールの NamedRange プロパティは、 Worksheet ホスト項目ではなく Worksheet オブジェクトを返します。For example, the Parent property of a NamedRange host control in Excel returns a Worksheet object rather than a Worksheet host item. 同様に、Word の Parent ホスト コントロールの RichTextContentControl プロパティは、 Document ホスト項目ではなく Document オブジェクトを返します。Similarly, the Parent property of a RichTextContentControl host control in Word returns a Document object rather than a Document host item.

ホストコントロールのコレクションへのアクセスAccess collections of host controls

Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime には、ホスト コントロールの種類ごとの個別のコレクションは用意されていません。The Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime does not provide individual collections for each type of host control. 代わりに、ホスト項目の Controls プロパティを使用して、ドキュメントまたはワークシートのすべてのマネージコントロール (ホストコントロールと Windows フォームコントロールの両方) を反復処理し、目的のホストコントロールの型に一致する項目を検索します。Instead, use the Controls property of a host item to iterate through all managed controls (both host controls and Windows Forms controls) on the document or worksheet, and then look for items that match the type of the host control you are interested in. 次に示すコード例では、Word 文書の各コントロールを調べ、そのコントロールが Bookmarkかどうかを確認しています。The following code example examines each control on a Word document and determines whether the control is a Bookmark.

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark =
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the bookmark here.
    }
}
Dim targetControl As Object
For Each targetControl In Me.Controls

    If TypeOf (targetControl) Is Microsoft.Office.Tools.Word.Bookmark Then
        Dim bookMark As Microsoft.Office.Tools.Word.Bookmark = _
            CType(targetControl, Microsoft.Office.Tools.Word.Bookmark)

        ' Do some work with the book mark here.
    End If
Next

ホスト項目の Controls プロパティの詳細については、「実行時に Office ドキュメントにコントロールを追加する」を参照してください。For more information about the Controls property of host items, see Add controls to Office documents at run time.

Word と Excel オブジェクト モデルには、文書とワークシートのネイティブ コントロールのコレクションを公開するプロパティが含まれています。The Word and Excel object models include properties that expose collections of native controls on documents and worksheets. これらのプロパティを使用してマネージド コントロールにアクセスすることはできません。You cannot access managed controls by using these properties. たとえば、 BookmarkBookmarks プロパティや DocumentBookmarks プロパティを使用して、文書内の各 Documentホスト コントロールを列挙することはできません。For example, it is not possible to enumerate each Bookmark host control in a document by using the Bookmarks property of a Document or the Bookmarks property of a Document. これらのプロパティには、文書内の Bookmark コントロールのみが含まれています。つまり、文書内の Bookmark ホスト コントロールは含まれていないということです。These properties include only the Bookmark controls in the document; they do not contain the Bookmark host controls in the document.

関連項目See also