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.).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Temas relacionados

Conceptual

• Acerca de los patrones de control Text y TextRange
• Atributos de texto de Automatización de la interfaz de usuario
• Información general acerca de los patrones de control de UI Automation
• Compatibilidad de automatización de la interfaz de usuario con el contenido textual