UI 자동화 포함된 개체를 노출하는 방법

아티클
07/04/2024

이 항목에서는 Microsoft UI 자동화 Text 및 TextRange 컨트롤 패턴을 사용하여 텍스트 문서 또는 컨테이너에 포함된 개체(자식/하위 요소)를 노출하는 방법을 설명합니다.

UI 자동화 경우 포함된 개체는 이미지, 하이퍼링크, 테이블 또는 문서 형식(Microsoft Excel 스프레드시트, Microsoft Windows Media 파일 등)과 같은 텍스트가 아닌 경계가 있는 요소입니다.

참고 항목

이는 요소가 한 애플리케이션에서 만들어지고 다른 애플리케이션에 포함되거나 연결된 COM(Component Object Model) OLE 정의(포함된 개체 참조)와 다릅니다. 원래 애플리케이션에서 개체를 편집할 수 있는지 여부는 UI 자동화 컨텍스트에서 관련이 없습니다.

포함된 개체 및 UI 자동화 트리

포함된 개체는 UI 자동화 트리의 컨트롤 뷰에서 개별 요소로 처리됩니다. UI 자동화 다른 컨트롤과 동일한 개체 모델을 통해 액세스할 수 있도록 텍스트 컨테이너의 자식으로 노출됩니다.

다음 표에서는 컨테이너 및 비 컨테이너 요소의 예를 나열합니다.

컨테이너 요소

비 컨테이너 요소

캘린더
콤보 상자
DataGrid
문서
편집
그룹
헤더
HeaderItem
List
메뉴

MenuBar
창
SplitButton
Tab
테이블
도구 모음
트리
TreeItem
창

링크
CheckBoxes
버튼

다음 이미지는 포함된 테이블과 이미지가 있는 텍스트 컨테이너(문서)를 보여 줍니다.

포함된 테이블 및 이미지가 있는 문서를 보여 주는 그림

이전 문서의 UI 자동화 콘텐츠 보기는 다음 다이어그램에 나와 있습니다.

포함된 개체가 있는 문서의 UI 자동화 콘텐츠 보기 다이어그램

"Compatible" 및 "Non-Compatible" 포함 개체

일부 UI 자동화 공급자는 포함된 각 TextPattern 개체에 대해 동일한 텍스트 저장소를 사용합니다. 컨테이너와 동일한 텍스트 저장소에서 지원되는 개체를 "호환되는" 포함된 개체라고 합니다. 이러한 개체는 TextPattern 개체 자체일 수 있으며, 이 경우 해당 텍스트 범위는 컨테이너에서 가져온 텍스트 범위와 비슷합니다. 이렇게 하면 공급자가 하나의 대형 텍스트 공급자인 것처럼 개별 TextPattern 개체에 대한 클라이언트 정보를 노출할 수 있습니다.

그러나 공급자는 TextPattern 컨테이너 내에 포함된 여러 TextPattern 개체에 대해 서로 다른 텍스트 저장소를 사용할 수 있습니다. 컨테이너의 텍스트 저장소에서 지원하지 않는 개체를 "호환되지 않는" 포함된 개체라고 합니다. 이러한 유형의 포함된 개체는 TextPattern 기반 개체일 수도 있고 그렇지 않을 수도 있습니다.

다음 표에서는 호환되는 개체와 호환할 수 없는 포함된 개체의 몇 가지 예를 나열합니다.

개체	호환되는 포함된 개체	호환할 수 없는 포함된 개체
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를 호출하여 각 요소에 대한 텍스트 범위를 가져옵니다. 이 과정은 모든 텍스트 내용이 검색될 때까지 반복적으로 수행됩니다.

참고 항목

퇴화(또는 축소된) 범위는 시작 엔드포인트와 엔드포인트가 동일한 위치입니다. 퇴행성 범위는 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 개체를 바깥쪽 요소로, 링크 개체를 자식으로 사용합니다.
문자 단위의 경우 개체는 바깥쪽 요소입니다(이와 같은 텍스트 단위에는 자식이 없어야 합니다).
주석 개체는 포함된 개체로 표시해서는 안 됩니다. 예를 들어 공동 작성 문서에 다른 작성자 지정자가 있습니다.
포함된 개체는 하나 이상의 커서 위치를 차지하며 주석은 메타데이터일 뿐입니다.
각 개체 경계(시작 및 끝)는 TextPattern 문서 범위의 서식 구분선으로 표시됩니다.
HTML의 경우 각 html 태그가 반드시 UI 자동화 개체가 되는 것은 아닙니다. 예를 들어 강조 태그 내 의 콘텐츠는 요소로 표현되지 않고 UIA_IsItalicAttributeId TRUE를 반환하는 텍스트 스트림으로 나타낼 필요가 없습니다.
시작 엔드포인트는 포함되며 엔드포인트는 배타적이지만 기본 엔드포인트입니다. 이는 범위가 퇴화되고 시작 및 끝 엔드포인트가 해당 범위에 대해 동일한 위치에 속하는 경우에 유용합니다.

포함된 개체 비교

비슷한 자식 관계에 있고 동일한 백업 텍스트 저장소를 공유하는 중첩된 TextPattern 개체를 비교 가능한 개체라고 합니다. 이 경우 ITextRangeProvider::Compare 및 ITextRangeProvider::CompareEndpoints를 사용하여 TextPattern 개체의 범위를 비교할 수 있습니다. 둘 다 상대 위치를 지정하는 유효한 숫자 값이 생성됩니다.

TextPattern 개체에 포함된 TextPattern이 아닌 개체는 TextPattern(ITextProvider::RangeFromChild)에 유효한 범위가 있고 텍스트 범위 뒤의 내용이 비어 있지 않고 대체 문자가 아닌 경우 TextPattern과 비슷합니다.

포함된 TextPattern 개체 및 Document TextUnit

포함된 TextPattern 개체의 경우 문서 단위는 해당 요소 내에 포함된 콘텐츠만 인식합니다.

Word TextPattern 요소 계층 구조

문서 요소는 TextPattern을 구현하고 Document 는 전체 Word 문서 범위를 반환합니다.
문서의 개별 페이지는 TextPattern을 구현하고 문서는 해당 개별 페이지의 콘텐츠를 반환합니다(페이지가 전체 문서 TextPattern과 동일한 텍스트 저장소를 공유하더라도).

Edge의 웹 페이지 및 텍스트 입력 컨트롤

기본 웹 페이지 창 요소는 TextPattern을 구현하고 전체 웹 페이지 콘텐츠를 노출합니다.
개별 텍스트 입력 컨트롤은 문서 범위가 각 입력 필드에 포함된 텍스트를 나타내는 TextPattern을 지원합니다(동일한 텍스트 저장소를 전체 웹 페이지와 공유하더라도).

일반적인 시나리오

이 섹션에서는 포함된 개체(하이퍼링크, 이미지 및 테이블)를 포함하는 일반적인 시나리오의 예를 제공합니다. 다음 예제에서 왼쪽 중괄호({)는 텍스트 범위의 시작 엔드포인트를 나타내고 오른쪽 중괄호(})는 엔드포인트를 나타냅니다.

하이퍼링크 예제 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. 여기서 UI 자동화 요소는 이전 IUIAutomationTextRange::GetChildren 메서드에 의해 반환되었습니다.	"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://"로 이동합니다. 이 경우 하이퍼링크는 단일 개체로 처리되지 않습니다. URL {http}이(가) 텍스트에 포함되어 있습니다.

이미지 예제 1: 포함된 이미지가 포함된 텍스트 범위

다음 텍스트 범위에는 셔틀의 포함된 이미지가 포함되어 있습니다.

{이미지 셔틀 그림 는 텍스트에 포함되어 있습니다}.

IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren 및 IUIAutomationTextPattern::RangeFromChild 메서드를 호출하면 다음 표에 설명된 동작이 발생합니다.

호출되는 메서드	결과
IUIAutomationTextRange::GetText	"이미지가 텍스트에 포함됨" 문자열을 반환합니다. 이미지와 연결된 ALT 텍스트는 텍스트 스트림에 포함되지 않습니다.
IUIAutomationTextRange::GetEnclosingElement	텍스트 범위를 둘러싸는 가장 안쪽 UI 자동화 요소(이 경우 텍스트 공급자 자체를 나타내는 요소)를 반환합니다.
IUIAutomationTextRange::GetChildren	이미지 컨트롤을 나타내는 UI 자동화 요소를 반환합니다.
IUIAutomationTextPattern::RangeFromChild. 여기서 UI 자동화 요소는 이전 IUIAutomationTextRange::GetChildren 메서드에 의해 반환되었습니다.	퇴행성 범위를 반환합니다.

이미지 예제 2: 텍스트 컨테이너의 내용에 부분적으로 걸쳐 있는 텍스트 범위

다음 텍스트 범위는 텍스트 컨테이너의 내용에 부분적으로 걸쳐 있습니다. 텍스트 컨테이너에는 텍스트 범위의 일부가 아닌 포함된 이미지가 있습니다.

{이미지} 셔틀 그림 는 텍스트에 포함되어 있습니다.

IUIAutomationTextRange::GetText, GetEnclosingElement 및 Move 메서드를 호출하면 다음 표에 설명된 동작이 발생합니다.

호출되는 메서드	결과
IUIAutomationTextRange::GetText	문자열 "The image"를 반환합니다.
IUIAutomationTextRange::GetEnclosingElement	텍스트 범위를 둘러싸는 가장 안쪽 UI 자동화 요소(이 경우 텍스트 공급자 자체를 나타내는 요소)를 반환합니다.
IUIAutomationTextRange::매개 변수를 사용하여 이동합니다 (TextUnit_Word, 2).	텍스트 범위를 "is "로 이동합니다. 텍스트 기반 포함된 개체만 텍스트 스트림의 일부로 간주되므로 이 예제의 이미지는 IUIAutomationTextRange::Move 또는 반환 값(이 경우 2)에 영향을 주지 않습니다.

테이블

표 예제 1: 셀 내용에서 텍스트 컨테이너를 가져옵니다.

다음 표에서는 셀 내용에서 텍스트 컨테이너를 가져옵니다.

이미지가 있는 셀	텍스트가 있는 셀
	X
	Y
	Z

IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild 및 IUIAutomationTextRange::GetEnclosingElement 메서드를 호출하면 다음 표에 설명된 동작이 발생합니다.

호출되는 메서드	결과
매개 변수가 있는 IUIAutomationGridPattern::GetItem (0, 0).	테이블 셀의 내용을 나타내는 UI 자동화 요소를 반환합니다. 이 경우 요소는 텍스트 컨트롤입니다.
iuiautomationtextpattern::rangefromchild	는 이미지 의 범위를 반환합니다.
이전 IUIAutomationTextPattern::RangeFromChild 메서드에서 반환된 개체에 대한 GetEnclosingElement입니다.	테이블 셀을 나타내는 UI 자동화 요소를 반환합니다. 이 경우 요소는 TableItem 컨트롤 패턴을 지원하는 텍스트 컨트롤입니다.
이전 GetEnclosingElement 메서드에서 반환된 개체에 대한 IUIAutomationTextRange::GetEnclosingElement입니다.	테이블을 나타내는 UI 자동화 요소를 반환합니다.
이전 GetEnclosingElement 메서드에서 반환된 개체에 대한 IUIAutomationTextRange::GetEnclosingElement입니다.	텍스트 공급자 자체를 나타내는 UI 자동화 요소를 반환합니다.

표 예제 2: 셀의 텍스트 내용을 가져옵니다.

앞의 예제의 표는 셀의 텍스트 내용을 가져옵니다.

IUIAutomationGridPattern::GetItem 및 IUIAutomationTextPattern::RangeFromChild 메서드를 호출하면 다음 표에 설명된 동작이 발생합니다.

호출되는 메서드	결과
매개 변수가 있는 IUIAutomationGridPattern::GetItem (1,1).	테이블 셀의 내용을 나타내는 UI 자동화 요소를 반환합니다. 이 경우 요소는 텍스트 컨트롤입니다.
IUIAutomationTextPattern::RangeFromChild. 여기서 UI 자동화 요소는 이전 IUIAutomationGridPattern::GetItem 메서드에서 반환된 개체입니다.	"Y"를 반환합니다.

TextUnit_Line 문서를 이동할 때 텍스트 범위가 포함된 표에 들어가면 셀의 각 텍스트 줄을 한 줄로 처리해야 합니다.

다음을 통해 공유

UI 자동화 포함된 개체를 노출하는 방법