Cómo Automatización de la interfaz de usuario expone objetos incrustados

En este tema se describe cómo Microsoft Automatización de la interfaz de usuario usa los patrones de control Text y TextRange para exponer objetos incrustados (elementos secundarios o descendientes) en un documento de texto o contenedor.

Para Automatización de la interfaz de usuario, 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 de Microsoft Excel, archivo de Microsoft Windows Media, etc.).

Nota

Esto difiere de la definición OLE del Modelo de objetos componentes (COM) (consulte Objetos incrustados), donde se crea un elemento en una aplicación y se inserta o vincula en otra aplicación. Si el objeto se puede editar en su aplicación original es irrelevante en el contexto de 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 elementos secundarios del contenedor de texto para que se pueda acceder a ellos a través del mismo modelo de objetos que otros controles de Automatización de la interfaz de usuario.

En la tabla siguiente se enumeran ejemplos de elementos contenedor y no contenedor.

Elementos de contenedor

Elementos que no son contenedores

• Calendario
• ComboBox
• DataGrid
• Documento
• Editar
• Grupo
• Encabezado
• HeaderItem
• List
• Menú

• MenuBar
• Panel
• SplitButton
• Pestaña
• Tabla
• Barra de herramientas
• Árbol
• TreeItem
• Periodo

• Vínculo
• Casillas
• Botón

En la imagen siguiente se muestra un contenedor de texto (documento) con una tabla e imagen incrustadas.

La vista de contenido Automatización de la interfaz de usuario del documento anterior se muestra en el diagrama siguiente.

Objetos incrustados "Compatibles" y "No compatibles"

Algunos proveedores de Automatización de la interfaz de usuario usan 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 conocen como objetos incrustados "compatibles". Estos objetos pueden ser objetos TextPattern y, en este caso, sus intervalos de texto son comparables a los intervalos de texto obtenidos de su contenedor. Esto permite a los proveedores exponer información de cliente sobre los objetos TextPattern individuales como si fueran un proveedor de texto grande.

Sin embargo, los proveedores pueden usar 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 conocen como objetos incrustados "no compatibles". Estos tipos de objetos incrustados podrían o no ser objetos basados en TextPattern.

En la tabla siguiente se enumeran algunos ejemplos de objetos incrustados compatibles y no compatibles.

Objetos	Objetos incrustados compatibles	Objetos incrustados no compatibles
Objetos incrustados que no son TextPattern	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 incrustados TextPattern	Control de entrada de tipo "texto" en Microsoft Edge Tabla en un documento de Word	Elemento TextBox de un documento de Microsoft Word

Exponer objetos incrustados

Los patrones de control Text y 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 Automatización de la interfaz de usuario está recuperando el texto para recitar, interpretar o analizar de alguna manera, el intervalo de texto debe comprobarse para casos especiales, como una tabla con contenido textual u otros objetos incrustados. Llame a IUIAutomationTextRange::GetChildren para obtener una interfaz IUIAutomationElement para cada objeto incrustado y, a continuación, llame a IUIAutomationTextPattern::RangeFromChild para obtener un intervalo de texto para cada elemento. Esto se realiza recursivamente hasta que se recupera todo el contenido textual.

Nota:

Un intervalo degenerado (o contraído) es donde el punto de conexión inicial y el extremo final son los mismos. Los intervalos degenerados se suelen usar para indicar la posición del cursor de texto a través de los métodos GetSelection y GetCaretRange de ITextProvider.

En el diagrama siguiente se muestra un flujo de texto con objetos incrustados y sus intervalos de intervalos.

Objetos incrustados y TextUnit

Un objeto ITextProvider se puede recorrer y mediante un TextUnit especificado. Los proveedores que contienen objetos incrustados se pueden recorrer de la misma manera, pero los objetos incrustados afectan al recorrido. Estas son algunas cosas que debe tener en cuenta:

• Cualquier objeto incrustado no compatible se representa mediante el carácter de reemplazo U+FFFC en el almacén de texto del TextPattern del elemento contenedor. También se considera una unidad de caracteres y una unidad de palabras.
• Los objetos incrustados compatibles pueden constar de varios caracteres y palabras.
• El elemento envolvente es el elemento más inferior que abarca todo el intervalo de texto.
• Los elementos secundarios de un intervalo también son elementos secundarios de un elemento contenedor que está incluido parcialmente o completamente dentro del intervalo.
• Idealmente (especialmente en el caso de elementos contenedor como Table) un límite de palabras no va más allá del límite del objeto. En el ejemplo siguiente, la unidad de palabra "Barra" no contiene ninguna posición de texto que esté fuera de la </td> etiqueta (<br \> no forma 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 va más allá de un límite de línea.
• Una excepción a la regla anterior es donde una unidad de texto de Word contiene objetos completos dentro de sí mismo. Por ejemplo, <p>Hello <a href="#">link</a> here.</p>, que incluye contenedores insertados, tiene las palabras "Hello", "link " y "here". Donde "link" tiene un objeto TextPattern como elemento envolvente y un objeto de vínculo como su elemento secundario.
• En el caso de las unidades de caracteres, el objeto es el elemento envolvente (unidades de texto como esta no deben tener elementos secundarios).
• Los objetos de anotación no deben representarse como objeto incrustado. Por ejemplo, la presencia de otros especificadores author en un documento co-autor.
• Los objetos incrustados ocupan al menos una posición del cursor, la anotación es solo metadatos.
• Cada límite de objeto (inicio y fin) se representa mediante un salto de formato en el intervalo de documentos TextPattern.
• Para HTML, cada etiqueta HTML no produce necesariamente un objeto Automatización de la interfaz de usuario. Por ejemplo, el contenido dentro de las etiquetas de énfasis no se debe representar como elemento, sino un flujo de texto en el que UIA_IsItalicAttributeId devuelve TRUE.
• El punto de conexión de inicio es inclusivo y es el punto de conexión preferido mientras que el extremo final es exclusivo. Esto es útil para cuando el intervalo se degenera y los puntos de conexión Inicio y Fin pertenecen a la misma posición para ese intervalo.

Comparación de objetos incrustados

Los objetos TextPattern anidados que están en una relación secundaria similar y que comparten el mismo almacén de texto auxiliar se denominan comparables. En este caso, los intervalos de cualquiera de los objetos TextPattern se pueden comparar mediante ITextRangeProvider::Compare e ITextRangeProvider::CompareEndpoints. Ambos dan como resultado un valor numérico válido que especifica su posición relativa.

Un objeto que no es TextPattern incrustado en un objeto TextPattern es comparable al TextPattern si el objeto tiene un intervalo válido en textPattern (ITextProvider::RangeFromChild) y el contenido detrás del intervalo de texto no está vacío y no es un carácter de reemplazo.

Objetos TextPattern incrustados y Document TextUnit

En el caso de los objetos TextPattern incrustados, la unidad document solo reconoce el contenido incluido en ese elemento.

jerarquía de elementos Word TextPattern

• El elemento document implementa TextPattern y Document devuelve todo el Word intervalo de documentos.
• Las páginas individuales del documento implementan TextPattern y Document devuelven 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 página web y texto en Edge

• El elemento main webpage Pane implementa TextPattern y expone todo el contenido de la página web.
• Los controles de entrada de texto individuales admiten TextPattern, donde un intervalo 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

En esta sección se presentan ejemplos de escenarios comunes que implican objetos incrustados: hipervínculos, imágenes y tablas. En los ejemplos siguientes, la llave izquierda ({) representa el punto de conexión Inicio del intervalo de texto y la llave derecha (}) representa el extremo final.

Ejemplo 1 de HyperLink: intervalo de texto que contiene un hipervínculo de texto incrustado

El siguiente intervalo de texto contiene un hipervínculo de texto incrustado.

{La dirección URL https://www.microsoft.com está incrustada en texto}.

Llamar a los métodos IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren e IUIAutomationTextPattern::RangeFromChild da como resultado los comportamientos descritos en la tabla siguiente.

Método al que se llama	Resultado
IUIAutomationTextRange::GetText	Devuelve la cadena "La dirección URL https://www.microsoft.com está incrustada en texto".
IUIAutomationTextRange::GetEnclosingElement	Devuelve el elemento Automatización de la interfaz de usuario más interno que incluye el intervalo de texto, en este caso, el elemento de automatización que representa el propio proveedor de texto.
IUIAutomationTextRange::GetChildren	Devuelve un elemento Automatización de la interfaz de usuario que representa el control de hipervínculo.
IUIAutomationTextPattern::RangeFromChild, donde el método IUIAutomationTextRange::GetChildren devolvió el elemento Automatización de la interfaz de usuario.	Devuelve el intervalo que representa "https://www.microsoft.com".

Ejemplo 2 de HyperLink: intervalo de texto que abarca parcialmente un hipervínculo de texto incrustado

El siguiente intervalo de texto abarca parcialmente un hipervínculo de texto incrustado.

La dirección URL https://{www} está incrustada en texto.

Llamar a los métodos IUIAutomationTextRange::GetText, GetEnclosingElement y GetChildren da como resultado 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 Automatización de la interfaz de usuario más interno que incluye el intervalo de texto; en este caso, el control de hipervínculo.
IUIAutomationTextRange::GetChildren	Devuelve NULL porque el intervalo de texto no abarca toda la cadena de dirección URL.

Ejemplo 3 de HyperLink: intervalo de texto que abarca parcialmente el contenido de un contenedor de texto

El siguiente intervalo de texto abarca parcialmente 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 dirección URL} https://www.microsoft.com está incrustado en texto.

Llamar a los métodos IUIAutomationTextRange::GetText, GetEnclosingElement y Move da como resultado 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 Automatización de la interfaz de usuario más interno que incluye el intervalo de texto, en este caso, el elemento que representa el propio proveedor de texto.
IUIAutomationTextRange::Move	Mueve el intervalo de texto a "https://" porque el texto del hipervínculo se compone de palabras individuales. En este caso, el hipervínculo no se considera un único objeto. La dirección URL {http} está incrustada en el texto.

Ejemplo de imagen 1: un intervalo de texto que contiene una imagen incrustada

El siguiente intervalo de texto contiene una imagen incrustada de un transfer.

{La está incrustada en texto}.

Llamar a los métodos IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren e IUIAutomationTextPattern::RangeFromChild da como resultado 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". Cualquier texto ALT asociado a la imagen no se incluye en la secuencia de texto.
IUIAutomationTextRange::GetEnclosingElement	Devuelve el elemento Automatización de la interfaz de usuario más interno que incluye el intervalo de texto, en este caso, el elemento que representa el propio proveedor de texto.
IUIAutomationTextRange::GetChildren	Devuelve un elemento Automatización de la interfaz de usuario que representa el control de imagen.
IUIAutomationTextPattern::RangeFromChild donde el método IUIAutomationTextRange::GetChildren devolvió el elemento Automatización de la interfaz de usuario.	Devuelve el intervalo degenerado.

Ejemplo de imagen 2: intervalo de texto que abarca parcialmente el contenido de un contenedor de texto

El siguiente intervalo de texto abarca parcialmente 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á incrustado en texto.

Llamar a los métodos IUIAutomationTextRange::GetText, GetEnclosingElement y Move da como resultado 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 Automatización de la interfaz de usuario más interno que incluye el intervalo de texto, en este caso, el elemento que representa el 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 de la secuencia de texto, la imagen de este ejemplo no afecta a IUIAutomationTextRange::Move o su valor devuelto, en este caso, 2.

Tabla

Ejemplo de tabla 1: obtiene el contenedor de texto del contenido de una celda

En la tabla siguiente se obtiene el contenedor de texto del contenido de una celda.

Celda con imagen	Celda con texto
	x
	Y
	Z

Llamar a los métodos IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild e IUIAutomationTextRange::GetEnclosingElement da como resultado los comportamientos descritos en la tabla siguiente.

Método al que se llama	Resultado
IUIAutomationGridPattern::GetItem con parámetros (0, 0).	Devuelve el elemento Automatización de la interfaz de usuario que representa el contenido de la celda de tabla, en este caso, el elemento es un control de texto.
iuiautomationtextpattern::rangefromchild	devuelve el intervalo de la .
GetEnclosingElement para el objeto devuelto por el método IUIAutomationTextPattern::RangeFromChild anterior.	Devuelve el elemento Automatización de la interfaz de usuario que representa la celda de tabla. En este caso, el elemento es un control de texto que admite el patrón de control TableItem .
IUIAutomationTextRange::GetEnclosingElement para el objeto devuelto por el método GetEnclosingElement anterior.	Devuelve el elemento Automatización de la interfaz de usuario que representa la tabla.
IUIAutomationTextRange::GetEnclosingElement para el objeto devuelto por el método GetEnclosingElement anterior.	Devuelve el elemento Automatización de la interfaz de usuario que representa el propio proveedor de texto.

Ejemplo de tabla 2: obtiene el contenido de texto de una celda

La tabla del ejemplo anterior obtiene el contenido de texto de una celda.

Llamar a los métodos IUIAutomationGridPattern::GetItem e IUIAutomationTextPattern::RangeFromChild da como resultado los comportamientos descritos en la tabla siguiente.

Método al que se llama	Resultado
IUIAutomationGridPattern::GetItem con parámetros (1,1).	Devuelve el elemento Automatización de la interfaz de usuario que representa el contenido de la celda de tabla. En este caso, el elemento es un control de texto.
IUIAutomationTextPattern::RangeFromChild donde el elemento Automatización de la interfaz de usuario es el objeto devuelto por el método IUIAutomationGridPattern::GetItem.	Devuelve "Y".

Al desplazarse por un documento por TextUnit_Line, si el intervalo de texto entra en una tabla incrustada, cada línea de texto de 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 contenido textual