Omówienie wzorców tekstowych i obiektów osadzonych

2025-06-22

Uwaga / Notatka

Ta dokumentacja jest przeznaczona dla deweloperów programu .NET Framework, którzy chcą używać zarządzanych klas automatyzacji interfejsu użytkownika zdefiniowanych w przestrzeni nazw System.Windows.Automation. Aby uzyskać najnowsze informacje na temat automatyzacji interfejsu użytkownika, zobacz Windows Automation API: Automatyzacja interfejsu użytkownika.

W tym omówieniu opisano, jak usługa Microsoft UI Automation uwidacznia obiekty osadzone lub elementy podrzędne w dokumencie tekstowym lub kontenerze.

W automatyzacji interfejsu użytkownika osadzony obiekt jest dowolnym elementem, który ma granice nietekstowe; na przykład obraz, hiperlink, tabela lub typ dokumentu, taki jak arkusz kalkulacyjny programu Microsoft Excel lub plik Microsoft Windows Media. Różni się to od standardowej definicji, w której element jest tworzony w jednej aplikacji i osadzony lub połączony w innym. To, czy obiekt można edytować w oryginalnej aplikacji, nie ma znaczenia w kontekście automatyzacji interfejsu użytkownika.

Obiekty osadzone i drzewo automatyzacji interfejsu użytkownika

Obiekty osadzone są traktowane jako poszczególne elementy w widoku sterowania drzewa automatyzacji interfejsu użytkownika. Są one widoczne jako elementy podrzędne kontenera tekstu, dzięki czemu można uzyskać do nich dostęp za pośrednictwem tego samego modelu, co inne kontrolki w automatyzacji interfejsu użytkownika.

Osadzona tabela z obrazem w kontenerze tekstowym Przykład kontenera tekstowego z obiektami osadzonymi tabel, obrazów i hiperłączy

Widok zawartości poprzedniego przykładu Przykład widoku zawartości dla części poprzedniego kontenera tekstu

Uwidaczniaj obiekty osadzone przy użyciu textPattern i TextPatternRange

Używany w połączeniu, klasa wzorca kontrolki TextPattern i klasa TextPatternRange uwidaczniają metody i właściwości, które ułatwiają nawigowanie oraz znajdowanie obiektów osadzonych.

Zawartość tekstowa (lub tekst wewnętrzny) kontenera tekstowego i osadzonego obiektu, takiego jak hiperlink lub komórka tabeli, jest widoczna jako pojedynczy, ciągły strumień tekstowy zarówno w widoku kontrolki, jak i w widoku zawartości drzewa automatyzacji interfejsu użytkownika; granice obiektów są ignorowane. Jeśli klient automatyzacji interfejsu użytkownika pobiera tekst w celu recytowania, interpretowania lub analizowania w jakiś sposób, zakres tekstu powinien być sprawdzany pod kątem specjalnych przypadków, takich jak tabela z zawartością tekstową lub innymi osadzonymi obiektami. Można to osiągnąć przez wywołanie GetChildren w celu uzyskania AutomationElement dla każdego osadzonego obiektu, a następnie wywołanie RangeFromChild w celu uzyskania zakresu tekstu dla każdego elementu. Odbywa się to rekursywnie do momentu pobrania całej zawartości tekstowej.

Zakresy tekstu mieszczące się w obiektach osadzonych. Przykład strumienia tekstowego z osadzonymi obiektami i ich zakresami

Kiedy konieczne jest przetwarzanie zawartości zakresu tekstu, za kulisami zachodzi szereg kroków, aby metoda Move została pomyślnie wykonana.

Zakres tekstu jest znormalizowany; oznacza to, że zakres tekstu jest zwinięty do zdegenerowanego zakresu w Start punkcie końcowym, co sprawia, że End punkt końcowy jest niepotrzebny. Ten krok jest niezbędny do usunięcia niejednoznaczności w sytuacjach, w których zakres tekstu obejmuje TextUnit granice: na przykład gdzie {The URL https://www.microsoft.com is embedded in text "{" i "}" są punktami końcowymi zakresu tekstu.
Zakres wynikowy jest cofany w DocumentRange do początku żądanej granicy TextUnit.
Zakres jest przesuwany do przodu lub do tyłu DocumentRange przez żądaną liczbę TextUnit granic.
Zakres jest następnie rozszerzany z zdegenerowanego stanu zakresu przez przeniesienie End punktu końcowego przez jedną żądaną TextUnit granicę.

UIA_TextPattern_MoveAndExpand_Examples: Dostosowanie zakresu za pomocą funkcji Move() i ExpandToEnclosingUnit() Przykłady, jak zakres tekstu jest dostosowany za pomocą funkcji Move() i ExpandToEnclosingUnit()

Typowe scenariusze

W poniższych sekcjach przedstawiono przykłady najbardziej typowych scenariuszy obejmujących obiekty osadzone.

Legenda przykładów pokazanych:

{ = Start

} = End

Hiperłącze

Przykład 1 — zakres tekstu zawierający wbudowane hiperłącze

{The URL https://www.microsoft.com is embedded in text}.

Metoda o nazwie	Wynik
GetText	Zwraca ciąg `The URL https://www.microsoft.com is embedded in text`.
GetEnclosingElement	Zwraca najgłębiej zagnieżdżony AutomationElement, który obejmuje zakres tekstu; w tym przypadku jest to AutomationElement, który reprezentuje samego dostawcę tekstu.
GetChildren	Zwraca AutomationElement reprezentującą kontrolkę hiperłącza.
RangeFromChild gdzie AutomationElement jest obiekt zwracany przez poprzednią `GetChildren` metodę.	Zwraca zakres reprezentujący `https://www.microsoft.com`.

Przykład 2 — zakres tekstu, który częściowo obejmuje osadzone hiperłącze tekstowe

Adres URL https://{[www]} jest osadzony w tekście.

Metoda o nazwie	Wynik
GetText	Zwraca ciąg "www".
GetEnclosingElement	Zwraca najbardziej wewnętrzny AutomationElement, który obejmuje zakres tekstowy; w tym przypadku jest to kontrolka hiperłącza.
GetChildren	Zwraca wartość `null` , ponieważ zakres tekstu nie obejmuje całego ciągu adresu URL.

Przykład 3 — zakres tekstu, który częściowo obejmuje zawartość kontenera tekstu. Kontener tekstu ma osadzony hiperlink tekstowy, który nie jest częścią zakresu tekstu.

{The URL} [https://www.microsoft.com](https://www.microsoft.com) is embedded in text.

Metoda o nazwie	Wynik
GetText	Zwraca ciąg "Adres URL".
GetEnclosingElement	Zwraca najgłębiej zagnieżdżony AutomationElement, który obejmuje zakres tekstu; w tym przypadku jest to AutomationElement, który reprezentuje samego dostawcę tekstu.
Move z parametrami (JednostkaTekstowa.Słowo, 1).	Przenosi zakres tekstu na "http", ponieważ tekst hiperłącza składa się z pojedynczych wyrazów. W takim przypadku hiperlink nie jest traktowany jako pojedynczy obiekt. Adres URL {[http]} jest osadzony w tekście.

Obraz

Przykład 1 — zakres tekstu zawierający osadzony obraz

{ Przykład osadzonego obrazu jest osadzony w tekście}.

Metoda o nazwie	Wynik
GetText	Zwraca ciąg "Jest osadzony w tekście". Nie można oczekiwać, że dowolny tekst ALT skojarzony z obrazem zostanie uwzględniony w strumieniu tekstowym.
GetEnclosingElement	Zwraca najgłębiej zagnieżdżony AutomationElement, który obejmuje zakres tekstu; w tym przypadku jest to AutomationElement, który reprezentuje samego dostawcę tekstu.
GetChildren	Zwraca element AutomationElement, który reprezentuje kontrolkę obrazu.
RangeFromChild gdzie AutomationElement jest obiekt zwracany przez poprzednią GetChildren metodę.	Zwraca zdegenerowany zakres reprezentujący "".

Przykład 2 — zakres tekstu, który częściowo obejmuje zawartość kontenera tekstu. Kontener tekstu ma osadzony obraz, który nie jest częścią zakresu tekstu.

{Obraz} Przykład osadzonego obrazu jest osadzony w tekście.

Metoda o nazwie	Wynik
GetText	Zwraca ciąg "Obraz".
GetEnclosingElement	Zwraca najgłębiej zagnieżdżony AutomationElement, który obejmuje zakres tekstu; w tym przypadku jest to AutomationElement, który reprezentuje samego dostawcę tekstu.
Move z parametrami (JednostkaTekstowa.Słowo, 1).	Przenosi zakres tekstu na "is". Ponieważ tylko tekstowe obiekty osadzone są traktowane jako część strumienia tekstowego, obraz w tym przykładzie nie ma wpływu na Move() ani na jego wartość zwracaną (1 w tym przypadku).

Tabela

Tabela używana na potrzeby przykładów

Komórka z obrazem	Komórka z tekstem
	X
	Y
Obraz dla Z	Z

Przykład 1 — pobieranie kontenera tekstu z zawartości komórki.

Metoda wywołana	Wynik
GetItem z parametrami (0,0)	Zwraca reprezentację AutomationElement zawartości komórki tabeli. W tym przypadku element jest kontrolką tekstową.
RangeFromChild gdzie AutomationElement jest obiekt zwracany przez poprzednią `GetItem` metodę.	Zwraca zakres obejmujący obraz .
GetEnclosingElement dla obiektu zwróconego przez poprzednią `RangeFromChild` metodę.	Zwraca reprezentującą AutomationElement komórkę tabeli. W tym przypadku element jest kontrolką tekstową, która obsługuje element TableItemPattern.
GetEnclosingElement dla obiektu zwróconego przez poprzednią `GetEnclosingElement` metodę.	Zwraca AutomationElement, który reprezentuje tabelę.
GetEnclosingElement dla obiektu zwróconego przez poprzednią `GetEnclosingElement` metodę.	Zwraca wartość AutomationElement reprezentującą samego dostawcę tekstu.

Przykład 2 — Pobierz zawartość tekstową komórki.

Metoda wywołana	Wynik
GetItem z parametrami (1,1).	Zwraca reprezentację AutomationElement zawartości komórki tabeli. W tym przypadku element jest kontrolką tekstową.
RangeFromChild gdzie AutomationElement jest obiekt zwracany przez poprzednią `GetItem` metodę.	Zwraca wartość "Y".

Udostępnij za pośrednictwem