次の方法で共有

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

  • [アーティクル]

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

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

Note

これは、コンポーネント オブジェクト モデル (COM) OLE 定義 (「埋め込みオブジェクト」を参照) とは異なります。その定義では、要素の作成はあるアプリケーションで行われ、要素の埋め込みとリンクは別のアプリケーションで行われます。 オブジェクトを元のアプリケーション内で編集できるかどうかは、UI オートメーションの状況とは無関係です。

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

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

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

コンテナー要素

コンテナー以外の要素

  • Calendar
  • コンボ ボックス
  • DataGrid
  • Document
  • 編集
  • グループ
  • ヘッダー
  • HeaderItem
  • 一覧取得
  • メニュー
  • MenuBar
  • ペイン
  • SplitButton
  • Tab
  • テーブル
  • ツール バー
  • ツリー
  • TreeItem
  • ウィンドウ
  • リンク
  • CheckBoxes
  • Button

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

埋め込みテーブルと画像を含むドキュメントを示すイラスト

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

埋め込みオブジェクトを含むドキュメントの UI オートメーション コンテンツ ビューの図

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

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

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

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

Objects 互換性のある埋め込みオブジェクト 互換性のない埋め込みオブジェクト
TextPattern 以外の埋め込みオブジェクト Microsoft Edge 内のボタン
Microsoft Edge 内のデータ テーブル		 Microsoft の XAML フレームワーク内にある RichTextBlock のボタン
Microsoft Edge 内の代替テキストを備えた画像
Microsoft の XAML フレームワーク内にある RichTextBlock の ListItems を備えた ListView
TextPattern 埋め込みオブジェクト Microsoft Edge 内の "text" 型の入力コントロール
Word 文書の表		 Microsoft Word 文書の TextBox 要素

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

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

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

Note

低次元テキスト (または折りたたまれた) 範囲は、開始エンドポイントと終了エンドポイントが同じです。 低次元テキスト範囲は、ITextProvider GetSelection メソッドと GetCaretRange メソッドを使用して、テキスト カーソル位置を示すために使用されることがよくあります。

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

埋め込みオブジェクトとその範囲を含むテキスト ストリームを示す図

埋め込みオブジェクトと 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 のメソッドを呼び出すと、次の表で説明する動作になります。

呼び出されるメソッド 結果
IUIAutomationTextRange::GetText 文字列 "URL https://www.microsoft.com はテキストに埋め込まれています" を返します。
IUIAutomationTextRange::GetEnclosingElement テキスト範囲を囲む最も内側の UI オートメーションを返します。この場合は、テキスト プロバイダー自体を表すオートメーション要素を返します。
IUIAutomationTextRange::GetChildren ハイパーリンク コントロールを表す UI オートメーション要素を返します。
IUIAutomationTextPattern::RangeFromChild。前の IUIAutomationTextRange::GetChildren メソッドによって UI オートメーション要素が返されました。 "https://www.microsoft.com" を表す範囲を返します。

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

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

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

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

呼び出されるメソッド 結果
IUIAutomationTextRange::GetText 文字列 "www" を返します。
IUIAutomationTextRange::GetEnclosingElement テキスト範囲を囲む最も内側の UI オートメーション要素を返します。この場合は、ハイパーリンク コントロールです。
IUIAutomationTextRange::GetChildren テキスト範囲が URL 文字列全体をカバーしていないため、NULL を返します。

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

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

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

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

呼び出されるメソッド 結果
IUIAutomationTextRange::GetText 文字列 "The URL" を返します。
IUIAutomationTextRange::GetEnclosingElement テキスト範囲を囲む最も内側の UI オートメーションを返します。この場合は、テキスト プロバイダー自体を表す要素を返します。
IUIAutomationTextRange::Move ハイパーリンクのテキストは個々の単語で成り立っているため、テキスト範囲は "https://" にわたります。 この場合、ハイパーリンクは 1 つのオブジェクトとして扱われません。
URL {http} はテキストに埋め込まれています。

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

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

{画像 スペース シャトルのイラスト がテキストに埋め込まれます}。

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

呼び出されるメソッド 結果
IUIAutomationTextRange::GetText 文字列 "画像がテキストに埋め込まれています" を返します。 画像に関連付けられた代替テキストは、テキスト ストリームに含まれていません。
IUIAutomationTextRange::GetEnclosingElement テキスト範囲を囲む最も内側の UI オートメーションを返します。この場合は、テキスト プロバイダー自体を表す要素を返します。
IUIAutomationTextRange::GetChildren 画像コントロールを表す UI オートメーション要素を返します。
IUIAutomationTextPattern::RangeFromChild。前の IUIAutomationTextRange::GetChildren メソッドによって UI オートメーション要素が返されました。 低次元テキスト範囲を返します。

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

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

{画像} スペース シャトルのイラスト がテキストに埋め込まれます。

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

呼び出されるメソッド 結果
IUIAutomationTextRange::GetText 文字列 "The image" を返します。
IUIAutomationTextRange::GetEnclosingElement テキスト範囲を囲む最も内側の UI オートメーションを返します。この場合は、テキスト プロバイダー自体を表す要素を返します。
(TextUnit_Word, 2) のパラメーターを持つ IUIAutomationTextRange::Move。 テキスト範囲は "is " に移動します。 テキスト ベースの埋め込みオブジェクトのみがテキスト ストリームの一部と見なされるため、この例の画像は IUIAutomationTextRange::Move やその戻り値 (この場合は 2) に影響を与えません。

テーブル

テーブル例 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 のメソッドを呼び出すと、次の表で説明する動作になります。

呼び出されるメソッド 結果
パラメーター (1,1) を持つ IUIAutomationGridPattern::GetItem。 テーブル セルの内容を表す UI オートメーション要素を返します。 この場合、要素はテキスト コントロールです。
IUIAutomationTextPattern::RangeFromChild。UI オートメーション要素は、前の IUIAutomationGridPattern::GetItem メソッドによって返されたオブジェクトです。 "Y" を返します。

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

Conceptual