埋め込みオブジェクトUI オートメーション公開する方法
このトピックでは、Microsoft UI オートメーションが Text コントロール パターンと TextRange コントロール パターンを使用して、テキスト ドキュメントまたはコンテナー内の埋め込みオブジェクト (子/子孫要素) を公開する方法について説明します。
UI オートメーションの場合、埋め込みオブジェクトは、画像、ハイパーリンク、テーブル、ドキュメントの種類 (Microsoft Excel スプレッドシート、Microsoft Windows Media ファイルなど) などのテキスト以外の境界を持つ任意の要素です。
注意
これは、1 つのアプリケーションで要素が作成され、別のアプリケーションに埋め込まれたりリンクされたりする、コンポーネント オブジェクト モデル (COM) OLE 定義とは異なります (「 埋め込みオブジェクト」を参照)。 オブジェクトを元のアプリケーションで編集できるかどうかは、UI オートメーションのコンテキストでは関係ありません。
埋め込みオブジェクトと UI オートメーション ツリー
埋め込みオブジェクトは、UI オートメーション ツリーのコントロール ビューで個々の要素として扱われます。 これらは、UI オートメーションの他のコントロールと同じオブジェクト モデルを介してアクセスできるように、テキスト コンテナーの子として公開されます。
次の表に、コンテナー要素とコンテナー以外の要素の例を示します。
コンテナー要素
コンテナー以外の要素
- Calendar
- Combobox
- DataGrid
- ドキュメント
- [編集]
- グループ
- ヘッダー
- HeaderItem
- List
- メニュー
- MenuBar
- ペイン
- SplitButton
- タブ
- テーブル
- ツール バー
- ツリー
- TreeItem
- ウィンドウ
- Link
- チェック
- Button
次の図は、埋め込みテーブルと画像を含むテキスト コンテナー (ドキュメント) を示しています。
前のドキュメントの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 を呼び出して各要素のテキスト範囲を取得します。 この操作は、すべてのテキスト コンテンツが取得されるまで再帰的に行われます。
注意
縮退 (または折りたたまれている) 範囲は、開始エンドポイントと終了エンドポイントが同じである場所です。 退化範囲は、多くの場合、 ITextProviderGetSelection メソッドと 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 を返すテキスト ストリームである必要があります。
- 開始エンドポイントは包括的であり、エンド エンドポイントが排他的である間に推奨されるエンドポイントです。 これは、範囲が縮退し、Start エンドポイントと End エンドポイントがその範囲の同じ位置に属している場合に便利です。
埋め込みオブジェクトの比較
同じ子リレーションシップにあり、同じバッキング テキスト ストアを共有する入れ子になった TextPattern オブジェクトは、比較可能と呼ばれます。 この場合、いずれかの TextPattern オブジェクトの範囲は、 ITextRangeProvider::Compare および ITextRangeProvider::CompareEndpoints を使用して比較できます。 両方とも、相対位置を指定する有効な数値になります。
TextPattern オブジェクトに埋め込まれている TextPattern 以外のオブジェクトは、オブジェクトが TextPattern (ITextProvider::RangeFromChild) 内の有効な範囲を持ち、テキスト範囲の背後にあるコンテンツが空ではなく、置換文字でない場合、TextPattern と同等です。
埋め込み TextPattern オブジェクトと Document TextUnit
埋め込み TextPattern オブジェクトの場合、 Document ユニットは、その要素に含まれるコンテンツのみを認識します。
Word TextPattern 要素階層
- document 要素は TextPattern を実装し、Document はドキュメント範囲全体Word返します。
- ドキュメントの個々のページは TextPattern を実装し、 Document はそれらの個々のページのコンテンツを返します (ページがドキュメント全体の TextPattern と同じテキスト ストアを共有している場合でも)。
Edge の Web ページとテキスト入力コントロール
- メイン Web ページ の Pane 要素は TextPattern を実装し、Web ページコンテンツ全体を公開します。
- 個々のテキスト入力コントロールは TextPattern をサポートします。この場合、ドキュメント範囲は各入力フィールドに含まれるテキストを表します (Web ページ全体で同じテキスト ストアを共有している場合でも)。
一般的なシナリオ
このセクションでは、埋め込みオブジェクトを含む一般的なシナリオの例を示します。ハイパーリンク、画像、テーブル。 次の例では、左中かっこ ({) はテキスト範囲の開始エンドポイントを表し、右中かっこ (}) は End エンドポイントを表します。
HyperLink の例 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"" を表す範囲を返します。 |
HyperLink の例 2: 埋め込みテキスト ハイパーリンクを部分的にまたがるテキスト範囲
次のテキスト範囲は、埋め込みテキスト ハイパーリンクに部分的にまたがっています。
URL https://{www} はテキストに埋め込まれています。
IUIAutomationTextRange::GetText、GetEnclosingElement、および GetChildren メソッドを呼び出すと、次の表に示す動作が発生します。
| 呼び出されるメソッド | 結果 |
|---|---|
| IUIAutomationTextRange::GetText | 文字列 "www" を返します。 |
| IUIAutomationTextRange::GetEnclosingElement | テキスト範囲を囲む最も内側のUI オートメーション要素 (この場合はハイパーリンク コントロール) を返します。 |
| IUIAutomationTextRange::GetChildren | テキスト範囲が URL 文字列全体にまたがらないため、 NULL を 返します。 |
HyperLink の例 3: テキスト コンテナーの内容を部分的にまたがるテキスト範囲
次のテキスト範囲は、テキスト コンテナーの内容に部分的にまたがっています。 テキスト コンテナーには、テキスト範囲に含まれない埋め込みテキスト ハイパーリンクが含まれます。
{URL} https://www.microsoft.com はテキストに埋め込まれています。
IUIAutomationTextRange::GetText、GetEnclosingElement、および Move メソッドを呼び出すと、次の表で説明する動作になります。
| 呼び出されるメソッド | 結果 |
|---|---|
| IUIAutomationTextRange::GetText | 文字列 "The URL" を返します。 |
| IUIAutomationTextRange::GetEnclosingElement | テキスト範囲を囲む最も内側のUI オートメーション要素 (この場合はテキスト プロバイダー自体を表す要素) を返します。 |
| IUIAutomationTextRange::Move | ハイパーリンクのテキストは個々の単語で構成されるため、テキスト範囲スパンを "https://" に移動します。 この場合、ハイパーリンクは 1 つのオブジェクトとして扱われません。 The URL {http} is embedded in text. |
画像の例 1: 埋め込み画像を含むテキスト範囲
次のテキスト範囲には、シャトルの埋め込み画像が含まれています。
{ 
はテキストに埋め込まれています}。
IUIAutomationTextRange::GetText、GetEnclosingElement、GetChildren、および IUIAutomationTextPattern::RangeFromChild メソッドを呼び出すと、次の表で説明する動作になります。
| 呼び出されるメソッド | 結果 |
|---|---|
| IUIAutomationTextRange::GetText | 文字列 "画像はテキストに埋め込まれています" を返します。 画像に関連付けられている代替テキストは、テキスト ストリームに含まれません。 |
| IUIAutomationTextRange::GetEnclosingElement | テキスト範囲を囲む最も内側のUI オートメーション要素 (この場合はテキスト プロバイダー自体を表す要素) を返します。 |
| IUIAutomationTextRange::GetChildren | イメージ コントロールを表すUI オートメーション要素を返します。 |
| 前の IUIAutomationTextRange::GetChildren メソッドによってUI オートメーション要素が返された IUIAutomationTextPattern::RangeFromChild。 | 縮退範囲を返します。 |
画像例 2: テキスト コンテナーの内容を部分的にまたがるテキスト範囲
次のテキスト範囲は、テキスト コンテナーの内容に部分的にまたがっています。 テキスト コンテナーには、テキスト範囲に含まれない埋め込みイメージが含まれます。
{画像} がテキストに埋め込まれています。
IUIAutomationTextRange::GetText、GetEnclosingElement、および Move メソッドを呼び出すと、次の表で説明する動作になります。
| 呼び出されるメソッド | 結果 |
|---|---|
| IUIAutomationTextRange::GetText | 文字列 "The image" を返します。 |
| IUIAutomationTextRange::GetEnclosingElement | テキスト範囲を囲む最も内側のUI オートメーション要素 (この場合はテキスト プロバイダー自体を表す要素) を返します。 |
| IUIAutomationTextRange::Move パラメーターが (TextUnit_Word、2) の場合。 | テキスト範囲は "is " に移動します。 テキスト ベースの埋め込みオブジェクトのみがテキスト ストリームの一部と見なされるため、この例の画像は IUIAutomationTextRange::Move またはその戻り値 (この場合は 2) には影響しません。 |
テーブル
表 例 1: セルの内容からテキスト コンテナーを取得する
次の表は、セルの内容からテキスト コンテナーを取得します。
| イメージを含むセル | テキストを含むセル |
|---|---|
|
X |
 |
Y |
 |
Z |
IUIAutomationGridPattern::GetItem、IUIAutomationTextPattern::RangeFromChild、および IUIAutomationTextRange::GetEnclosingElement メソッドを呼び出すと、次の表で説明する動作になります。
| 呼び出されるメソッド | 結果 |
|---|---|
| パラメーター (0、0) を含む IUIAutomationGridPattern::GetItem。 | テーブル セルの内容を表すUI オートメーション要素を返します。この場合、要素はテキスト コントロールです。 |
| iuiautomationtextpattern::rangefromchild | は、シャトルの画像 。 |
| 前の IUIAutomationTextPattern::RangeFromChild メソッドによって返されたオブジェクトの GetEnclosingElement。 | テーブル セルを表すUI オートメーション要素を返します。 この場合、要素は TableItem コントロール パターンをサポートするテキスト コントロールです。 |
| 前の GetEnclosingElement メソッドによって返されたオブジェクトの IUIAutomationTextRange::GetEnclosingElement。 | テーブルを表すUI オートメーション要素を返します。 |
| 前の GetEnclosingElement メソッドによって返されたオブジェクトの IUIAutomationTextRange::GetEnclosingElement。 | テキスト プロバイダー自体を表すUI オートメーション要素を返します。 |
表 例 2: セルのテキスト コンテンツを取得する
前の例の表は、セルのテキスト コンテンツを取得します。
IUIAutomationGridPattern::GetItem メソッドと IUIAutomationTextPattern::RangeFromChild メソッドを呼び出すと、次の表で説明する動作になります。
| 呼び出されるメソッド | 結果 |
|---|---|
| パラメーター (1,1) を含む IUIAutomationGridPattern::GetItem。 | テーブル セルの内容を表すUI オートメーション要素を返します。 この場合、 要素はテキスト コントロールです。 |
| IUIAutomationTextPattern::RangeFromChild。ここで、UI オートメーション要素は、前の IUIAutomationGridPattern::GetItem メソッドによって返されるオブジェクトです。 | "Y" を返します。 |
TextUnit_Lineで文書内を移動する場合、テキスト範囲が埋め込みテーブルに入った場合、セル内のテキストの各行は行として扱われる必要があります。
関連トピック
概念
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示