Cómo expone Automatización de la interfaz de usuario los objetos incrustados
Este tema describe cómo Microsoft UI Automation utiliza los patrones de control Text y TextRange para exponer objetos incrustados (elementos hijos/descendientes) en un documento o contenedor de texto.
Para UI Automation, un objeto incrustado es cualquier elemento que tenga límites no textuales, como una imagen, un hipervínculo, una tabla o un tipo de documento (hoja de cálculo Microsoft Excel, archivo Microsoft Windows Media, etc.).
Nota:
Esto difiere de la definición OLE del Modelo de objetos componentes (COM) (consulte objetos integrados), cuando un elemento se crea en una aplicación y se incrusta o enlaza en otra. El hecho de que el objeto pueda editarse en su aplicación original es irrelevante en el contexto de la automatización de la interfaz de usuario.
Objetos incrustados y el árbol de automatización de la interfaz de usuario
Los objetos incrustados se tratan como elementos individuales en la vista de control del árbol de automatización de la interfaz de usuario. Se exponen como hijos del contenedor de texto para que se pueda acceder a ellos a través del mismo modelo de objetos que a otros controles de UI Automation.
La siguiente tabla enumera ejemplos de elementos contenedores y no contenedores.
Elementos de contenedor
Elementos de no contenedor
- Calendario
- Combobox
- DataGrid
- Document
- Editar
- Grupo
- Encabezado
- HeaderItem
- List
- Menu
- MenuBar
- Panel
- SplitButton
- Pestaña
- Tabla
- Barra de herramientas
- Tree
- TreeItem
- Window
- Vínculo
- CheckBoxes
- Botón
La siguiente imagen muestra un contenedor de texto (documento) con una tabla y una imagen incrustadas.
La vista de contenido de UI Automation del documento anterior se muestra en el siguiente diagrama.
"Objetos incrustados "compatibles" y "no compatibles
Algunos proveedores de UI Automation utilizan el mismo almacén de texto para cada objeto TextPattern que contienen. Los objetos respaldados por el mismo almacén de texto que su contenedor se denominan objetos incrustados "compatibles". Estos objetos pueden ser a su vez objetos TextPattern y, en este caso, sus rangos de texto son comparables a los rangos de texto obtenidos de su contenedor. Esto permite a los proveedores exponer la información del cliente sobre los objetos TextPattern individuales como si fueran un único y gran proveedor de texto.
Sin embargo, los proveedores pueden utilizar diferentes almacenes de texto para diferentes objetos TextPattern incrustados dentro de un contenedor TextPattern. Los objetos no respaldados por el almacén de texto del contenedor se denominan objetos incrustados "no compatibles". Estos tipos de objetos incrustados pueden ser o no objetos basados en TextPattern.
La siguiente tabla enumera algunos ejemplos de objetos incrustados compatibles y no compatibles.
| Objetos | Objetos integrados compatibles | Objetos integrados no compatibles |
|---|---|---|
| Objetos integrados no patrón de texto | Botón en Microsoft Edge Tabla de datos en Microsoft Edge |
Botón en RichTextBlock en el marco XAML de Microsoft Imágenes con texto alternativo en Microsoft Edge ListView con ListItems en RichTextBlock en el marco XAML de Microsoft |
| Objetos integrados patrón de texto | Control de entrada de tipo "texto" en Microsoft Edge Tabla en un documento Word |
Elemento TextBox en un documento Microsoft Word |
Exponer Objetos Integrados
El Text and TextRange exponen propiedades y métodos que facilitan la navegación y la consulta de objetos incrustados.
El contenido textual (o texto interno) de un contenedor de texto y un objeto incrustado, como un hipervínculo o una celda de tabla, se expone como una secuencia de texto continua única en las vistas de control y contenido del árbol de Automatización de la interfaz de usuario. Los límites del objeto se ignoran. Si un cliente de UI Automation está recuperando el texto para recitarlo, interpretarlo o analizarlo de alguna manera, el rango de texto debe comprobarse para casos especiales, como una tabla con contenido textual u otros objetos incrustados. Llame IUIAutomationTextRange::GetChildren para obtener un IUIAutomationElement para cada objeto incrustado y, a continuación, llamar a IUIAutomationTextPattern::RangeFromChild para obtener un rango de texto para cada elemento. Esto se realiza recursivamente hasta que se recupera todo el contenido textual.
Nota:
Un rango degenerado (o colapsado) es aquel en el que el punto final inicial y el punto final son iguales. Los rangos degenerados se utilizan a menudo para indicar la posición del cursor de texto a través del ITextProvider GetSelection and GetCaretRange métodos.
El siguiente diagrama muestra un flujo de texto con objetos incrustados y sus rangos de alcance.
Objetos incrustados y TextUnit
Un ITextProvider objeto se puede recorrer y por un TextUnit. Los proveedores que contienen objetos incrustados pueden ser recorridos de la misma manera, pero los objetos incrustados afectan al recorrido. He aquí algunas cosas que hay que tener en cuenta:
- Cualquier objeto incrustado no compatible se representa mediante el carácter de sustitución U+FFFC en el almacén de texto del TextPattern del elemento contenedor. También se considera tanto una unidad de carácter como una unidad de palabra.
- Los objetos incrustados compatibles pueden constar de varios caracteres y palabras.
- El elemento delimitador es el elemento situado más abajo que abarca todo el rango de texto.
- Los elementos hijos de un rango son también elementos hijos de un elemento contenedor que está parcial o totalmente incluido en el rango.
- Lo ideal (especialmente en el caso de elementos contenedores como Table) es que el límite de una palabra no sobrepase el límite del objeto. En el siguiente ejemplo, la unidad de palabra "Bar" no contiene ninguna posición de texto que esté fuera del
</td>etiqueta (<br \>no es parte de la palabra "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/>
- En general,
<br \>se trata como una palabra individual, de modo que no sobrepasa el límite de una línea. - Una excepción a la regla anterior es cuando una unidad de texto Word contiene objetos completos dentro de sí misma. Por ejemplo,
<p>Hello <a href="#">link</a> here.</p>, que incluye contenedores en línea, tiene las palabras "Hola ", "enlace " y "aquí". Donde "link " tiene un objeto TextPattern como elemento delimitador y un objeto link como hijo. - En el caso de las unidades de caracteres, el objeto es el elemento que las contiene (las unidades de texto de este tipo no deben tener hijos).
- Los objetos de anotación no deben representarse como objetos incrustados. Por ejemplo, la presencia de otros especificadores de Autor en un documento de coautoría.
- Los objetos incrustados ocupan al menos una posición del cursor, la anotación son solo metadatos.
- Cada límite de objeto (inicio y fin) se representa mediante un salto de formato en el rango del documento TextPattern.
- Para HTML, cada etiqueta html no da lugar necesariamente a un objeto UI Automation. Por ejemplo, los contenidos de no es necesario representar las etiquetas de énfasis como elementos, sino como un flujo de texto en el que UIA_IsItalicAttributeId devuelve TRUE.
- El punto final Inicio es inclusivo y es el punto final preferido, mientras que el punto final Fin es exclusivo. Esto es útil cuando el rango es degenerado y los puntos finales Inicio y Fin pertenecen a la misma posición para ese rango.
Comparar objetos integrados
Los objetos TextPattern anidados que tienen una relación de hijo similar y comparten el mismo almacén de texto de respaldo se denominan comparables. En este caso, los rangos de cualquiera de los objetos TextPattern pueden compararse utilizando ITextRangeProvider::Compare y ITextRangeProvider::CompareEndpoints. Ambos dan como resultado un valor numérico válido que especifica su posición relativa.
Un objeto no TextPattern incrustado en un objeto TextPattern es comparable al TextPattern si el objeto tiene un rango válido en el TextPattern (ITextProvider::RangeFromChild) y el contenido detrás del rango de texto no está vacío y no es un carácter de sustitución.
Objetos TextPattern incrustados y la TextUnit del documento
Para los objetos TextPattern incrustados, la función Documento solo reconoce el contenido de ese elemento.
Jerarquía de elementos Word TextPattern
- El elemento documento implementa TextPattern y Document devuelve el rango completo del documento Word.
- Las páginas individuales del documento implementan TextPattern y Documento devuelve el contenido de esas páginas individuales (aunque las páginas compartan el mismo almacén de texto con todo el documento TextPattern).
Controles de entrada de texto y páginas web en Edge
- El elemento Pane de la página web principal implementa TextPattern y expone todo el contenido de la página web.
- Los controles de entrada de texto individuales admiten TextPattern, donde un rango de documentos representa el texto contenido en cada campo de entrada (aunque compartan el mismo almacén de texto con toda la página web).
Escenarios comunes
Esta sección presenta ejemplos de escenarios comunes que involucran objetos incrustados: hipervínculos, imágenes y tablas. En los siguientes ejemplos, la llave izquierda ({) representa el punto final Inicio del rango de texto, y la llave derecha (}) representa el punto final Fin.
Hiperenlace Ejemplo 1: Un rango de texto que contiene un hiperenlace de texto incrustado
El siguiente rango de texto contiene un hipervínculo de texto incrustado.
(La URL https://www.microsoft.com está incrustada en texto}.
Llamar el IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren, y IUIAutomationTextPattern::RangeFromChild métodos da lugar a los comportamientos descritos en la tabla siguiente.
| Método al que se llama | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Devuelve la cadena "La URL https://www.microsoft.com está incrustada en texto". |
| IUIAutomationTextRange::GetEnclosingElement | Devuelve el elemento de automatización de IU más interno que encierra el rango de texto, en este caso, el elemento de automatización que representa al propio proveedor de texto. |
| IUIAutomationTextRange::GetChildren | Devuelve un elemento de UI Automation que representa el control de hipervínculo. |
| IUIAutomationTextPattern::RangeFromChild, donde el elemento UI Automation fue devuelto por el anterior IUIAutomationTextRange::GetChildren método. | Devuelve el rango que representa "https://www.microsoft.com". |
Hiperenlace Ejemplo 2: Un rango de texto parcialmente abarca un hiperenlace de texto incrustado
El siguiente rango de texto parcialmente abarca un hipervínculo de texto incrustado.
(La URL https://{www} está incrustada en texto.
Llamar el IUIAutomationTextRange::GetText, GetEnclosingElement, y GetChildren método da lugar a los comportamientos descritos en la tabla siguiente.
| Método al que se llama | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Devuelve la cadena "www". |
| IUIAutomationTextRange::GetEnclosingElement | Devuelve el elemento de Automatización de IU más interno que encierra el rango de texto; en este caso, el control de hipervínculo. |
| IUIAutomationTextRange::GetChildren | Devuelve NULO porque el rango de texto no abarca toda la cadena URL. |
Hiperenlace Ejemplo 3: Un rango de texto parcialmente abarca el contenido de un contenedor de texto
El siguiente rango de texto parcialmente abarca el contenido de un contenedor de texto. El contenedor de texto incluye un hipervínculo de texto incrustado que no forma parte del intervalo de texto.
{La URL} https://www.microsoft.com está incrustada en texto.
Llamar el IUIAutomationTextRange::GetText, GetEnclosingElement, y Mover método da lugar a los comportamientos descritos en la tabla siguiente.
| Método al que se llama | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Devuelve la cadena "La dirección URL". |
| IUIAutomationTextRange::GetEnclosingElement | Devuelve el elemento de automatización de IU más interno que encierra el rango de texto, en este caso, el elemento que representa al propio proveedor de texto. |
| IUIAutomationTextRange::Move | Mueve el span del rango de texto a "https://" porque el texto del hipervínculo está formado por palabras individuales. En este caso, el hipervínculo no se considera un único objeto. (La URL {http} está incrustada en texto. |
Imagen Ejemplo 1: Un rango de texto que contiene una imagen
El siguiente rango de texto contiene un imagen de una lanzadera.
{La imagen 
está insertada en el texto}.
Llamar el IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren, y IUIAutomationTextPattern::RangeFromChild métodos da lugar a los comportamientos descritos en la tabla siguiente.
| Método al que se llama | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Devuelve la cadena "La imagen está incrustada en texto". El texto ALT asociado a la imagen no se incluye en el flujo de texto. |
| IUIAutomationTextRange::GetEnclosingElement | Devuelve el elemento de automatización de IU más interno que encierra el rango de texto, en este caso, el elemento que representa al propio proveedor de texto. |
| IUIAutomationTextRange::GetChildren | Devuelve un elemento de UI Automation que representa el control de imagen. |
| IUIAutomationTextPattern::RangeFromChild donde el elemento UI Automation fue devuelto por el anterior IUIAutomationTextRange::GetChildren método. | Devuelve el rango degenerado. |
Imagen Ejemplo 2: Un rango de texto parcialmente abarca el contenido de un contenedor de texto
El siguiente rango de texto parcialmente abarca el contenido de un contenedor de texto. El contenedor de texto incluye una imagen incrustada que no forma parte del intervalo de texto.
{La imagen} está insertada en el texto.
Llamar el IUIAutomationTextRange::GetText, GetEnclosingElement, y Mover método da lugar a los comportamientos descritos en la tabla siguiente.
| Método al que se llama | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Devuelve la cadena "La imagen". |
| IUIAutomationTextRange::GetEnclosingElement | Devuelve el elemento de automatización de IU más interno que encierra el rango de texto, en este caso, el elemento que representa al propio proveedor de texto. |
| IUIAutomationTextRange::Move con parámetros de (TextUnit_Word, 2). | Mueve el intervalo de texto a "está". Dado que solo los objetos incrustados basados en texto se consideran parte del flujo de texto, la imagen de este ejemplo no afecta a IUIAutomationTextRange::Move o su valor de retorno, en este caso, 2. |
Tabla
Tabla Ejemplo 1: Obtiene el contenedor de texto a partir del contenido de una celda
La siguiente tabla obtiene el contenedor de texto a partir del contenido de una celda.
| Celda con imagen | Celda con texto |
|---|---|
|
X |
 |
Y |
 |
Z |
Llamar el IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild, y IUIAutomationTextRange::GetEnclosingElement método da lugar a los comportamientos descritos en la tabla siguiente.
| Método al que se llama | Resultado |
|---|---|
| IUIAutomationGridPattern::GetItem con parámetros (0, 0). | Devuelve el elemento de UI Automation que representa el contenido de la celda de la tabla, en este caso, el elemento es un control de texto. |
| iuiautomationtextpattern::rangefromchild | devuelve el rango de la imagen . |
| IUIAutomationTextPattern::RangeFromChild donde el elemento UI Automation fue devuelto por el anterior IUIAutomationTextPattern::RangeFromChild método. | Devuelve el elemento de UI Automation que representa la celda de la tabla. En este caso, el elemento es un control de texto que admite la función TableItem patrón de control. |
| IUIAutomationTextRange::GetEnclosingElement para el objeto devuelto por el GetEnclosingElement método. | Devuelve el elemento de UI Automation que representa la tabla. |
| IUIAutomationTextRange::GetEnclosingElement para el objeto devuelto por el GetEnclosingElement método. | Devuelve el elemento de UI Automation que representa al propio proveedor de texto. |
Tabla Ejemplo 2: Obtiene el texto de una celda
La tabla del ejemplo anterior obtiene el contenido de texto de una celda.
Llamar el IUIAutomationGridPattern::GetItem y IUIAutomationTextPattern::RangeFromChild método da lugar a los comportamientos descritos en la tabla siguiente.
| Método al que se llama | Resultado |
|---|---|
| IUIAutomationGridPattern::GetItem con parámetros (1,1). | Devuelve el elemento de UI Automation que representa el contenido de la celda de la tabla. En este caso, el elemento es un control de texto. |
| IUIAutomationTextPattern::RangeFromChild donde el elemento UI Automation el objeto devuelto por el anterior IUIAutomationGridPattern::GetItem método. | Devuelve "Y". |
Al desplazarse por un documento mediante TextUnit_Line, si el rango de texto entra en una tabla incrustada, cada línea de texto en una celda debe tratarse como una línea.