Nuta
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować się zalogować lub zmienić katalog.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
W tym temacie opisano sposób używania właściwości i metod interfejsu IUIAutomationTextRange w celu uzyskania dostępu do zawartości tekstowej kontrolki opartej na tekście i manipulowania nią.
Co to jest zakres tekstu?
Model obiektów tekstowych automatyzacji interfejsu użytkownika firmy Microsoft jest oparty na koncepcji zakresu tekstu . Zakres tekstu to obiekt, który uwidacznia interfejs IUIAutomationTextRange i reprezentuje ciągły zakres tekstu w kontrolce opartej na tekście. Każdy zakres tekstu ma zarówno początkowy punkt końcowy, jak i końcowy punkt końcowy, a cała zawartość tekstowa między dwoma punktami końcowymi jest traktowana jako część zakresu. Zakres tekstu, którego początek i koniec znajdują się w tym samym miejscu, jest nazywany zdegenerowanym (lub pustym) zakresem tekstu. Zakres zdegenerowanego tekstu służy do oznaczania określonej lokalizacji w tekście kontrolki, na przykład lokalizacji punktu wstawienia tekstu.
Uzyskiwanie obiektów zakresu tekstu
Aplikacje klienckie uzyskują obiekty zakresu tekstu przy użyciu właściwości i metod interfejsu IUIAutomationTextPattern. Właściwość IUIAutomationTextRangePattern::DocumentRange pobiera zakres tekstu, który reprezentuje całą zawartość tekstową kontrolki opartej na tekście. Inne metody uzyskują zakresy tekstu reprezentujące fragment zawartości, takie jak zaznaczony tekst, widoczny tekst lub obiekt osadzony w tekście.
Metody IUIAutomationTextRangePattern::GetVisibleRanges i GetSelection mogą pobierać tablice obiektów zakresu tekstu. Jeśli kontrolka jest częściowo zasłonięta przez nakładające się okno lub inny obiekt, GetVisibleRanges zwraca tablicę zawierającą obiekt zakresu tekstu dla każdego częściowo widocznego wiersza tekstu. Podobnie, jeśli kontrolka oparta na tekście obsługuje wybór wielu, rozłącznych zakresów tekstu, GetSelection zwraca tablicę zawierającą obiekt zakresu tekstu dla każdego zaznaczonego zakresu.
Metoda IUIAutomationTextRangePattern::RangeFromChild umożliwia aplikacji klienckiej pobranie zakresu tekstu zawierającego obiekt osadzony w zawartości tekstowej. Klient określa IUIAutomationElement wskaźnik interfejsu obiektu osadzonego, taki jak obraz, tabela lub hiperlink, a metoda zwraca zakres tekstu, który otacza obiekt. Jeśli jednak osadzony obiekt nie ma skojarzonego z nim tekstu, metoda zwraca zdegenerowane zakresy tekstu.
Aplikacja kliencka może użyć metody IUIAutomationTextRangePattern::RangeFromPoint, aby pobrać zakres tekstu dla widocznego tekstu lub obiektu osadzonego znajdującego się najbliżej określonych współrzędnych ekranu.
Zaznaczanie tekstu w obrębie zakresu
Interfejs IUIAutomationTextRange zawiera szereg metod, które umożliwiają aplikacji klienckiej kontrolowanie zaznaczenia tekstu w kontrolce o charakterze tekstowym.
Aplikacje klienckie mogą użyć metody IUIAutomationTextRange::Select, aby wybrać tekst odpowiadający zakresowi tekstu i usunąć poprzednie zaznaczenie, jeśli istnieje, z kontrolki tekstu. Wywołanie Select z zdegenerowanym zakresem tekstowym przenosi punkt wstawiania do pozycji tego zakresu tekstowego bez zaznaczania tekstu.
Jeśli kontrolka obsługuje wybór wielu, rozłącznych zakresów tekstu, klient może użyć metod IUIAutomationTextRange::AddToSelection i RemoveFromSelection, aby dodać zakresy tekstu do kolekcji wybranych zakresów tekstu oraz je z niej usunąć. Jeśli kontrolka obsługuje tylko jeden zaznaczony zakres tekstu jednocześnie, ale operacja zaznaczenia spowoduje zaznaczenie wielu rozłącznych zakresów tekstu, metoda zwraca błąd E_INVALIDOPERATION lub rozszerza lub obcina bieżące zaznaczenie. Aplikacja kliencka może ustalić, czy element sterujący obsługuje wybór jednego lub wielu zakresów tekstu, lub wcale, sprawdzając właściwość IUIAutomationTextPattern::SupportedTextSelection.
Jeśli kontrolka oparta na tekście obsługuje wstawiania tekstu, wywoływanie metody IUIAutomationTextRange::AddToSelection lub RemoveFromSelection na zdegeneranym zakresie tekstu w kontrolce przenosi punkt wstawiania, ale nie zaznacza żadnego tekstu.
Pobieranie tekstu z zakresu tekstowego
Aplikacje klienckie mogą używać metody IUIAutomationTextRange::GetText w celu pobrania zwykłego tekstu zakresu tekstu. Tekst zwykły zawiera wszystkie znaki sterujące znalezione w tekście źródłowym, takie jak znak powrotu karetki i znak kierunku tekstu od lewej do prawej (LRM). Zwykły tekst nie zawiera żadnych tagów znaczników, takich jak HTML, które mogą być obecne w tekście źródłowym. Ponadto wszystkie kody ucieczki w tekście źródłowym są konwertowane na odpowiedniki zwykłego tekstu. Na przykład znak " " jest konwertowany na prosty znak spacji.
Jeśli osadzony obiekt obejmuje zakres tekstu, zwykły tekst zawiera tekst wewnętrzny obiektu, ale nie tekst alternatywny (właściwość 'nazwa' obiektu osadzonego). Aby uzyskać więcej informacji, zobacz Jak automatyzacja interfejsu użytkownika uwidacznia obiekty osadzone.
Metoda IUIAutomationTextRange::FindText wyszukuje zakres tekstu dla określonego ciągu, a jeśli zostanie znaleziony, zwraca nowy zakres tekstu obejmujący ciąg.
Pobieranie atrybutów tekstu z zakresu tekstu
Atrybuty tekstu określają styl formatowania tekstu w kontrolce opartej na tekście i zawierają takie elementy jak kolor pierwszego planu, styl punktora, rozmiar czcionki itd. Automatyzacja interfejsu użytkownika obsługuje wiele atrybutów tekstowych i definiuje identyfikator dla każdego obsługiwanego atrybutu. Aplikacja kliencka może wykonać zapytanie dotyczące zakresu tekstu dla wartości określonego atrybutu tekstowego, określając identyfikator atrybutu w wywołaniu metody IUIAutomationTextRange::GetAttributeValue, wraz z wskaźnikiem do variant struktury, która odbiera wartość atrybutu. Aby uzyskać szczegółowe informacje na temat każdego atrybutu tekstowego obsługiwanego przez automatyzację interfejsu użytkownika, zobacz identyfikatory atrybutów tekstowych.
Wartość pobrana przez GetAttributeValue reprezentuje wartość atrybutu w całym zakresie tekstu. Jeśli cały tekst w zakresie ma tę samą wartość dla określonego atrybutu, ta wartość jest zwracana przez GetAttributeValue. Jeśli jednak wartość atrybutu różni się w zakresie tekstu, GetAttributeValue zwraca wskaźnik IUnknown do statycznego obiektu tokenu o nazwie ReservedMixedAttribute. Aby sprawdzić, czy wartość atrybutu różni się w zakresie tekstu, aplikacja kliencka powinna porównać wyniki GetAttributeValue z obiektem ReservedMixedAttribute pobranym z właściwości IUIAutomation::ReservedMixedAttributeValue.
Kontrolka oparta na tekście nie jest wymagana do obsługi wszystkich atrybutów tekstu automatyzacji interfejsu użytkownika. Jeśli klient wywołuje metodę IUIAutomationTextRange::GetAttributeValue i przekazuje identyfikator atrybutu, który nie jest obsługiwany, metoda zwraca wskaźnik IUnknown do statycznego obiektu tokenu o nazwie ReservedNotSupported. Aby sprawdzić, czy dany atrybut jest obsługiwany, aplikacja kliencka powinna porównać wyniki GetAttributeValue z właściwością ReservedNotSupported pobraną z właściwości IUIAutomation::ReservedNotSupportedValue.
Aplikacje klienckie mogą używać metody IUIAutomationTextRange::FindAttribute w celu wyszukania zakresu tekstu zawierającego określony atrybut tekstowy. Jeśli zostanie znaleziona, metoda zwraca nowy zakres tekstu, który obejmuje pasujący tekst. Należy pamiętać, że FindAttribute zwraca zakres tekstu pasujący do tekstu, nawet jeśli tekst nie jest widoczny.
Pobieranie obiektów osadzonych z zakresu tekstu
Zakres tekstu może zawierać obiekty osadzone, takie jak tabele, obrazy, hiperlinki itd. Aplikacja klienta może pobrać zbiór wszystkich osadzonych obiektów w danym zakresie, wywołując metodę IUIAutomationTextRange::GetChildren. Obiekty osadzone, które nakładają się na zakres, ale nie są w nim całkowicie ujęte, zawierają się także w kolekcji. Jeśli zakres nie zawiera żadnych obiektów osadzonych, GetChildren pobiera pustą kolekcję.
Mimo że zależy to od dostawcy kontrolki opartej na tekście, metoda GetChildren zwykle nie zwraca żadnych elementów podrzędnych elementów osadzonych. Jeśli na przykład zakres tekstu zawiera tabelę zawierającą kilka komórek podrzędnych, metoda GetChildren zwykle zwraca tylko element tabeli, a nie elementy komórki.
Ze względów wydajnościowych lub architektonicznych GetChildren może nie być w stanie pobrać obiektów IUIAutomationElement dla wszystkich obiektów osadzonych w zakresie tekstu. Zamiast tego dostawca może zwrócić kolekcję zawierającą elementy zwirtualizowane. Aby uzyskać więcej informacji, zobacz Praca z elementami zwirtualizowanymi.
Manipulowanie zakresem tekstu
Interfejs IUIAutomationTextRange udostępnia kilka metod manipulowania zakresami tekstu i nawigowania po nim w kontrolce opartej na tekście. Metody IUIAutomationTextRange::Move, MoveEndpointByUnitoraz ExpandToEnclosingUnit przenoszą zakres tekstu lub jeden z jego punktów końcowych przez określoną jednostkę tekstową, taką jak znak, wyraz, akapit itd. Aby uzyskać więcej informacji, zobacz Jednostki tekstu automatyzacji interfejsu użytkownika.
Pomimo nazwy metoda ExpandToEnclosingUnit nie musi rozszerzać zakresu tekstu. Zamiast tego "normalizuje" zakres tekstu, przenosząc punkty końcowe, tak aby zakres obejmował dokładnie określoną jednostkę tekstową. Zakres jest rozszerzany, jeśli jest mniejszy niż określona jednostka, lub skrócony, jeśli jest dłuższy niż określona jednostka. Na poniższym diagramie pokazano, jak ExpandToEnclosingUnit normalizuje zakres tekstu, przenosząc punkty końcowe zakresu.
Jeśli zakres tekstu rozpoczyna się na początku jednostki tekstowej i kończy się na początku lub przed następną granicą jednostki tekstowej, końcowy punkt jest przenoszony do następnej granicy jednostki tekstowej (patrz 1 i 2 na poprzedniej ilustracji).
Jeśli zakres tekstu rozpoczyna się od początku jednostki tekstowej i kończy się na lub po następnej granicy jednostki, końcowy punkt końcowy pozostaje lub jest przenoszony do następnej granicy jednostki po początkowym punkcie końcowym (patrz 3 i 4 na poprzedniej ilustracji). Jeśli między początkowym a końcowym punktem istnieje więcej niż jedna granica jednostki tekstowej, punkt końcowy przesuwa się wstecz do następnej granicy jednostki po początkowym punkcie, co skutkuje zakresem tekstu, który ma długość jednej jednostki tekstowej.
Jeśli zakres tekstu rozpoczyna się w środku jednostki tekstowej, początkowy punkt końcowy zostanie przeniesiony do tyłu do początku jednostki tekstowej, a końcowy punkt końcowy zostanie przeniesiony do przodu lub do tyłu, w razie potrzeby, do następnej granicy jednostki po początkowym punkcie końcowym (patrz od 5 do 8 na poprzedniej ilustracji).
Po wywołaniu metody IUIAutomationTextRange::Move dostawca normalizuje zakres tekstu według określonej jednostki tekstowej. Następnie dostawca przenosi zakres do tyłu lub do przodu przez określoną liczbę jednostek tekstu. Podczas przenoszenia zakresu dostawca ignoruje granice wszelkich osadzonych obiektów w tekście. (Jednak sama granica jednostki może mieć wpływ na istnienie obiektu osadzonego). Na poniższym diagramie pokazano, jak metoda Move przenosi zakres tekstu, jednostkę według jednostki, między obiektami osadzonymi i granicami jednostek tekstowych.
Metoda IUIAutomationTextRange::MoveEndpointByUnit przenosi jeden z punktów końcowych do przodu lub do tyłu przez określoną jednostkę tekstową. Na poniższej ilustracji pokazano, jak punkt końcowy przechodzi do przodu.
diagram 
Metoda IUIAutomationTextRange::MoveEndpointByRange umożliwia aplikacji klienckiej ustawienie jednego punktu końcowego zakresu tekstu na tę samą lokalizację co określony punkt końcowy drugiego zakresu tekstu.
Przewijanie zakresu tekstu w widoku
Metoda IUIAutomationTextRange::ScrollIntoView przewija zakres tekstu, aby tekst był widoczny w widoku kontrolki opartej na tekście. Podczas wywoływania ScrollIntoViewklient może określić, czy tekst powinien być wyrównany do górnej lub dolnej części okna widoku.
Pobieranie otaczającego elementu zakresu tekstu
Aplikacja kliencka może użyć metody IUIAutomationTextRange::GetEnclosingElement, aby pobrać IUIAutomation wskaźnik interfejsu najbardziej wewnętrznego elementu, który otacza zakres tekstu. Otaczający element jest zazwyczaj dostawcą tekstu, który dostarcza zakres tekstu. Jeśli jednak dostawca tekstu obsługuje elementy podrzędne, takie jak tabele lub hiperlinki, element otaczający może być elementem potomnym dostawcy tekstu.
Porównywanie i klonowanie zakresów tekstu
Interfejs IUIAutomationTextRange zawiera dwie metody porównywania zakresów tekstu. Metoda IUIAutomationTextRange::Compare porównuje początkowe i końcowe punkty końcowe dwóch zakresów tekstu i zwraca true, jeśli oba punkty końcowe są takie same. Metoda IUIAutomationTextRange::CompareEndpoints porównuje początkowy lub końcowy punkt końcowy dwóch zakresów. Wartość zwracana jest zero, jeśli punkty końcowe są takie same, lub wartość dodatnia lub ujemna, która wskazuje względne pozycje dwóch punktów końcowych.
Aplikacje klienckie mogą używać metody IUIAutomationTextRange::Clone, aby utworzyć dokładną kopię zakresu tekstu. Nowy zakres tekstu można manipulować niezależnie od oryginalnego zakresu tekstu.
Pobieranie adnotacji
Zakres tekstu może zawierać adnotacje, jeśli kontrolka oparta na tekście je obsługuje. Istnieje wiele różnych rodzajów adnotacji. Plik nagłówka UIAutomationClient.h definiuje zestaw nazwanych wartości stałych, które identyfikują typy adnotacji obsługiwane przez automatyzację interfejsu użytkownika. Aby uzyskać więcej informacji, zobacz identyfikatory typów adnotacji .
Niektóre rodzaje adnotacji są reprezentowane przez element automatyzacji, który obsługuje wzorzec kontrolki Annotation (IUIAutomationAnnotationPattern interface). Inne rodzaje adnotacji są widoczne za pośrednictwem wzorca kontrolki TextRange. Na przykład dostawca może uwidocznić prosty wskaźnik błędu pisowni, sprawiając, że metoda IUIAutomationTextRange::GetAttributeValue zwraca atrybut tekstowy AnnotationTypes o wartości AnnotationType_SpellingError, a wartość null dla atrybutu tekstowego AnnotationObjects.
Pobieranie typów adnotacji z zakresu tekstu
Listę typów adnotacji znajdujących się w zakresie tekstu można pobrać przy użyciu metody IUIAutomationTextRange::GetAttributeValue. Podczas wywoływania metody określ identyfikator atrybutu tekstowego UIA_AnnotationTypesAttributeId i wskaźnik do parametru typu VARIANT. Gdy metoda zwraca, parametr VARIANT zawiera listę identyfikatorów typu adnotacji, po jednym dla każdego typu adnotacji w zakresie tekstu. Aby uzyskać więcej informacji, zobacz identyfikatory typów adnotacji .
Pobieranie wszystkich adnotacji z zakresu tekstu
Aby pobrać adnotacje z zakresu tekstu, wywołaj metodę IUIAutomationTextRange::GetAttributeValue, określając identyfikator atrybutu tekstowego UIA_AnnotationObjectsAttributeId i wskaźnik do parametru typu VARIANT. Gdy metoda zwraca, parametr VARIANT zawiera interfejs IUIAutomationElementArray, który reprezentuje tablicę elementów automatyzacji, po jednym dla każdej adnotacji w zakresie tekstu. Właściwość IUIAutomationElementArray::Length wskazuje liczbę elementów w tablicy oraz IUIAutomationElementArray::GetElement metoda pobiera interfejs IUIAutomationElement dla określonego elementu.
Pobieranie informacji o określonej adnotacji
Aby pobrać informacje o konkretnej adnotacji, najpierw pobierz interfejs IUIAutomationElement dla elementu adnotacji zgodnie z opisem w poprzedniej sekcji. Następnie pobierz interfejs IUIAutomationAnnotationPattern dla adnotacji, wywołując metodę IUIAutomationElement::GetCurrentPatternAs z identyfikatorem wzorca sterowania UIA_AnnotationPatternId, identyfikatorem interfejsu IID_IUIAutomationAnnotationPattern oraz adresem zmiennej odbierającej wskaźnik IUIAutomationAnnotation dla adnotacji. Wykonaj zapytanie o właściwości interfejsu IUIAutomationAnnotation, aby pobrać nazwę typu adnotacji i identyfikator typu, nazwę autora adnotacji, datę i godzinę adnotacji oraz interfejs IUIAutomationElement dla elementu, który jest adnotacją.
Pobieranie tekstu docelowego adnotacji
Zazwyczaj adnotacja ma zastosowanie do podzbioru tekstu w zakresie treści. Po pobraniu interfejsu IUIAutomationElement dla adnotacji można przekazać interfejs do metody IUIAutomationTextRange2::RangeFromAnnotation, aby pobrać zakres tekstu zawierający tekst, który jest celem adnotacji.
Pobieranie stylów wizualnych
Dostawca implementuje wzorzec kontrolek Style opisujący element interfejsu użytkownika, który ma określony styl, kolor wypełnienia, wzorzec wypełnienia lub kształt. Jest to szczególnie przydatne podczas opisywania elementów w dokumencie, które często mają takie style. Style takie jak te często zawierają informacje przydatne dla klientów niepełnosprawnych; Na przykład style mogą opisywać określony ciąg jako tytuł dokumentu lub określony obiekt schematu blokowego jako romb lub okrąg.
Możesz użyć metody IUIAutomationTextRange::GetAttributeValue, aby pobrać nazwy i identyfikatory stylów wizualizacji używanych w zakresie tekstu. Użyj atrybutu UIA_StyleNameAttributeId text, aby pobrać nazwy stylów i UIA_StyleIdAttributeId w celu pobrania identyfikatorów stylów.
Kontrolka oparta na tekście, która obsługuje style wizualne, może zaimplementować wzorzec kontroli Style, aby umożliwić klientom dostęp do informacji o stylu wizualizacji używanym przez kontrolkę. Klienci uzyskują dostęp do wzorca kontrolki Style za pośrednictwem interfejsu IUIAutomationStylesPattern. Ten interfejs można pobrać, wywołując metodę IUIAutomationElement::GetCurrentPattern lub GetCurrentPatternAs, określając UIA_StylesPatternId jako identyfikator wzorca kontrolki.
Interfejs IUIAutomationStylesPattern zawiera właściwości i metody, które zawierają następujące informacje o stylu wizualizacji:
- Nazwa stylu wizualnego, na przykład "Normalny" lub "Nagłówek 1".
- Identyfikator stylu wizualizacji. Aby uzyskać więcej informacji, zobacz Identyfikatory stylów.
- Kolor używany do wypełnienia kontrolki opartej na tekście.
- Kolor wzorca używanego do wypełnienia kontrolki opartej na tekście.
- Kształt kontrolki opartej na tekście.
- Właściwości rozszerzone; czyli lista nazw stylów i wartości specyficznych dla kontrolek.
Wywoływanie menu kontekstowych z zakresów tekstu
Począwszy od systemu Windows 8.1, zakresy tekstu mogą obsługiwać interfejs IUIAutomationTextRange2. Ten interfejs obsługuje metodę ShowContextMenu. Tę metodę można wywołać, aby wywołać dowolne menu kontekstowe skojarzone z zakresem tekstu. W tym scenariuszu jest autokorekcja zakresów tekstu lub wybór kandydata do IME. W takich przypadkach zostanie wyświetlone menu kontekstowe, które obsługuje interakcję użytkownika.
Tematy pokrewne
-
Obsługa Automatyzacji Interfejsu Użytkownika dla Zawartości Tekstowej