コンテンツ コントロール
コンテンツ コントロールは、次のような機能を備える文書やテンプレートをデザインするときに使用します。
フォームのように、入力を制御するユーザー インターフェイス (UI)。
文書やテンプレートの保護されたセクションをユーザーが編集できないように制限する。 詳細については、「コンテンツ コントロールを使用した文書保護」を参照してください。
データ ソースへのデータ バインディング。 詳細については、「コンテンツ コントロールへのデータのバインディング」を参照してください。
対象: このトピックの情報は、Word 2007 と Word 2010 のドキュメント レベルのプロジェクトおよびアプリケーション レベルのプロジェクトに適用されます。詳細については、「Office アプリケーションおよびプロジェクト タイプ別の使用可能な機能」を参照してください。
.gif "ビデオへのリンク")
関連のビデオ デモについては、「Binding Data to Word 2007 Content Controls Using Visual Studio Tools for the Office System (3.0) (Visual Studio Tools for the Office System (3.0) を使用した Word 2007 コンテンツ コントロールへのデータのバインド)」を参照してください。
コンテンツ コントロールの概要
コンテンツ コントロールは、ユーザー入力用および表示用に最適化された UI を提供します。 文書に追加したコンテンツ コントロールは、境界線、タイトル、およびユーザーへの説明を示す一時的なテキストで識別されます。 コントロールの境界線とタイトルは、文書を表示したときには示されません。
たとえば、ユーザーが文書のセクションに日付を入力するように設定する場合、文書に日付選択コントロールを追加します。 ユーザーがコントロールをクリックすると、日付選択の標準的な UI が表示されます。 地域で使用するカレンダーを表示して日付形式を指定するように、コントロールのプロパティを設定することもできます。 ユーザーが日付を選択すると、コントロールの UI は非表示となります。ユーザーが文書を表示すると、日付だけが示されます。
コンテンツ コントロールは、次のような処理を実行する場合にも役立ちます。
ユーザーが文書のある部分を編集または削除できないようにする。 これは、文書またはテンプレート内の情報についてユーザーが読むことができても編集はできないようにすることが必要な部分がわかっている場合や、ユーザーが編集できても削除はできないようにしたい場合などに役立ちます。
文書またはテンプレートの一部分を、データにバインドする。 コンテンツ コントロールは、データベース フィールド、.NET Framework 内のマネージ オブジェクト、文書に格納されている XML 要素、その他のデータ ソースにバインドできます。
ドキュメント レベルのプロジェクトでは、デザイン時または実行時に文書にコンテンツ コントロールを追加できます。 アプリケーション レベルのプロジェクトでは、実行時にコンテンツ コントロールを任意の開いているドキュメントに追加できます。 詳細については、「方法 : Word 文書にコンテンツ コントロールを追加する」を参照してください。
注意
コンテンツ コントロールは Open XML 形式で保存された文書でのみ使用できます。 Word 97 ～ Word 2003 文書 (.doc) 形式で保存された文書では、コンテンツ コントロールは使用できません。
コンテンツ コントロールの種類
文書に追加できるコンテンツ コントロールは 9 種類あります。 ほとんどのコンテンツ コントロールには、Microsoft.Office.Tools.Word 名前空間内に対応する型が存在します。 また、ジェネリック型である ContentControl を使用することもできます。この型は、使用できる任意のコンテンツ コントロールを表すことができます。 各コンテンツ コントロールの使用方法を説明するチュートリアルについては、「チュートリアル : コンテンツ コントロールによるテンプレートの作成」を参照してください。
ビルド ブロック ギャラリ
ビルド ブロック ギャラリを使用すると、ユーザーが文書のビルド ブロックの一覧から選択して、文書に挿入することができます。 文書のビルド ブロックは、複数回使用できるように作成されたコンテンツ部分です。たとえば、共通の表紙、書式設定された表、ヘッダーなどが挙げられます。 詳細については、BuildingBlockGalleryContentControl 型を参照してください。 ビルド ブロックの詳細については、「What's New for Developers in Word 2007」を参照してください。
チェック ボックス
チェック ボックスは、バイナリ (オンまたはオフ) の状態を表す UI です。 この種類のコンテンツ コントロールは、Word 2010 だけで使用できます。
他の種類のコンテンツ コントロールと異なり、Visual Studio Tools for Office Runtime にはチェック ボックス コンテンツ コントロールを表す特定の型が用意されていません。 つまり、CheckBoxContentControl 型は存在しません。 しかし、プログラム上でジェネリック型である ContentControl を文書に追加して、チェック ボックス コンテンツ コントロールを作成することはできます。 詳細については、「Word 2010 プロジェクトにおけるチェック ボックス コンテンツ コントロール」を参照してください。
コンボ ボックス
コンボ ボックスには、ユーザーが選択できるアイテムの一覧が表示されます。 ドロップダウン リストとは異なり、コンボ ボックスではユーザーが独自のアイテムを追加できます。 詳細については、ComboBoxContentControl 型を参照してください。
日付選択
日付選択は、日付を選択するためのカレンダーの UI を提供します。 カレンダーは、エンド ユーザーがコントロール内のドロップダウン矢印をクリックすると表示されます。 地域で使用するカレンダーや、いくつかの異なる日付形式を使用できます。 詳細については、DatePickerContentControl 型を参照してください。
ドロップダウン リスト
ドロップダウン リストには、ユーザーが選択できるアイテムの一覧が表示されます。 コンボ リストとは異なり、ドロップダウン ボックスではユーザーがアイテムの追加や削除を行うことはできません。 詳細については、DropDownListContentControl 型を参照してください。
グループ
グループ コントロールは、文書の保護された領域 (ユーザーが編集や削除を行うことができない領域) を定義するものです。 グループ コントロールには、任意のドキュメント アイテム (テキスト、表、グラフィックスなどのコンテンツ コントロール) を含めることができます。 詳細については、GroupContentControl 型を参照してください。
画像
画像コントロールは、イメージを表示します。 イメージは、デザイン時または実行時に指定できます。また、このコントロールをクリックしてイメージを選択し、文書に挿入することも可能です。 詳細については、PictureContentControl 型を参照してください。
リッチ テキスト
リッチ テキスト コントロールには、テキストだけでなく、その他のアイテム (表や画像などのコンテンツ コントロール) を含めることができます。 詳細については、RichTextContentControl 型を参照してください。
[プレーンテキスト]
プレーンテキスト コントロールには、テキストが格納されます。 プレーンテキスト コントロールに、その他のアイテム (表や画像などのコンテンツ コントロール) を含めることはできません。 また、プレーンテキスト コントロール内のテキストには同じ書式が設定されます。 たとえば、プレーンテキスト コントロール内の 1 つの単語に斜体を適用すると、そのコントロールに含まれるすべてのテキストに斜体が適用されます。 詳細については、PlainTextContentControl 型のトピックを参照してください。
汎用コンテンツ コントロール
汎用コンテンツ コントロールは、使用できる任意の種類のコンテンツ コントロールを表すことができる ContentControl オブジェクトです。 Type プロパティを使用して ContentControl オブジェクトを変更し、別の種類のコンテンツ コントロールであるかのように動作させることができます。 たとえば、プレーンテキスト コントロールを表す ContentControl オブジェクトを作成し、実行時にコンボ ボックスのように動作するよう変更できます。
ContentControl オブジェクトを作成できるのは、実行時だけです。デザイン時には作成できません。 詳細については、「方法 : Word 文書にコンテンツ コントロールを追加する」を参照してください。
コンテンツ コントロールの共通機能
大部分のコンテンツ コントロールは、一般的なタスクの実行に使用できるメンバー セットを共有します。 これらのメンバーを使用して実行できる一部のタスクについて、次の表で説明します。
タスク : |
方法 : |
|---|---|
コントロールに表示されるテキストを取得または設定します。 |
Text プロパティを使用します。 .gif "メモ") メモ
PictureContentControl 型と ContentControl 型には、このプロパティはありません。
|
ユーザーによるコントロールの編集、データ ソースからコントロールへのデータの設定、コントロール コンテンツの削除のいずれかが行われるまで、コントロールに表示される一時的なテキストを取得または設定します。 |
PlaceholderText プロパティを使用します。 メモ
PictureContentControl 型には、このプロパティはありません。
|
ユーザーがクリックしたときにコンテンツ コントロールの境界線に表示されるタイトルを取得または設定します。 |
Title プロパティを使用します。 |
ユーザーがコントロールを編集したときに、文書からコントロールを自動的に削除します (コントロール内のテキストは、文書内に残ります)。 |
Temporary プロパティを使用します。 |
ユーザーがコンテンツ コントロールをクリックしたとき、またはプログラムによってカーソルがコンテンツ コントロール内に移動したときに、コードを実行します。 |
コントロールの Entering イベントを処理します。 |
ユーザーがコンテンツ コントロールの外部をクリックしたとき、またはプログラムによってカーソルがコンテンツ コントロールの外部に移動したときにコードを実行します。 |
コントロールの Exiting イベントを処理します。 |
元に戻す操作またはやり直し操作の結果としてコンテンツ コントロールが文書に追加された後に、コードを実行します。 |
コントロールの Added イベントを処理します。 |
コンテンツ コントロールが文書から削除される直前にコードを実行します。 |
コントロールの Deleting イベントを処理します。 |
コンテンツ コントロールを使用した文書保護
文書の一部を保護すると、ユーザーは保護した部分の内容を変更および削除できなくなります。 コンテンツ コントロールを使用して文書の一部を保護するには、いくつかの方法があります。
保護対象とする領域がコンテンツ コントロールの内部にある場合は、コンテンツ コントロールのプロパティを使用して、ユーザーがコントロールの編集や削除を行うことができないようにします。
ユーザーがコンテンツを編集できないようにするには、LockContents プロパティを使用します。
ユーザーがコントロールを削除できないようにするには、LockContentControl プロパティを使用します。
保護対象とする領域がコンテンツ コントロールの内部にない場合、またはコンテンツ コントロールだけでなくその他の種類のコンテンツを含む領域を保護する場合は、領域全体を GroupContentControl に配置します。 他のコンテンツ コントロールとは異なり、GroupContentControl には、ユーザーに対して表示される UI はありません。 ユーザーが編集できない領域を定義することだけに使用します。
注意
コンテンツ コントロールが埋め込まれた GroupContentControl を作成した場合、埋め込まれたコンテンツ コントロールは自動的には保護されません。 コンテンツをユーザーが編集できないようにするには、埋め込まれた各コントロールの LockContents プロパティを使用する必要があります。
コンテンツ コントロールを使用して文書の一部を保護する方法の詳細については、「方法 : コンテンツ コントロールを使用して文書を保護する」を参照してください。
コンテンツ コントロールへのデータのバインディング
コンテンツ コントロールをデータ ソースにバインドすると、文書内にデータを表示できます。 データ ソースが更新されると、コンテンツ コントロールに変更内容が反映されます。 変更内容をデータ ソースに反映して保存することもできます。
コンテンツ コントロールには、次のようなデータ バインディング オプションがあります。
Windows フォームと同じデータ バインディング モデルを使用して、データベース フィールドやマネージ オブジェクトにコンテンツ コントロールをバインドできます。
コンテンツ コントロールを、文書に埋め込まれている XML 内の要素 (カスタム XML 部分とも呼ばれます) にバインドできます。
Office ソリューション内のホスト コントロールをデータにバインドすることの概要については、「Office ソリューションでのコントロールへのデータのバインド」を参照してください。
Windows フォーム データ バインディング モデルの使用
大部分のコンテンツ コントロールは、Windows フォームが使用する単純なデータ バインディング モデルをサポートします。 単純なデータ バインディングとは、コントロールが単一のデータ要素 (データ テーブルの列など) にバインドされることを意味します。 詳細については、「データ連結と Windows フォーム」を参照してください。
ドキュメント レベルのプロジェクトでは、Visual Studio の [データ ソース] ウィンドウを使ってコンテンツ コントロールにデータをバインドすることもできます。 データ バインドされているコンテンツ コントロールを文書に追加する方法の詳細については、「方法 : データベースからドキュメントにデータを読み込む」および「方法 : オブジェクトのデータをドキュメントに読み込む」を参照してください。
[データ ソース] ウィンドウを使用して各データ型にバインドできるコンテンツ コントロールの一覧を、次の表に示します。
データ型 |
既定のコンテンツ コントロール |
このデータ型にバインドできるその他のコンテンツ コントロール |
|---|---|---|
|
Byte 配列 |
なし |
ドキュメント レベルのプロジェクトとアプリケーション レベルのプロジェクトでは、コントロールの DataBindings プロパティの Add() メソッドを使用して、プログラムによってデータ ソースにコンテンツ コントロールをバインドすることもできます。 この方法を使用する場合は、Add() メソッドの propertyName パラメーターに文字列 Text を渡します。 Text プロパティは、コンテンツ コントロールの既定のデータ バインディング プロパティです。
コンテンツ コントロールは双方向のデータ バインディングもサポートするため、コントロール内での変更がデータ ソースにも反映されます。 詳細については、「方法 : ホスト コントロールからのデータでデータ ソースを更新する」を参照してください。
注意
コンテンツ コントロールでは、複合データ バインディングはサポートしません。 Windows フォーム データ モデルを使用してデータ ソースに対して DropDownListContentControl または ComboBoxContentControl をバインドすると、ユーザーには、コントロールをクリックしたときに 1 つの値だけが表示されます。 これらのコントロールを一連のデータ値にバインドし、ユーザーがその値の中から選択できるようにするには、カスタム XML 部分の要素に対してコントロールをバインドします。
カスタム XML 部分へのコンテンツ コントロールのバインド
一部のコンテンツ コントロールは、文書に埋め込まれているカスタム XML 部分の要素にバインドできます。 カスタム XML 部分の詳細については、「カスタム XML 部分の概要」を参照してください。
コンテンツ コントロールをカスタム XML 部分の要素にバインドするには、コントロールの XMLMapping プロパティを使用します。 文書に追加されているカスタム XML 部分の Product ノード下にある Price 要素に対して、PlainTextContentControl をバインドする方法を次のコード例に示します。
plainTextContentControl1.XMLMapping.SetMapping("/Product/Price")
plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);
カスタム XML 部分にコンテンツ コントロールをバインドする方法について、より詳しく説明するチュートリアルを参照するには、「チュートリアル : カスタム XML 部分へのコンテンツ コントロールのバインド」をご覧ください。
カスタム XML 部分にコンテンツ コントロールをバインドすると、双方向のデータ バインディングが自動的に有効になります。 コントロール内のテキストをユーザーが編集すると、対応する XML 要素が自動的に更新されます。 同様に、カスタム XML 部分の要素の値が変更されると、その XML 要素にバインドされているコンテンツ コントロールには新しいデータが表示されます。
カスタム XML 部分にバインドできるコンテンツ コントロールの種類の一覧を、次に示します。
コンテンツ コントロールのデータ バインディング イベント
すべてのコンテンツ コントロールでは一連のイベントが提供されます。イベントは、データ関連のタスクを実行するために処理できるもので、データ ソースを更新する前にコントロール内のテキストが特定の条件を満たしていることを検証することなどが例として挙げられます。 データ バインディングに関連するコンテンツ コントロール イベントの一覧を、次の表に示します。
タスク |
イベント |
|---|---|
カスタム XML 部分にバインドされているコンテンツ コントロール内のテキストが Word で自動的に更新される直前に、コードを実行します。 |
|
コンテンツ コントロールにバインドされているカスタム XML 部分内のデータが Word で自動的に更新される直前 (コンテンツ コントロール内のテキストが変更された後) に、コードを実行します。 |
|
独自のコードを実行し、独自の条件に基づいてコントロールの内容を検証します。 |
|
コントロールの内容の検証が正常に完了した後に、コードを実行します。 |
コンテンツ コントロールの制限事項
Office プロジェクトでコンテンツ コントロールを使用する場合には、次の制限事項に留意してください。
デザイン時と実行時の動作の相違
実行時のコンテンツ コントロールに対する Microsoft Office Word の制約の多くがデザイン時には適用されません。 Visual Studio でドキュメント レベルのソリューションの UI を設計する場合は、それが実行時にサポートされるかどうかを踏まえて、コンテンツ コントロールを編集する必要があります。
コンテンツ コントロールに対して、実行時にはサポートされないなんらかの変更をデザイン時に加えたとしても、Visual Studio のデザイナーでは、サポートされない変更であることを告げる警告は表示されません。 ただし、プロジェクトのデバッグ時や実行時、または、プロジェクトを保存した後で開き直した場合、Word のエラー メッセージが表示され、文書を修復してよいかどうかをたずねられます。 文書を修復した場合、サポートされていないすべてのコンテンツおよび書式設定がコントロールから削除されます。
たとえば、デザイン時に、Word で PlainTextContentControl に対して表を追加することができます。 しかし、実行時には PlainTextContentControl オブジェクトに表が含まれていないため、この文書を開くと Word のエラー メッセージが表示されます。
コンテンツ コントロールの動作を定義する多くのプロパティは、デザイン時には効果がないことにも留意してください。 たとえば、デザイン時にコンテンツ コントロールの LockContents プロパティを True に設定しても、Visual Studio デザイナーでこのコントロールのテキストを編集することができます。 このプロパティによってユーザーがコントロールを編集できなくなるのは、実行時だけです。
イベントの制限事項
コンテンツ コントロールでは、ユーザーがコントロール内のテキストや他のアイテムを変更したときに発生するイベントは提供されません。 たとえば、ユーザーが DropDownListContentControl や ComboBoxContentControl で異なるアイテムを選択したときに発生するイベントはありません。
コンテンツ コントロールの内容についてユーザーが編集した時点を判断するには、カスタム XML 部分にコントロールをバインドし、StoreUpdating イベントを処理します。 このイベントは、カスタム XML 部分にバインドされているコントロールの内容をユーザーが変更したときに発生します。 カスタム XML 部分にコンテンツ コントロールをバインドする方法を説明するチュートリアルについては、「チュートリアル : カスタム XML 部分へのコンテンツ コントロールのバインド」を参照してください。
Word 2010 プロジェクトにおけるチェック ボックス コンテンツ コントロール
Word 2010 には、チェック ボックスを表す新しい種類のコンテンツ コントロールが導入されました。 ただし、Visual Studio Tools for Office Runtime には、Office プロジェクトで使用できる対応する CheckBoxContentControl 型は用意されていません。 Word 2010 プロジェクトでチェック ボックス コンテンツ コントロールを作成するには、AddContentControl メソッドを使用して Microsoft.Office.Tools.Word.ContentControl オブジェクトを作成します。このとき、wdContentControlCheckBox 値をメソッドに渡してチェック ボックス コンテンツ コントロールを指定します。 これを実行する方法を次のコード例に示します。
Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)
' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True
' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True
this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 =
this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);
// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;
// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;
注意
Microsoft.Office.Tools.Word.ContentControl オブジェクトの Checked プロパティは、.NET Framework 4 を対象とするプロジェクトでのみ直接使用できます。 .NET Framework 3.5 を対象とするプロジェクトでは、InnerObject プロパティを使用して、基になる Microsoft.Office.Interop.Word.ContentControl オブジェクトの Checked プロパティにアクセスする必要があります。 詳細については、「ホスト項目およびホスト コントロールのプログラム上の制限事項」を参照してください。
参照
処理手順
方法 : Word 文書にコンテンツ コントロールを追加する
チュートリアル : コンテンツ コントロールによるテンプレートの作成
概念
Office ソリューションでのコントロールへのデータのバインド
ホスト項目およびホスト コントロールのプログラム上の制限事項