Как UI Automation обнаруживает внедренные объекты
В этом разделе описывается, как Microsoft использует шаблоны управления Text и TextRange для предоставления внедренных объектов (дочерних или потомков) в текстовом документе или контейнере.
Для модель автоматизации пользовательского интерфейса внедренный объект — это любой элемент, имеющий нетекстовые границы, такие как изображение, гиперссылка, таблица или тип документа (электронная таблица Microsoft Excel, файл Microsoft Windows Media и т. д.).
Примечание.
Это отличается от определения OLE компонентной объектной модели (COM) (см . внедренные объекты), где элемент создается в одном приложении и внедрен или связан в другом приложении. Может ли объект изменяться в исходном приложении, не имеет значения в контексте автоматизации пользовательского интерфейса.
Внедренные объекты и дерево модели автоматизации пользовательского интерфейса
Внедренные объекты рассматриваются как отдельные элементы в представлении управления в дереве автоматизации пользовательского интерфейса. Они предоставляются как дочерние элементы текстового контейнера, чтобы их можно было получить через ту же объектную модель, как и другие элементы управления в автоматизации пользовательского интерфейса (UI Automation).
В следующей таблице перечислены примеры элементов контейнера и неконтейнеров.
Элементы контейнера
Неконтейнерные элементы
- Календарь
- Combobox
- DataGrid
- Документ
- Изменить
- Группа
- Заголовок
- ЭлементЗаголовка
- Список
- Меню
- Панель меню
- панель
- Кнопка с разделением
- Вкладка
- Таблица
- Панель инструментов
- дерево
- TreeItem
- Окно
- Ссылка
- CheckBoxes
- Кнопка
На следующем рисунке показан текстовый контейнер (документ) со встроенной таблицей и изображением.
Представление содержимого автоматизации пользовательского интерфейса для предыдущего документа показано на следующей схеме.
Совместимые и несовместимые внедренные объекты
Некоторые поставщики автоматизации пользовательского интерфейса используют то же текстовое хранилище для каждого объекта TextPattern, который они содержат. Объекты, поддерживаемые тем же текстовым хранилищем, что и их контейнер, называются "совместимыми" внедренными объектами. Эти объекты могут быть объектами TextPattern и, в данном случае, их текстовые диапазоны сравнимы с текстовыми диапазонами, полученными из контейнера. Это позволяет поставщикам предоставлять клиентские сведения об отдельных объектах TextPattern, как если бы они были одним, большим текстовым поставщиком.
Однако поставщики могут использовать различные текстовые хранилища для различных объектов TextPattern, внедренных в контейнер TextPattern. Объекты, не поддерживаемые текстовым хранилищем контейнера, называются "не совместимыми" внедренными объектами. Эти типы внедренных объектов могут быть или не могут быть объектами на основе TextPattern.
В следующей таблице перечислены некоторые примеры совместимых и несовместимых внедренных объектов.
| Объект | Совместимые внедренные объекты | Не совместимые внедренные объекты |
|---|---|---|
| Внедренные объекты, не соответствующие TextPattern | Кнопка в Microsoft Edge Таблица данных в Microsoft Edge |
Кнопка в RichTextBlock в платформе XAML Майкрософт Изображения с альтернативным текстом в Microsoft Edge ListView и ListItems в RichTextBlock в платформе XAML от компании Майкрософт |
| Внедренные объекты TextPattern | Элемент управления ввода типа "text" в Microsoft Edge Таблица в документе Word |
Элемент TextBox в документе Microsoft Word |
Раскрытие внедренных объектов
Шаблоны элементов управления Text и TextRange предоставляют свойства и методы, упрощающие навигацию и запросы внедренных объектов.
Текстовое содержимое (или внутренний текст) текстового контейнера и внедренного объекта, например гиперссылки или ячейки таблицы, предоставляется как один непрерывный текстовый поток как в представлении управления, так и в содержимом дерева автоматизации пользовательского интерфейса. Границы объектов игнорируются. Если клиент UI Automation извлекает текст для чтения, интерпретации или анализа тем или иным образом, диапазон текста должен быть проверен на наличие особых случаев, таких как таблицы с текстовым содержимым или других встроенных объектов. Вызовите IUIAutomationTextRange::GetChildren, чтобы получить интерфейс IUIAutomationElement для каждого внедренного объекта, а затем вызовите IUIAutomationTextPattern::RangeFromChild, чтобы получить текстовый диапазон для каждого элемента. Это выполняется рекурсивно, пока не будет получено все текстовое содержимое.
Примечание.
Для дегенерированного (или свернутого) диапазона характерно состояние, когда начальная и конечная точки совпадают. Вырожденные диапазоны часто используются для указания положения текстового курсора с помощью методов GetSelection и GetCaretRange.
На следующей схеме показан текстовый поток со встроенными объектами и их диапазонами.
Внедренные объекты и TextUnit
Объект ITextProvider можно обойти с помощью указанного TextUnit. Поставщики, содержащие внедренные объекты, могут перемещаться точно так же, однако внедренные объекты влияют на обход. Ниже приведены некоторые моменты, которые следует учитывать:
- Любой не совместимый внедренный объект представлен символом замены U+FFFC в текстовом хранилище элемента контейнера TextPattern. Он также считается как единицей символа, так и единицей слова.
- Совместимые внедренные объекты могут состоять из нескольких символов и слов.
- Ограничивающий элемент — это нижний элемент, охватывающий весь текстовый диапазон.
- Дочерние элементы диапазона также становятся дочерними элементами элемента контейнера, находящегося частично или полностью в пределах диапазона.
- В идеале (особенно в случае элементов контейнера, таких как Таблица), граница слова не выходит за пределы границы объекта. В следующем примере блок слова "Панель" не содержит текстовой позиции, которая находится за пределами
</td>тега (<br \>не является частью слова "Панель").
<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 как включающий элемент и объект link в качестве дочернего объекта. - В случае символьных единиц объект является обрамляющим элементом (такие текстовые единицы не должны иметь дочерних элементов).
- Объекты аннотации не должны представляться как встраиваемые объекты. Например, наличие других указателей авторов в совместно написанном документе.
- Внедренные объекты занимают по крайней мере одну позицию курсора, заметка — это только метаданные.
- Каждая граница объекта (начало и конец) представлена разрывом формата в диапазоне документов TextPattern.
- Для HTML каждый HTML-тег не обязательно приводит к объекту модели автоматизации пользовательского интерфейса. Например, содержимое в тегах выделения должно быть представлено не как элемент, а как текстовый поток, в котором UIA_IsItalicAttributeId возвращает TRUE.
- Начальная точка является инклюзивной и предпочтительной, в то время как конечная точка является эксклюзивной. Это полезно, если диапазон дегенерируется, а конечные точки start и end принадлежат к той же позиции для этого диапазона.
Сравнение внедренных объектов
Вложенные объекты TextPattern, которые находятся в аналогичной дочерней связи и совместно используют то же резервное текстовое хранилище, называются сопоставимыми. В этом случае диапазоны от любого из объектов TextPattern можно сравнить с помощью ITextRangeProvider::Compare и ITextRangeProvider::CompareEndpoints. Оба результата имеют допустимое числовое значение, указывающее их относительную позицию.
Объект, не являющийся TextPattern, встроенный в объект TextPattern, сравнивается с TextPattern, если объект имеет допустимый диапазон в TextPattern (ITextProvider::RangeFromChild), а содержимое, лежащее в диапазоне текста, не является пустым и не является символом замены.
Внедренные объекты TextPattern и текстовые единицы документа
Для внедренных объектов TextPattern единица Document распознает только содержимое, содержащееся в этом элементе.
Иерархия элементов Word TextPattern
- Элемент документа реализует TextPattern и Document возвращает весь диапазон документов Word.
- Отдельные страницы документа реализуют TextPattern, а Document возвращает содержимое этих страниц (несмотря на то, что страницы используют одно и то же текстовое хранилище вместе с полным TextPattern документа).
Элементы управления вводом веб-страниц и текста в Edge
- Основной элемент панели веб-страницы реализует TextPattern и открывает доступ ко всему содержимому веб-страницы.
- Отдельные элементы управления вводом текста поддерживают TextPattern, где диапазон документов представляет текст, содержащийся в каждом поле ввода (даже если они используют одно и то же текстовое хранилище со всей веб-страницей).
Распространенные сценарии
В этом разделе представлены примеры распространенных сценариев, которые включают внедренные объекты: гиперссылки, изображения и таблицы. В следующих примерах левая скобка ({) представляет конечную точку начального диапазона текста, а правая скобка (}) представляет конечную точку end.
Пример HyperLink 1. Текстовый диапазон, содержащий внедренную текстовую гиперссылку
Следующий текстовый диапазон содержит внедренную текстовую гиперссылку.
{URL-адрес https://www.microsoft.com внедрен в текст}.
Вызов методов IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren и IUIAutomationTextPattern::RangeFromChild приводит к поведению, описанному в следующей таблице.
| Вызываемый метод | Результат |
|---|---|
| IUIAutomationTextRange::GetText | Возвращает строку "URL-адрес https://www.microsoft.com внедрен в текст". |
| IUIAutomationTextRange::GetEnclosingElement | Возвращает внутренний элемент UI Automation, который заключает текстовый диапазон, в данном случае элемент автоматизации, представляющий текстового провайдера. |
| IUIAutomationTextRange::GetChildren | Возвращает элемент автоматизации пользовательского интерфейса (UI Automation), представляющий элемент управления контроль гиперссылкой. |
| IUIAutomationTextPattern::RangeFromChild, где элемент пользовательского интерфейса в автоматизации был возвращен предыдущей методом IUIAutomationTextRange::GetChildren. | Возвращает диапазон, представляющий "https://www.microsoft.com". |
Пример HyperLink 2: текстовый диапазон, частично охватывающий внедренную текстовую гиперссылку
Следующий текстовый диапазон частично охватывает внедренную текстовую гиперссылку.
URL-адрес https://{www} внедрен в текст.
Вызов методов IUIAutomationTextRange::GetText, GetEnclosingElement и GetChildren приводит к поведению, описанным в следующей таблице.
| Вызываемый метод | Результат |
|---|---|
| IUIAutomationTextRange::GetText | Возвращает строку "www". |
| IUIAutomationTextRange::GetEnclosingElement | Возвращает наиболее внутренний элемент модели автоматизации пользовательского интерфейса, который включает текстовый диапазон; в данном случае элемент гиперссылки. |
| IUIAutomationTextRange::GetChildren | Возвращает значение NULL , так как текстовый диапазон не охватывает всю строку URL-адреса. |
Пример HyperLink 3. Диапазон текста, частично охватывающий содержимое текстового контейнера
Следующий диапазон текста частично охватывает содержимое текстового контейнера. В текстовом контейнере есть встроенная текстовая гиперссылка, которая не входит в текстовый диапазон.
{URL-адрес} https://www.microsoft.com внедрен в текст.
Вызов методов IUIAutomationTextRange::GetText, GetEnclosingElement и Move приводит к поведению, описанным в следующей таблице.
| Вызываемый метод | Результат |
|---|---|
| IUIAutomationTextRange::GetText | Возвращает строку "URL-адрес". |
| IUIAutomationTextRange::GetEnclosingElement | Возвращает самый внутренний элемент автоматизации пользовательского интерфейса, который заключает текстовый диапазон, в данном случае это элемент, представляющий поставщика текста. |
| IUIAutomationTextRange::Move | Перемещает диапазон текста на "https://", так как текст гиперссылки состоит из отдельных слов. В этом случае гиперссылка не рассматривается как один объект. URL-адрес {http} внедрен в текст. |
Пример изображения 1. Текстовый диапазон, содержащий внедренное изображение
Следующий текстовый фрагмент содержит встроенное изображение шаттла.
{Изображение 
внедрено в текст}.
Вызов методов IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren и IUIAutomationTextPattern::RangeFromChild приводит к поведению, описанному в следующей таблице.
| Вызываемый метод | Результат |
|---|---|
| IUIAutomationTextRange::GetText | Возвращает строку "Изображение внедрено в текст". Любой альтернативный текст, связанный с изображением, не включается в поток текста. |
| IUIAutomationTextRange::GetEnclosingElement | Возвращает внутренний элемент автоматизации пользовательского интерфейса, который охватывает текстовый диапазон, в данном случае элемент, представляющий самого поставщика текста. |
| IUIAutomationTextRange::GetChildren | Возвращает элемент автоматизации пользовательского интерфейса, представляющий элемент управления изображением. |
| IUIAutomationTextPattern::RangeFromChild, где элемент автоматизации пользовательского интерфейса был возвращен предыдущим методом IUIAutomationTextRange::GetChildren. | Возвращает вырожденный диапазон. |
Пример изображения 2. Текстовый диапазон, частично охватывающий содержимое текстового контейнера
Следующий диапазон текста частично охватывает содержимое текстового контейнера. В текстовом контейнере есть внедренное изображение, которое не входит в текстовый диапазон.
{Изображение} внедрено в текст.
Вызов методов IUIAutomationTextRange::GetText, GetEnclosingElement и Move приводит к поведению, описанным в следующей таблице.
| Вызываемый метод | Результат |
|---|---|
| IUIAutomationTextRange::GetText | Возвращает строку "Изображение". |
| IUIAutomationTextRange::GetEnclosingElement | Определяет самый внутренний элемент автоматизации пользовательского интерфейса, который включает текстовый диапазон, в данном случае элемент, представляющий самого поставщика текста. |
| IUIAutomationTextRange::Move с параметрами (TextUnit_Word, 2). | Перемещает диапазон охвата текста к "is ". Так как только текстовые внедренные объекты считаются частью текстового потока, изображение в этом примере не влияет на IUIAutomationTextRange::Move или его возвращаемое значение, в данном случае 2. |
Таблица
Пример таблицы 1. Получение текстового контейнера из содержимого ячейки
В следующей таблице текстовый контейнер извлекается из содержимого ячейки.
| Ячейка с изображением | Ячейка с текстом |
|---|---|
|
|
X |
|
Y |
|
Z |
Вызов методов IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild, и IUIAutomationTextRange::GetEnclosingElement приводит к поведению, описанному в следующей таблице.
| Вызываемый метод | Результат |
|---|---|
| IUIAutomationGridPattern::GetItem с параметрами (0, 0). | Возвращает элемент автоматизации пользовательского интерфейса, представляющий содержимое ячейки таблицы, в данном случае элемент является текстовым элементом управления. |
| iuiautomationtextpattern::rangefromchild | возвращает диапазон изображения . |
| GetEnclosingElement для объекта, возвращаемого предыдущим методом IUIAutomationTextPattern::RangeFromChild. | Возвращает элемент автоматизации пользовательского интерфейса, представляющий ячейку таблицы. В этом случае элемент является текстовым элементом управления, поддерживающим шаблон элемента управления TableItem . |
| IUIAutomationTextRange::GetEnclosingElement для объекта, возвращаемого предыдущим методом GetEnclosingElement. | Возвращает элемент автоматизации пользовательского интерфейса, представляющий таблицу. |
| IUIAutomationTextRange::GetEnclosingElement для объекта, возвращаемого предыдущим методом GetEnclosingElement. | Возвращает элемент автоматизации пользовательского интерфейса, представляющий самого поставщика текста. |
Пример таблицы 2. Возвращает текстовое содержимое ячейки
Таблица в предыдущем примере извлекает содержимое текста ячейки.
Вызов методов IUIAutomationGridPattern::GetItem и IUIAutomationTextPattern::RangeFromChild приводит к поведению, описанным в следующей таблице.
| Вызываемый метод | Результат |
|---|---|
| IUIAutomationGridPattern::GetItem с параметрами (1,1). | Возвращает элемент автоматизации пользовательского интерфейса, представляющий содержимое ячейки таблицы. В этом случае элемент является текстовым элементом управления. |
| IUIAutomationTextPattern::RangeFromChild, где элемент автоматизации пользовательского интерфейса представляет собой объект, возвращаемый предыдущим методом IUIAutomationGridPattern::GetItem. | Возвращает "Y". |
При перемещении по документу с помощью TextUnit_Line, если текстовый диапазон входит во внедренную таблицу, каждая строка текста в ячейке должна обрабатываться как строка.