Come Automazione interfaccia utente espone oggetti incorporati

Questo argomento descrive come Microsoft Automazione interfaccia utente usa i modelli di controllo Text e TextRange per esporre oggetti incorporati (elementi figlio/discendenti) in un documento o un contenitore di testo.

Per Automazione interfaccia utente, un oggetto incorporato è qualsiasi elemento con limiti non testuali, ad esempio un'immagine, un collegamento ipertestuale, una tabella o un tipo di documento (foglio di calcolo di Microsoft Excel, file Microsoft Windows Media e così via).

Nota

Ciò è diverso dalla definizione OLE (COM) Del modello a oggetti componente (vedere Oggetti incorporati), in cui viene creato un elemento in un'applicazione e incorporato o collegato in un'altra applicazione. Se l'oggetto può essere modificato nell'applicazione originale è irrilevante nel contesto di Automazione interfaccia utente.

Oggetti incorporati e albero di automazione interfaccia utente

Gli oggetti incorporati vengono considerati come singoli elementi nella visualizzazione controllo dell'albero Automazione interfaccia utente. Vengono esposti come elementi figlio del contenitore di testo in modo che possano essere accessibili tramite lo stesso modello a oggetti di altri controlli in Automazione interfaccia utente.

Nella tabella seguente sono elencati esempi di elementi contenitore e non contenitore.

Elementi contenitore

Elementi non contenitore

• Calendario
• Combobox
• DataGrid
• Documento
• Modifica
• Gruppo
• Intestazione
• HeaderItem
• Elenco
• Menu

• MenuBar
• Riquadro
• SplitButton
• Scheda
• Tabella
• Barra degli strumenti
• Albero
• TreeItem
• Finestra

• Collegamento
• Caselle
• Pulsante

L'immagine seguente mostra un contenitore di testo (documento) con una tabella e un'immagine incorporata.

La Automazione interfaccia utente visualizzazione contenuto del documento precedente è illustrata nel diagramma seguente.

Oggetti incorporati "compatibili" e "non compatibili"

Alcuni provider di Automazione interfaccia utente usano lo stesso archivio testo per ogni oggetto TextPattern che contengono. Gli oggetti supportati dallo stesso archivio di testo del contenitore vengono definiti oggetti incorporati "compatibili". Questi oggetti possono essere oggetti TextPattern e, in questo caso, gli intervalli di testo sono paragonabili agli intervalli di testo ottenuti dal contenitore. Ciò consente ai provider di esporre informazioni client sui singoli oggetti TextPattern come se fossero uno, provider di testo di grandi dimensioni.

Tuttavia, i provider possono usare archivi di testo diversi per oggetti TextPattern diversi incorporati all'interno di un contenitore TextPattern. Gli oggetti non supportati dall'archivio di testo del contenitore vengono definiti oggetti incorporati non compatibili. Questi tipi di oggetti incorporati potrebbero o non essere oggetti basati su TextPattern.

Nella tabella seguente sono elencati alcuni esempi di oggetti incorporati compatibili e non compatibili.

Oggetti	Oggetti incorporati compatibili	Oggetti incorporati non compatibili
Oggetti incorporati non TextPattern	Pulsante in Microsoft Edge Tabella dati in Microsoft Edge	Pulsante in RichTextBlock nel framework XAML di Microsoft Immagini con alt-text in Microsoft Edge ListView con ListItems in RichTextBlock nel framework XAML di Microsoft
Oggetti incorporati TextPattern	Controllo di input di tipo "text" in Microsoft Edge Tabella in un documento di Word	Elemento TextBox in un documento di Microsoft Word

Esposizione di oggetti incorporati

I modelli di controllo Text e TextRange espongono proprietà e metodi che facilitano la navigazione e l'esecuzione di query sugli oggetti incorporati.

Il contenuto testuale (o il testo interno) di un contenitore di testo e di un oggetto incorporato, ad esempio un collegamento ipertestuale o una cella di tabella, viene esposto come un singolo flusso di testo continuo nella visualizzazione di controllo e nella visualizzazione contenuto dell'albero Automazione interfaccia utente; i limiti dell'oggetto vengono ignorati. Se un client Automazione interfaccia utente recupera il testo da recizionare, interpretare o analizzare in qualche modo, l'intervallo di testo deve essere controllato per casi speciali, ad esempio una tabella con contenuto testuale o altri oggetti incorporati. Chiamare IUIAutomationTextRange::GetChildren per ottenere un'interfaccia IUIAutomationElement per ogni oggetto incorporato e quindi chiamare IUIAutomationTextPattern::RangeFromChild per ottenere un intervallo di testo per ogni elemento. Questa operazione viene eseguita in modo ricorsivo fino a quando non è stato recuperato l'intero contenuto testuale.

Nota

Un intervallo degenerato (o compresso) è il punto in cui l'endpoint iniziale e l'endpoint finale sono uguali. Gli intervalli degenerati vengono spesso usati per indicare la posizione del cursore di testo tramite i metodi ITextProviderGetSelection e GetCaretRange .

Il diagramma seguente mostra un flusso di testo con oggetti incorporati e l'intervallo.

Oggetti incorporati e TextUnit

Un oggetto ITextProvider può essere attraversato e da un oggetto TextUnit specificato. I provider che contengono oggetti incorporati possono essere attraversati nello stesso modo, ma gli oggetti incorporati influiscono sull'attraversamento. Ecco alcune cose da tenere presente:

• Qualsiasi oggetto incorporato non compatibile è rappresentato dal carattere di sostituzione U+FFFC nell'archivio di testo dell'elemento contenitore TextPattern. È anche considerato un'unità di carattere e un'unità di parola.
• Gli oggetti incorporati compatibili possono essere costituiti da più caratteri e parole.
• L'elemento racchiuso è l'elemento più basso che estende l'intero intervallo di testo.
• Gli elementi figlio di un intervallo sono anche elementi figlio di un elemento contenitore parzialmente o completamente racchiuso all'interno dell'intervallo.
• Idealmente (soprattutto nel caso di elementi del contenitore come Table) un limite di parola non supera il limite dell'oggetto. Nell'esempio seguente l'unità di parola "Bar" non contiene alcuna posizione di testo esterna al </td> tag (<br \> non fa parte della parola "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/>

• In generale, <br \> viene considerato come una singola parola in modo che non vada oltre un limite di riga.
• Un'eccezione alla regola precedente è la posizione in cui un'unità di testo Word contiene oggetti completi all'interno di se stesso. Ad esempio, <p>Hello <a href="#">link</a> here.</p>che include contenitori inline, contiene le parole "Hello", "link" e "here". Dove "link" ha un oggetto TextPattern come elemento di inclusione e un oggetto di collegamento come figlio.
• Nel caso di unità Carattere, l'oggetto è l'elemento racchiuso (unità di testo come questa non deve avere elementi figlio).
• Gli oggetti annotazione non devono essere rappresentati come oggetto incorporato. Ad esempio, la presenza di altri identificatori author in un documento coautore.
• Gli oggetti incorporati occupano almeno una posizione del cursore, l'annotazione è solo metadati.
• Ogni limite di oggetto (inizio e fine) è rappresentato da un'interruzione di formato nell'intervallo di documenti TextPattern.
• Per HTML, ogni tag HTML non comporta necessariamente un oggetto Automazione interfaccia utente. Ad esempio, il contenuto all'interno dei tag di enfasi non deve essere rappresentato come elemento, ma piuttosto come flusso di testo in cui UIA_IsItalicAttributeId restituisce TRUE.
• L'endpoint iniziale è inclusivo ed è l'endpoint preferito mentre l'endpoint finale è esclusivo. Ciò è utile per quando l'intervallo viene degenerato e gli endpoint Start e End appartengono alla stessa posizione per tale intervallo.

Confronto di oggetti incorporati

Gli oggetti TextPattern annidati che si trovano in una relazione figlio simile e condividono lo stesso archivio di testo di backup vengono chiamati confrontabili. In questo caso, è possibile confrontare gli intervalli da uno degli oggetti TextPattern usando ITextRangeProvider::Compare e ITextRangeProvider::CompareEndpoints. Entrambi generano un valore numerico valido che specifica la relativa posizione relativa.

Un oggetto non TextPattern incorporato in un oggetto TextPattern è paragonabile a TextPattern se l'oggetto ha un intervallo valido in TextPattern (ITextProvider::RangeFromChild) e il contenuto dietro l'intervallo di testo non è vuoto e non è un carattere sostitutivo.

Oggetti TextPattern incorporati e Document TextUnit

Per gli oggetti TextPattern incorporati, l'unità Document riconosce solo il contenuto contenuto contenuto all'interno di tale elemento.

Word gerarchia degli elementi TextPattern

• L'elemento del documento implementa TextPattern e Document restituisce l'intero intervallo di documenti Word.
• Le singole pagine del documento implementano TextPattern e Document restituiscono il contenuto di tali singole pagine (anche se le pagine condividono lo stesso archivio di testo con l'intero documento TextPattern).

Controlli di input di testo e pagina Web in Edge

• L'elemento riquadro della pagina Web principale implementa TextPattern ed espone l'intero contenuto della pagina Web.
• I singoli controlli di input di testo supportano TextPattern in cui un intervallo di documenti rappresenta il testo contenuto in ogni campo di input (anche se condividono lo stesso archivio di testo con l'intera pagina Web).

Scenari comuni

Questa sezione presenta esempi di scenari comuni che coinvolgono oggetti incorporati: collegamenti ipertestuali, immagini e tabelle. Negli esempi seguenti la parentesi graffa sinistra ({) rappresenta l'endpoint iniziale dell'intervallo di testo e la parentesi graffa destra (}) rappresenta l'endpoint finale.

Esempio HyperLink 1: Intervallo di testo che contiene un collegamento ipertestuale di testo incorporato

L'intervallo di testo seguente contiene un collegamento ipertestuale di testo incorporato.

{L'URL https://www.microsoft.com è incorporato nel testo}.

Chiamando i metodi IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren e IUIAutomationTextPattern::RangeFromChild si ottengono i comportamenti descritti nella tabella seguente.

Metodo chiamato	Risultato
IUIAutomationTextRange::GetText	Restituisce la stringa "L'URL https://www.microsoft.com è incorporato nel testo".
IUIAutomationTextRange::GetEnclosingElement	Restituisce l'elemento più interno Automazione interfaccia utente che racchiude l'intervallo di testo, in questo caso, l'elemento di automazione che rappresenta il provider di testo stesso.
IUIAutomationTextRange::GetChildren	Restituisce un elemento Automazione interfaccia utente che rappresenta il controllo collegamento ipertestuale.
IUIAutomationTextPattern::RangeFromChild, dove l'elemento Automazione interfaccia utente è stato restituito dal metodo IUIAutomationTextRange::GetChildren precedente.	Restituisce l'intervallo che rappresenta "https://www.microsoft.com".

Esempio HyperLink 2: Intervallo di testo che si estende parzialmente su un collegamento ipertestuale di testo incorporato

L'intervallo di testo seguente si estende parzialmente su un collegamento ipertestuale di testo incorporato.

L'URL https://{www} è incorporato nel testo.

La chiamata ai metodi IUIAutomationTextRange::GetText, GetEnclosingElement e GetChildren comporta i comportamenti descritti nella tabella seguente.

Metodo chiamato	Risultato
IUIAutomationTextRange::GetText	Restituisce la stringa "www".
IUIAutomationTextRange::GetEnclosingElement	Restituisce l'elemento più interno Automazione interfaccia utente che racchiude l'intervallo di testo; in questo caso, il controllo collegamento ipertestuale.
IUIAutomationTextRange::GetChildren	Restituisce NULL perché l'intervallo di testo non si estende sull'intera stringa URL.

Esempio HyperLink 3: Intervallo di testo che si estende parzialmente sul contenuto di un contenitore di testo

L'intervallo di testo seguente si estende parzialmente sul contenuto di un contenitore di testo. Il contenitore di testo contiene testo incorporato che non fa parte dell'intervallo di testo.

{URL} https://www.microsoft.com è incorporato nel testo.

La chiamata ai metodi IUIAutomationTextRange::GetText, GetEnclosingElement e Move comporta i comportamenti descritti nella tabella seguente.

Metodo chiamato	Risultato
IUIAutomationTextRange::GetText	Restituisce la stringa "L'URL".
IUIAutomationTextRange::GetEnclosingElement	Restituisce l'elemento più interno Automazione interfaccia utente che racchiude l'intervallo di testo, in questo caso, l'elemento che rappresenta il provider di testo stesso.
IUIAutomationTextRange::Move	Sposta l'intervallo di testo su "https://" perché il testo del collegamento ipertestuale è costituito da singole parole. In questo caso, il collegamento ipertestuale non viene considerato come oggetto singolo. L'URL {http} è incorporato nel testo.

Esempio di immagine 1: intervallo di testo che contiene un'immagine incorporata

L'intervallo di testo seguente contiene un'immagine incorporata di una navetta.

{ è incorporata nel testo}.

Chiamando i metodi IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren e IUIAutomationTextPattern::RangeFromChild si ottengono i comportamenti descritti nella tabella seguente.

Metodo chiamato	Risultato
IUIAutomationTextRange::GetText	Restituisce la stringa "L'immagine è incorporata nel testo". Qualsiasi testo ALT associato all'immagine non è incluso nel flusso di testo.
IUIAutomationTextRange::GetEnclosingElement	Restituisce l'elemento più interno Automazione interfaccia utente che racchiude l'intervallo di testo, in questo caso, l'elemento che rappresenta il provider di testo stesso.
IUIAutomationTextRange::GetChildren	Restituisce un elemento Automazione interfaccia utente che rappresenta il controllo immagine.
IUIAutomationTextPattern::RangeFromChild in cui l'elemento Automazione interfaccia utente è stato restituito dal metodo IUIAutomationTextRange::GetChildren precedente.	Restituisce l'intervallo degenerato.

Esempio di immagine 2: intervallo di testo che si estende parzialmente sul contenuto di un contenitore di testo

L'intervallo di testo seguente si estende parzialmente sul contenuto di un contenitore di testo. Il contenitore di testo contiene un'immagine incorporata che non fa parte dell'intervallo di testo.

{L'immagine} è incorporata nel testo.

La chiamata ai metodi IUIAutomationTextRange::GetText, GetEnclosingElement e Move comporta i comportamenti descritti nella tabella seguente.

Metodo chiamato	Risultato
IUIAutomationTextRange::GetText	Restituisce la stringa "L'immagine".
IUIAutomationTextRange::GetEnclosingElement	Restituisce l'elemento più interno Automazione interfaccia utente che racchiude l'intervallo di testo, in questo caso, l'elemento che rappresenta il provider di testo stesso.
IUIAutomationTextRange::Move con parametri di (TextUnit_Word, 2).	Sposta l'estensione dell'intervallo di testo a "è". Poiché solo gli oggetti incorporati basati su testo sono considerati parte del flusso di testo, l'immagine in questo esempio non influisce su IUIAutomationTextRange::Move o sul relativo valore restituito, in questo caso 2.

Tabella

Esempio di tabella 1: ottiene il contenitore di testo dal contenuto di una cella

La tabella seguente ottiene il contenitore di testo dal contenuto di una cella.

Cella con immagine	Cella con testo
	X
	S
	Z

Chiamando i metodi IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild e IUIAutomationTextRange::GetEnclosingElement vengono restituiti i comportamenti descritti nella tabella seguente.

Metodo chiamato	Risultato
IUIAutomationGridPattern::GetItem con parametri (0, 0).	Restituisce l'elemento Automazione interfaccia utente che rappresenta il contenuto della cella della tabella, in questo caso l'elemento è un controllo di testo.
iuiautomationtextpattern::rangefromchild	restituisce l'intervallo .
GetEnclosingElement per l'oggetto restituito dal metodo IUIAutomationTextPattern::RangeFromChild precedente.	Restituisce l'elemento Automazione interfaccia utente che rappresenta la cella della tabella. In questo caso, l'elemento è un controllo di testo che supporta il pattern di controllo TableItem .
IUIAutomationTextRange::GetEnclosingElement per l'oggetto restituito dal metodo GetEnclosingElement precedente.	Restituisce l'elemento Automazione interfaccia utente che rappresenta la tabella.
IUIAutomationTextRange::GetEnclosingElement per l'oggetto restituito dal metodo GetEnclosingElement precedente.	Restituisce l'elemento Automazione interfaccia utente che rappresenta il provider di testo stesso.

Esempio di tabella 2: ottiene il contenuto di testo di una cella

La tabella nell'esempio precedente ottiene il contenuto di testo di una cella.

La chiamata dei metodi IUIAutomationGridPattern::GetItem e IUIAutomationTextPattern::RangeFromChild comporta i comportamenti descritti nella tabella seguente.

Metodo chiamato	Risultato
IUIAutomationGridPattern::GetItem con parametri (1,1).	Restituisce l'elemento Automazione interfaccia utente che rappresenta il contenuto della cella della tabella. In questo caso, l'elemento è un controllo di testo.
IUIAutomationTextPattern::RangeFromChild dove l'elemento Automazione interfaccia utente è l'oggetto restituito dal metodo IUIAutomationGridPattern::GetItem precedente.	Restituisce "Y".

Quando si passa attraverso un documento TextUnit_Line, se l'intervallo di testo entra in una tabella incorporata, ogni riga di testo in una cella deve essere considerata come una riga.

Argomenti correlati

Informazioni concettuali

• Informazioni sui pattern di controllo Text e TextRange
• attributi di testo Automazione interfaccia utente
• Cenni preliminari sui pattern di controllo per l'automazione interfaccia utente
• supporto di Automazione interfaccia utente per il contenuto testuale