Udostępnij za pośrednictwem

Jak automatyzacja interfejsu użytkownika uwidacznia obiekty osadzone

  • Artykuł

W tym temacie opisano, jak Microsoft UI Automation używa wzorców kontrolek Text i TextRange do uwidaczniania obiektów osadzonych (elementów podrzędnych/potomnych) w dokumencie tekstowym lub kontenerze.

W przypadku automatyzacji interfejsu użytkownika obiekt osadzony jest dowolnym elementem, który ma granice nietekstowe, takie jak obraz, hiperlink, tabela lub typ dokumentu (arkusz kalkulacyjny programu Microsoft Excel, plik Microsoft Windows Media itd.).

Notatka

Różni się to od definicji OLE modelu obiektów składowych (COM) (zobacz Embedded Objects), gdzie element jest tworzony w jednej aplikacji i osadzony lub połączony w innej aplikacji. 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, aby można było uzyskać do nich dostęp za pośrednictwem tego samego modelu obiektów co inne kontrolki w automatyzacji interfejsu użytkownika.

W poniższej tabeli wymieniono przykłady elementów kontenera i elementów innych niż kontener.

elementów kontenera

elementów innych niż kontener

  • Kalendarz
  • Lista rozwijana
  • DataGrid
  • Dokument
  • Edytuj
  • Grupa
  • Nagłówek
  • ElementNagłówka
  • Lista
  • Menu
  • Pasek menu
  • Szyba
  • SplitButton
  • Zakładka
  • Stół
  • Pasek narzędzi
  • Drzewo
  • TreeItem
  • Okno
  • Łącze
  • Pola wyboru
  • Przycisk

Na poniższej ilustracji przedstawiono kontener tekstowy (dokument) z osadzoną tabelą i obrazem.

ilustracja przedstawiająca dokument z osadzoną tabelą i obrazem

Na poniższym diagramie przedstawiono widok zawartości UI Automation w poprzednim dokumencie.

diagram przedstawiający widok zawartości dokumentu z obiektami osadzonymi w automatyzowanym interfejsie użytkownika

Obiekty osadzone "Zgodne" i "Niezgodne"

Niektórzy dostawcy automatyzacji interfejsu użytkownika używają tego samego magazynu tekstu dla każdego obiektu TextPattern, który zawierają. Obiekty wspierane przez ten sam magazyn tekstu co kontener są nazywane "zgodnymi" obiektami osadzonymi. Te obiekty mogą być obiektami TextPattern, a w tym przypadku ich zakresy tekstu są porównywalne z zakresami tekstu uzyskanymi z ich kontenera. Dzięki temu dostawcy mogą uwidaczniać informacje o poszczególnych obiektach TextPattern tak, jakby były jednym, dużym dostawcą tekstu.

Jednak dostawcy mogą używać różnych magazynów tekstu dla różnych obiektów TextPattern osadzonych w kontenerze TextPattern. Obiekty, które nie są obsługiwane przez magazyn tekstu kontenera, nazywane są niezgodnymi obiektami osadzonymi. Tego typu osadzone obiekty mogą, ale nie muszą być oparte na TextPattern.

W poniższej tabeli wymieniono kilka przykładów zgodnych i niezgodnych obiektów osadzonych.

Obiekty Zgodne obiekty osadzone Niekompatybilne obiekty osadzone
Obiekty osadzone nienależące do TextPattern Przycisk w przeglądarce Microsoft Edge
Tabela danych w przeglądarce Microsoft Edge		 Przycisk w narzędziu RichTextBlock w strukturze XAML firmy Microsoft
Obrazy z tekstem alternatywnym w Microsoft Edge
ListView z Elementami Listy w RichTextBlock w strukturze XAML firmy Microsoft
Obiekty osadzone w TextPattern Kontrolka wprowadzania typu "text" w przeglądarce Microsoft Edge
Tabela w dokumencie programu Word		 TextBox, element w dokumencie programu Microsoft Word

Uwidacznianie obiektów osadzonych

Wzorce kontrolek Text and TextRange uwidaczniają właściwości i metody ułatwiające nawigację i wykonywanie zapytań dotyczących 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. Wywołaj IUIAutomationTextRange::GetChildren, aby uzyskać interfejs IUIAutomationElement dla każdego obiektu osadzonego, a następnie wywołaj IUIAutomationTextPattern::RangeFromChild, aby uzyskać zakres tekstu dla każdego elementu. Odbywa się to rekursywnie do momentu pobrania całej zawartości tekstowej.

Notatka

Zdegenerowany (lub zwinięty) zakres to taki, w którym punkt początkowy i punkt końcowy są takie same. Zdegenerowane zakresy są często używane do wskazywania położenia kursora tekstu poprzez metody ITextProviderGetSelection i GetCaretRange.

Na poniższym diagramie przedstawiono strumień tekstowy z osadzonymi obiektami i ich zakresami.

diagram przedstawiający strumień tekstowy z osadzonymi obiektami i zakresami ich rozpiętości

Obiekty osadzone i TextUnit

Obiekt ITextProvider można przeszukiwać za pomocą określonej jednostki TextUnit. Dostawcy, którzy zawierają obiekty osadzone, mogą być przechodzeni w podobny sposób, ale obiekty osadzone faktycznie wpływają na sposób przechodzenia. Oto kilka rzeczy, o których należy pamiętać:

  • Każdy niezgodny obiekt osadzony jest reprezentowany przez znak zastępczy U+FFFC w magazynie tekstowym składnika kontenera TextPattern. Jest również uważany za jednostkę znaku i jednostkę słowa.
  • Zgodne obiekty osadzone mogą składać się z wielu znaków i wyrazów.
  • Otaczający element to najbardziej dolny element, który obejmuje cały zakres tekstu.
  • Elementy podrzędne zakresu są również elementami podrzędnymi elementu kontenera, który jest częściowo lub całkowicie zawarty w zakresie.
  • Najlepiej (zwłaszcza w przypadku elementów kontenera, takich jak Tabela), granica słowa nie wykracza poza granicę obiektu. W poniższym przykładzie, jednostka słowa "Bar" nie zawiera żadnej pozycji tekstowej, która znajduje się poza tagiem </td> (<br \> nie stanowi części jednostki słowa "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/>
  • Ogólnie rzecz biorąc, <br \> jest traktowana jako pojedyncze słowo, tak aby nie wykraczała poza granicę linii.
  • Wyjątkiem od poprzedniej reguły jest to, że jednostka tekstowa programu Word zawiera pełne obiekty w sobie. Na przykład <p>Hello <a href="#">link</a> here.</p>, która zawiera kontenery wbudowane, zawiera wyrazy "Hello", "link" i "here". Gdzie obiekt "link" ma obiekt TextPattern jako element otaczający i obiekt łącza jako jego element podrzędny.
  • W przypadku jednostek znaków obiekt jest elementem otaczającym (takie jednostki tekstowe nie powinny mieć elementów podrzędnych).
  • Obiekty adnotacji nie powinny być reprezentowane jako obiekt osadzony. Na przykład obecność innych oznaczeń autorów w dokumencie współtworzonym.
  • Obiekty osadzone zajmują co najmniej jedną pozycję kursora, adnotacja to tylko metadane.
  • Każda granica obiektu (początek i koniec) jest reprezentowana przez przerwę formatu w zakresie dokumentu TextPattern.
  • W przypadku języka HTML każdy tag HTML nie musi powodować obiektu automatyzacji interfejsu użytkownika. Na przykład zawartość wewnątrz tagów wyróżnienia nie musi być reprezentowana jako element, ale raczej jako zwykły strumień tekstowy, w którym UIA_IsItalicAttributeId zwraca wartość TRUE.
  • Punkt początkowy jest wliczany i jest preferowany, natomiast punkt końcowy jest wykluczany. To jest przydatne, gdy zakres jest zdegradowany i punkty początkowy i końcowy dotyczą tej samej pozycji w tym zakresie.

Porównywanie obiektów osadzonych

Zagnieżdżone obiekty TextPattern, które znajdują się w podobnej relacji podrzędnej i współużytkują ten sam magazyn tekstu zapasowego, są nazywane porównywalnymi. W tym przypadku zakresy z jednego z obiektów TextPattern można porównać przy użyciu ITextRangeProvider::Compare i ITextRangeProvider::CompareEndpoints. Oba wyniki powodują prawidłową wartość liczbową określającą ich położenie względne.

Obiekt inny niż TextPattern osadzony w obiekcie TextPattern jest porównywalny z obiektem TextPattern, jeśli obiekt ma prawidłowy zakres w obiekcie TextPattern (ITextProvider::RangeFromChild), a zawartość za zakresem tekstu nie jest pusta i nie jest znakiem zastępczym.

Osadzone obiekty TextPattern i TextUnit dokumentu

W przypadku osadzonych obiektów TextPattern jednostka Document rozpoznaje tylko zawartość zawartą w tym elemecie.

Hierarchia elementów TextPattern programu Word

  • Element dokumentu implementuje element TextPattern i Document zwraca cały zakres dokumentów programu Word.
  • Poszczególne strony dokumentu implementują TextPattern, a Document zwraca zawartość tych poszczególnych stron (mimo że strony współdzielą to samo przechowywanie tekstu z całym dokumentem TextPattern).

Kontrolki wprowadzania tekstu i strony internetowej w przeglądarce Edge

  • Główny element okienka strony internetowej implementuje element TextPattern i uwidacznia całą zawartość strony internetowej.
  • Poszczególne kontrolki wprowadzania tekstu obsługują wzorzec TextPattern, w którym zakres dokumentu reprezentuje tekst zawarty w każdym polu wejściowym (mimo że dzielą ten sam magazyn tekstowy z całą stroną internetową).

Typowe scenariusze

W tej sekcji przedstawiono przykłady typowych scenariuszy obejmujących obiekty osadzone: hiperlinki, obrazy i tabele. W poniższych przykładach lewy nawias klamrowy ({) reprezentuje punkt początkowy zakresu tekstu, a prawy nawias klamrowy (}) reprezentuje punkt końcowy.

Hiperlink — przykład 1: zakres tekstu zawierający osadzony hiperlink tekstowy

Poniższy zakres tekstu zawiera osadzone hiperłącze tekstowe.

{Adres URL https://www.microsoft.com jest osadzony w tekście}.

Wywoływanie metod IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildreni IUIAutomationTextPattern::RangeFromChild powoduje zachowania opisane w poniższej tabeli.

Metoda o nazwie Wynik
IUIAutomationTextRange::GetText Zwraca ciąg "Adres URL https://www.microsoft.com jest osadzony w tekście".
IUIAutomationTextRange::GetEnclosingElement Zwraca najbardziej wewnętrzny element automatyzacji interfejsu użytkownika, który obejmuje zakres tekstu, w tym przypadku element automatyzacji, który reprezentuje dostawcę tekstu.
IUIAutomationTextRange::GetChildren Zwraca element automatyzacji interfejsu użytkownika reprezentujący kontrolkę hiperłącza.
IUIAutomationTextPattern::RangeFromChild, gdzie element automatyzacji UI został zwrócony przez poprzednią metodę IUIAutomationTextRange::GetChildren. Zwraca zakres reprezentującyhttps://www.microsoft.com".

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

Poniższy zakres tekstu częściowo obejmuje osadzony hiperlink tekstowy.

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

Wywoływanie IUIAutomationTextRange::GetText, GetEnclosingElementi metod GetChildren powoduje zachowanie opisane w poniższej tabeli.

Metoda o nazwie Wynik
IUIAutomationTextRange::GetText Zwraca ciąg "www".
IUIAutomationTextRange::GetEnclosingElement Zwraca najbardziej wewnętrzny element automatyzacji interfejsu użytkownika, który otacza zakres tekstowy, konkretnie kontrolkę hiperłącza.
IUIAutomationTextRange::GetChildren Zwraca wartość NULL, ponieważ zakres tekstu nie obejmuje całego ciągu adresu URL.

Hiperlink — przykład 3: zakres tekstu, który częściowo obejmuje zawartość kontenera tekstowego

Poniższy zakres tekstu częściowo obejmuje zawartość kontenera tekstowego. Kontener tekstu ma osadzony hiperlink tekstowy, który nie jest częścią zakresu tekstu.

{Adres URL} https://www.microsoft.com jest osadzony w tekście.

Wywołanie metod IUIAutomationTextRange::GetText, GetEnclosingElementi Move skutkuje zachowaniem opisanym w poniższej tabeli.

Metoda o nazwie Wynik
IUIAutomationTextRange::GetText Zwraca ciąg "Adres URL".
IUIAutomationTextRange::GetEnclosingElement Zwraca najbardziej wewnętrzny element automatyzacji interfejsu użytkownika, który otacza zakres tekstu, w tym przypadku element reprezentujący samego dostawcę tekstu.
IUIAutomationTextRange::Move Przenosi zakres tekstu na "https://", 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.

Przykład obrazu 1: zakres tekstu zawierający osadzony obraz

Poniższy zakres tekstu zawiera osadzony obraz promu.

{Obraz ilustracji wahadłowca jest osadzony w tekście}.

Wywołanie metod IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildreni IUIAutomationTextPattern::RangeFromChild prowadzi do zachowań opisanych w poniższej tabeli.

Metoda o nazwie Wynik
IUIAutomationTextRange::GetText Zwraca ciąg "Obraz jest osadzony w tekście". Żaden tekst ALT skojarzony z obrazem nie jest uwzględniony w strumieniu tekstowym.
IUIAutomationTextRange::GetEnclosingElement Zwraca najbardziej wewnętrzny element automatyzacji interfejsu użytkownika, który otacza zakres tekstu, w tym przypadku element reprezentujący samego dostawcę tekstu.
IUIAutomationTextRange::GetChildren Zwraca element automatyzacji interfejsu użytkownika reprezentujący kontrolkę obrazu.
IUIAutomationTextPattern::RangeFromChild gdzie element automatyzacji interfejsu użytkownika został zwrócony przez poprzednią metodę IUIAutomationTextRange::GetChildren. Zwraca zakres zdegenerowany.

Przykład obrazu 2: zakres tekstu, który częściowo obejmuje zawartość kontenera tekstu

Poniższy zakres tekstu częściowo obejmuje zawartość kontenera tekstowego. Kontener tekstu ma osadzony obraz, który nie jest częścią zakresu tekstu.

{Obraz} ilustracji wahadłowca jest osadzony w tekście.

Wywołanie metody IUIAutomationTextRange::GetText, GetEnclosingElementi metody Move powoduje zachowanie opisane w poniższej tabeli.

Metoda o nazwie Wynik
IUIAutomationTextRange::GetText Zwraca ciąg "Obraz".
IUIAutomationTextRange::GetEnclosingElement Zwraca najbardziej wewnętrzny element automatyzacji interfejsu użytkownika, który otacza zakres tekstu, w tym przypadku element reprezentujący samego dostawcę tekstu.
IUIAutomationTextRange::Move z parametrami (TextUnit_Word, 2). Przenosi zakres tekstu na "is". Ponieważ tylko obiekty osadzone oparte na tekście są uważane za część strumienia tekstu, obraz w tym przykładzie nie ma wpływu na IUIAutomationTextRange::Move lub jego wartość zwracana, w tym przypadku 2.

Stół

Przykład tabeli 1: pobiera kontener tekstowy z zawartości komórki

Poniższa tabela pobiera kontener tekstowy z zawartości komórki.

Komórka z obrazem Komórka z tekstem
ilustracja promu kosmicznego X
ilustracja przestrzeni i teleskopu Y
ilustracja mikroskopu Z

Wywoływanie metod IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChildoraz IUIAutomationTextRange::GetEnclosingElement skutkuje zachowaniami opisanymi w poniższej tabeli.

Metoda o nazwie Wynik
IUIAutomationGridPattern::GetItem z parametrami (0, 0). Zwraca element automatyzacji interfejsu użytkownika reprezentujący zawartość komórki tabeli, w tym przypadku element jest kontrolką tekstową.
iuiautomationtextpattern::rangefromchild zwraca zakres obrazu ilustracji promu.
GetEnclosingElement dla obiektu zwróconego przez poprzednią metodę IUIAutomationTextPattern::RangeFromChild. Zwraca element automatyzacji interfejsu użytkownika reprezentujący komórkę tabeli. W tym przypadku element jest kontrolką tekstową, która obsługuje wzorzec kontrolki TableItem.
IUIAutomationTextRange::GetEnclosingElement dla obiektu zwróconego przez poprzednią metodę GetEnclosingElement. Zwraca element automatyzacji interfejsu użytkownika reprezentujący tabelę.
IUIAutomationTextRange::GetEnclosingElement dla obiektu zwróconego przez poprzednią metodę GetEnclosingElement. Zwraca element automatyzacji interfejsu użytkownika reprezentujący samego dostawcę tekstu.

Przykład tabeli 2: pobiera zawartość tekstową komórki

Tabela w poprzednim przykładzie pobiera zawartość tekstową komórki.

Wywołanie metod IUIAutomationGridPattern::GetItem i IUIAutomationTextPattern::RangeFromChild powoduje zachowania opisane w poniższej tabeli.

Metoda o nazwie Wynik
IUIAutomationGridPattern::GetItem z parametrami (1,1). Zwraca element automatyzacji interfejsu użytkownika reprezentujący zawartość komórki tabeli. W tym przypadku element jest kontrolką tekstową.
IUIAutomationTextPattern::RangeFromChild gdzie element automatyzacji interfejsu użytkownika jest obiektem zwróconym przez poprzednią metodę IUIAutomationGridPattern::GetItem. Zwraca wartość "Y".

Podczas przechodzenia przez dokument za pomocą TextUnit_Line, jeśli zakres tekstowy wchodzi w osadzoną tabelę, każdy wiersz tekstu w komórce powinien być traktowany jako wiersz.

Konceptualny