Общие сведения об объектах TextPattern и Embedded

Статья
08/11/2011

Примечание
Эта документация предназначена для разработчиков на платформе .NET Framework, которым требуется использовать управляемые классы UI Automation, определенные в пространстве имен System.Windows.Automation. Последние сведения о UI Automation см. на веб-странице Windows Automation API: UI Automation.

Эта документация предназначена для разработчиков на платформе .NET Framework, которым требуется использовать управляемые классы UI Automation, определенные в пространстве имен System.Windows.Automation. Последние сведения о UI Automation см. на веб-странице Windows Automation API: UI Automation.

В данном обзоре описано, как Microsoft UI Automation представляет внедренные объекты или дочерние элементы в текстовом документе или контейнере.

В UI Automation внедренным объектом является любой элемент, имеющий нетекстовые границы, например изображение, гиперссылка, таблица или документ типа электронной таблицы Microsoft Excel или файла Microsoft Windows Media. Это отличается от стандартного определения, где элемент создается в одном приложении и внедряется в другой (или связывается с ним). Возможность редактирования объекта в его исходном приложении несущественна в контексте UI Automation.

В этом разделе содержатся следующие подразделы.

Внедренные объекты и дерево модели автоматизации пользовательского интерфейса
Представление внедренных объектов с помощью объектов классов TextPattern и TextPatternRange
Общие сценарии
Связанные разделы

Внедренные объекты и дерево модели автоматизации пользовательского интерфейса

Внедренные объекты рассматриваются как отдельные элементы в представлении элемента управления дерева UI Automation. Они представляются как дочерние элементы текстового контейнера, поэтому к ним можно получать доступ, используя ту же модель, что и для других элементов управления в UI Automation.

Пример контейнера текста с внедренными объектами "Таблица", "Изображение" и "Гиперссылка"

Вставленная таблица с изображением в текстовом контейнере

Пример представления содержимого для части предыдущего контейнера текста

Просмотр содержимого предыдущего примера

Представление внедренных объектов с помощью объектов классов TextPattern и TextPatternRange

Используемые в связке, класс TextPattern шаблона элемента управления и класс TextPatternRange предоставляют методы и свойства, упрощающие навигацию и запросы к внедренным объектам.

Текстовое содержимое (или внутренний текст) контейнера текста и внедренного объекта, например гиперссылки или ячейки таблицы, представляется как один непрерывный текстовый поток и в представлении элемента управления, и в представлении содержимого дерева UI Automation; границы объекта игнорируются. Если клиент автоматизации пользовательского интерфейса извлекает текст с целью вывода, интерпретации или какого-либо анализа, текстовый диапазон должен проверяться на предмет особых случаев, например наличия таблицы с текстовым содержимым или других внедренных объектов. Это можно реализовать путем вызова метода GetChildren для получения объекта AutomationElement для каждого внедренного объекта и последующего вызова метода RangeFromChild для получения текстового диапазона для каждого элемента. Это выполняется рекурсивно до тех пор, пока не будет получено все текстовое содержимое.

Пример текстового потока с внедренными объектами и границами их диапазонов

Текст, разделенный вставленными объектами.

Для успешного выполнения метода Move при необходимости прохода по содержимому текстового диапазона за сценой выполняется ряд шагов.

Диапазон текста нормализуется, т.е. сокращается до вырожденного диапазона в конечной точке Start, что делает конечную точку End излишней. Данное действие необходимо для устранения неоднозначности в случаях, когда границы текстового диапазона не совпадают с границами объекта TextUnit. Например,"{U}RL", где символами "{" и "}" обозначены конечные точки текстового диапазона.
Результирующий диапазон перемещается назад в свойство DocumentRange в начало запрашиваемой границы TextUnit.
Диапазон перемещается в вперед или назад значения DocumentRange на требуемое количество запрошенных единиц TextUnit к границе единицы.
Диапазон затем расширяется из состояния вырожденного диапазона путем перемещения конечной точки End на границу одной запрошенной единицы TextUnit.

Примеры размещения текстового диапазона для методов Move() и ExpandToEnclosingUnit()

Настройка диапазона при помощи Move & ExpandToEnclosingUnit

Общие сценарии

В следующих разделах представлены примеры наиболее распространенных скриптов, использующих внедренные объекты.

Легенда для приведенных примеров:

{ = Start

} = End

Гиперссылка

Пример 1. Диапазон текста, содержащий внедренную текстовую гиперссылку

{URL-адрес , внедренный в текст}.

Вызываемый метод	Результат
GetText	Возвращает строку "URL-адрес https://www.microsoft.com внедренный в текст".
GetEnclosingElement	Возвращает внутренний объект AutomationElement, который включает диапазон текста; в данном случае это объект AutomationElement, представляющий собой самого поставщика текста.
GetChildren	Возвращает AutomationElement, представляющий элемент управления "Гиперссылка".
RangeFromChild, где объект AutomationElement является объектом, возвращаемым предыдущим методом GetChildren.	Возвращает диапазон, представляющий "http://www.microsoft.com".

Пример 2. Диапазон текста, частично занимающий внедренную текстовую гиперссылку

URL-адрес http://{} внедряется в текст.

Вызываемый метод	Результат
GetText	Возвращает строку "www".
GetEnclosingElement	Возвращает внутренний объект AutomationElement, который включает диапазон текста; в данном случае это элемент управления "Гиперссылка".
GetChildren	Возвращает значение null, поскольку диапазон текста не занимает всю строку URL-адреса.

Пример 3. Диапазон текста, частично занимающий содержимое контейнера текста. Контейнер текста имеет внедренную текстовую гиперссылку, не являющуюся частью диапазона текста.

{URL} , внедренный в текст.

Вызываемый метод	Результат
GetText	Возвращает строку "URL".
GetEnclosingElement	Возвращает внутренний объект AutomationElement, который включает диапазон текста; в данном случае это объект AutomationElement, представляющий собой самого поставщика текста.
Move с параметрами (TextUnit.Word, 1).	Перемещает занимаемый диапазон текста на "http", поскольку текст гиперссылки состоит из отдельных слов. В этом случае гиперссылка не рассматривается как один объект. URL-адрес {} внедряется в текст.

GetText

Возвращает строку "URL".

GetEnclosingElement

Возвращает внутренний объект AutomationElement, который включает диапазон текста; в данном случае это объект AutomationElement, представляющий собой самого поставщика текста.

Move с параметрами (TextUnit.Word, 1).

Перемещает занимаемый диапазон текста на "http", поскольку текст гиперссылки состоит из отдельных слов. В этом случае гиперссылка не рассматривается как один объект.

URL-адрес {} внедряется в текст.

Изображение

Пример 1. Диапазон текста, содержащий внедренное изображение

{Изображение Пример вставленного изображения , внедренное в текст}.

Вызываемый метод	Результат
GetText	Возвращает строку "The is embedded in text". Любой ALT текст, связанный с изображением, не может быть включен в текстовый поток.
GetEnclosingElement	Возвращает внутренний объект AutomationElement, который включает диапазон текста; в данном случае это AutomationElement, представляющий собой самого поставщика текста.
GetChildren	Возвращает AutomationElement, представляющий элемент управления изображение.
RangeFromChild, где объект AutomationElement является объектом, возвращаемым предыдущим методом GetChildren.	Возвращает вырожденный диапазон, представляющий "".

Пример 2. Диапазон текста, частично занимающий содержимое контейнера текста. Контейнер текста имеет внедренное изображение, не являющееся частью диапазона текста.

{В текст внедрено изображение Пример вставленного изображения }.

Вызываемый метод	Результат
GetText	Возвращает строку "The image".
GetEnclosingElement	Возвращает внутренний объект AutomationElement, который включает диапазон текста; в данном случае это объект AutomationElement, представляющий собой самого поставщика текста.
Move с параметрами (TextUnit.Word, 1).	Перемещает занимаемый диапазон текста на указанное значение. Поскольку только основанные на тексте внедренные объекты считаются частью текстового потока, изображение в этом примере не влияет на метод "Move" или его возвращаемое значение (1 в данном случае).

Таблица

Таблица, используемая для примеров

Ячейка с изображением	Ячейка с текстом
	X
	Y
Изображение для Z	Z

Пример вставленного изображения

Пример внедренного изображения 2

Пример внедренного изображения 3

Изображение для Z

Пример 1. Получение контейнера текста из содержимого ячейки.

Вызываемый метод	Результат
GetItem с параметрами (0,0)	Возвращает объект AutomationElement, представляющий содержимое ячейки таблицы. В данном случае элементом является текстовый элемент управления.
RangeFromChild, где объект AutomationElement является объектом, возвращаемым предыдущим методом GetItem.	Возвращает диапазон, который занимает изображение .
GetEnclosingElement для объекта, возвращаемого предыдущим методом RangeFromChild.	Возвращает объект AutomationElement, представляющий ячейку таблицы. В данном случае элемент — это элемент управления текстом, который поддерживает TableItemPattern.
GetEnclosingElement для объекта, возвращаемого предыдущим методом GetEnclosingElement.	Возвращает AutomationElement, представляющий таблицу.
GetEnclosingElement для объекта, возвращаемого предыдущим методом GetEnclosingElement.	Возвращает AutomationElement, представляющий самого поставщика текста.

Пример 2. Загрузка текстового содержимого ячейки.

Вызываемый метод	Результат
GetItem с параметрами (1,1).	Возвращает объект AutomationElement, представляющий содержимое ячейки таблицы. В данном случае элементом является текстовый элемент управления.
RangeFromChild, где объект AutomationElement является объектом, возвращаемым предыдущим методом GetItem.	Возвращает "Y".