UI オートメーション 埋め込みオブジェクトが公開される方法

このトピックでは、Microsoft UI オートメーションで Text コントロール パターンと TextRange コントロール パターンを使用して、テキスト ドキュメントまたはコンテナー内の埋め込みオブジェクト (子/子孫要素) を公開する方法について説明します。

UI オートメーションの場合、埋め込みオブジェクトとは、画像、ハイパーリンク、テーブル、ドキュメントの種類 (例: Microsoft Excel スプレッドシート、Microsoft Windows Media ファイル) など、テキスト以外の境界を持つあらゆる要素を指します。

埋め込みオブジェクトと UI オートメーション ツリー

埋め込みオブジェクトは、UI オートメーション ツリーのコントロール ビュー内では個々の要素として扱われます。 これらはテキスト コンテナーの子として公開され、UI オートメーションの他のコントロールと同じオブジェクト モデルを介してアクセスできます。

次の表に、コンテナー要素とコンテナー以外の要素の例を示します。

次の画像は、埋め込みテーブルと画像を含むテキスト コンテナー (ドキュメント) を示しています。

前のドキュメントの UI オートメーション コンテンツ ビューを次の図に示します。

"互換性のある" 埋め込みオブジェクトと "互換性のない" 埋め込みオブジェクト

一部の UI オートメーション プロバイダーは、含まれている各 TextPattern オブジェクトに同じテキスト ストアを使用します。 コンテナーと同じテキスト ストアでサポートされるオブジェクトは、"互換性のある" 埋め込みオブジェクトと呼ばれます。 これらのオブジェクトには TextPattern オブジェクト自体を指定できます。この場合、それらのテキスト範囲は、コンテナーから取得したテキスト範囲に相当します。 これにより、プロバイダーは、個々の TextPattern オブジェクトに関するクライアント情報を、あたかも 1 つの大きなテキスト プロバイダーであるかのように公開できるようになります。

ただし、プロバイダーは、TextPattern コンテナー内に埋め込まれているさまざまな TextPattern オブジェクトに対して異なるテキスト ストアを使用できます。 コンテナーのテキスト ストアでサポートされていないオブジェクトは、"互換性のない" 埋め込みオブジェクトと呼ばれます。 これらの種類の埋め込みオブジェクトは、TextPattern ベースのオブジェクトである場合とそうでない場合があります。

次の表に、互換性のある埋め込みオブジェクトと互換性のない埋め込みオブジェクトの例をいくつか示します。

埋め込みオブジェクトの公開

Text および TextRange のコントロール パターンを使用すると、埋め込みオブジェクトのナビゲーションとクエリの実行を支援するプロパティとメソッドが公開されます。

テキスト コンテナーのテキスト コンテンツ (内部テキスト) と埋め込みオブジェクト (ハイパーリンクやテーブルのセルなど) は、連続する単一のテキスト ストリームとして、UI オートメーション ツリーのコントロール ビューとコンテンツ ビューの両方で公開されます。そのため、オブジェクトの境界は無視されます。 UI オートメーション クライアントがなんらかの方法で再現、解釈、または分析するテキストを取得している場合は、テキスト コンテンツやその他の埋め込みオブジェクトを持つテーブルなど特殊なケースについて、テキスト範囲をチェックする必要があります。 IUIAutomationTextRange::GetChildren を呼び出して埋め込みオブジェクトごとに IUIAutomationElement インターフェイスを取得してから、IUIAutomationTextPattern::RangeFromChild を呼び出し、各要素のテキスト範囲を取得します。 この操作は、すべてのテキスト コンテンツが取得されるまで再帰的に行われます。

次の図は、埋め込みオブジェクトとその範囲を含むテキスト ストリームを示しています。

埋め込みオブジェクトと TextUnit

ITextProvider オブジェクトは、指定した TextUnit によって走査できます。 埋め込みオブジェクトを含んだプロバイダーの走査は、ほぼ同じ方法でできますが、埋め込みオブジェクトは走査に影響します。 注意すべきポイントをいくつか次に示します。

• 互換性のない埋め込みオブジェクトは、コンテナー要素の TextPattern のテキスト ストア内にある置換文字 U+FFFC によって表されます。 また、文字単位と単語単位の両方とみなされます。
• 互換性のある埋め込みオブジェクトは、複数の文字と単語で構成される場合があります。
• 囲み要素は、テキスト範囲全体にまたがる最下位レベルにある要素です。
• 範囲の子要素は、範囲内で部分的または完全に囲まれたコンテナー要素の子要素でもあります。
• 理想的には (特に Table のようなコンテナー要素の場合)、単語の境界はオブジェクトの境界を超えません。 次の例では、単語単位 "Bar" には、</td> タグの外側にあるテキスト位置が含まれていません (<br \> は単語 "Bar" の一部ではありません)。

<table style="width:100%">
  <tr>
    <th>Name</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>Eve Jackson</td>
    <td>Foo Bar</td>
  </tr>
</table>
<br/>

• 一般に、<br \> は行の境界を超えないように、個々の単語として扱われます。
• 前の規則の例外は、Word テキスト単位自体に完全なオブジェクトが含まれている場合です。 たとえば、インライン コンテナーを含む <p>Hello <a href="#">link</a> here.</p>には、"Hello"、"link"、"here" という単語があります。ここで、"link" は TextPattern オブジェクトを囲み要素として、リンク オブジェクトを子として持ちます。
• 文字単位の場合、オブジェクトは囲み要素です (このようなテキスト単位には子を含めてはなりません)。
• 注釈オブジェクトを埋め込みオブジェクトとして表さないでください。 たとえば、共同執筆されたドキュメントに他の Author 指定子が存在する場合です。
• 埋め込みオブジェクトは少なくとも 1 つのカーソル位置を占め、注釈はメタデータにすぎません。
• 各オブジェクト境界 (開始と終了) は、TextPattern ドキュメント範囲の書式区切りで表されます。
• HTML の場合、各 html タグは必ずしも UI オートメーション オブジェクトを生成するとは限りません。 たとえば、 強調タグ内のコンテンツは要素として表す必要はありませんが、UIA_IsItalicAttributeId が TRUE を返すテキスト ストリームとして表す必要があります。
• 開始エンドポイントは包括的であり、優先エンドポイントですが、終了エンドポイントは排他的です。 これは、範囲が低次元テキスト範囲であり、開始エンドポイントと終了エンドポイントがその範囲の同じ位置に属している場合に便利です。

埋め込みオブジェクトの比較

同じような子リレーションシップにあり、同じバッキング テキスト ストアを共有する入れ子になった TextPattern オブジェクトは、同等と呼ばれます。 この場合、どちらの TextPattern オブジェクトからの範囲も、 ITextRangeProvider::Compare と ITextRangeProvider::CompareEndpoints を使用して比較できます。 両方とも、相対位置を指定する有効な数値になります。

TextPattern オブジェクトに埋め込まれている TextPattern 以外のオブジェクトは、オブジェクトが TextPattern (ITextProvider::RangeFromChild) の有効な範囲を持ち、テキスト範囲の背後にあるコンテンツが空ではなく、置換文字でもない場合、TextPattern と同等です。

埋め込み TextPattern オブジェクトと Document TextUnit

埋め込み TextPattern オブジェクトの場合、Document ユニットは、その要素に含まれるコンテンツのみを認識します。

Word TextPattern 要素の階層

• ドキュメント要素は TextPattern を実装し、Document は Word 文書の範囲全体を返します。
• ドキュメントの個々のページには TextPattern が実装され、Document は、(ページがドキュメント TexPattern 全体で同じテキスト ストアを共有している場合でも) それらの個々のページのコンテンツを返します。

Edge 内の Web ページとテキスト入力コントロール

• メインの Web ページ ウィンドウ要素は TextPattern を実装し、Web ページのコンテンツ全体を公開します。
• 個々のテキスト入力コントロールでは、TextPattern がサポートされます。ドキュメント範囲は、(同じテキスト ストアを Web ページ全体と共有している場合でも) 各入力フィールドに含まれるテキストを表します。

一般的なシナリオ

このセクションでは、埋め込みオブジェクト (ハイパーリンク、画像、およびテーブル) を含む一般的なシナリオの例を示します。 次の例では、左中かっこ ({) はテキスト範囲の開始エンドポイントを表し、右中かっこ (}) は終了エンドポイントを表します。

ハイパーリンク例 1: 埋め込みテキスト ハイパーリンクを含むテキスト範囲

次のテキスト範囲には、埋め込みテキスト ハイパーリンクが含まれています。

{URL https://www.microsoft.com はテキストに埋め込まれています}。

IUIAutomationTextRange::GetText、GetEnclosingElement、GetChildren、および IUIAutomationTextPattern::RangeFromChild のメソッドを呼び出すと、次の表で説明する動作になります。

ハイパーリンク例 2: 埋め込みテキスト ハイパーリンクに部分的にかかるテキスト範囲

次のテキスト範囲は、埋め込みテキスト ハイパーリンクに部分的にまたがっています。

URL https://{www} はテキストに埋め込まれています。

IUIAutomationTextRange::GetText、GetEnclosingElement、および GetChildren のメソッドを呼び出すと、次の表で説明する動作になります。

ハイパーリンク例 3: テキスト コンテナーのコンテンツに部分的にかかるテキスト範囲

次のテキスト範囲は、テキスト コンテナーのコンテンツに部分的にまたがっています。 テキスト コンテナーには、テキスト範囲に含まれない埋め込みテキスト ハイパーリンクが含まれます。

{URL} https://www.microsoft.com はテキストに埋め込まれています。

IUIAutomationTextRange::GetText、GetEnclosingElement、および Move のメソッドを呼び出すと、次の表で説明する動作になります。

画像例 1: 埋め込みイメージを含むテキスト範囲

次のテキスト範囲には、スペース シャトルの埋め込み画像が含まれています。

{画像 がテキストに埋め込まれます}。

IUIAutomationTextRange::GetText、GetEnclosingElement、GetChildren、および IUIAutomationTextPattern::RangeFromChild のメソッドを呼び出すと、次の表で説明する動作になります。

画像例 2: テキスト コンテナーのコンテンツに部分的にかかるテキスト範囲

次のテキスト範囲は、テキスト コンテナーのコンテンツに部分的にまたがっています。 テキスト コンテナーには、テキスト範囲に含まれない埋め込みイメージが含まれます。

{画像} がテキストに埋め込まれます。

IUIAutomationTextRange::GetText、GetEnclosingElement、および Move のメソッドを呼び出すと、次の表で説明する動作になります。

テーブル

テーブル例 1: セルのコンテンツからテキスト コンテナーを取得する

次のテーブルは、セルの内容からテキスト コンテナーを取得します。

イメージを含むセル	テキストを含むセル
	x
	年
	Z

IUIAutomationGridPattern::GetItem、IUIAutomationTextPattern::RangeFromChild、および IUIAutomationTextRange::GetEnclosingElement のメソッドを呼び出すと、次の表で説明する動作になります。

呼び出されるメソッド	結果
パラメーター (0,0) を持つ IUIAutomationGridPattern::GetItem。	テーブル セルのコンテンツを表す UI オートメーション要素を返します。この場合、要素はテキスト コントロールです。
iuiautomationtextpattern::rangefromchild	画像 の範囲を返します。
前の IUIAutomationTextPattern::RangeFromChild メソッドによって返されたオブジェクトの GetEnclosingElement。	テーブル セルを表す UI オートメーション要素を返します。 この場合、要素は、TableItem コントロール パターンをサポートするテキスト コントロールです。
前の GetEnclosingElement メソッドによって返されたオブジェクトの IUIAutomationTextRange::GetEnclosingElementt。	テーブルを表す UI オートメーション要素を返します。
前の GetEnclosingElement メソッドによって返されたオブジェクトの IUIAutomationTextRange::GetEnclosingElementt。	テキスト プロバイダー自体を表す UI オートメーション要素を返します。

テーブル例 2: セルのテキスト コンテンツを取得する

前の例のテーブルは、セルのテキスト コンテンツを取得します。

IUIAutomationGridPattern::GetItem および IUIAutomationTextPattern::RangeFromChild のメソッドを呼び出すと、次の表で説明する動作になります。

TextUnit_Line で文書内を移動する場合、テキスト範囲が埋め込みテーブルに達したら、セル内のテキストの各行を 1 行として扱う必要があります。

関連トピック

Conceptual

• Text および TextRange のコントロール パターンについて
• UI オートメーションのテキスト属性
• UI オートメーション コントロール パターンの概要
• Textual Content 用 UI Automation Support