Come Automazione interfaccia utente espone oggetti incorporati
In questo argomento viene descritto come Microsoft Automazione interfaccia utente usa i pattern 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 Di Microsoft Windows Media e così via).
Nota
Ciò differisce dalla definizione OLE COM (Component Object Model) (vedere Oggetti incorporati), in cui un elemento viene creato 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
- Raggruppa
- Intestazione
- HeaderItem
- List
- Menu
- MenuBar
- Riquadro
- SplitButton
- Tab
- Tabella
- Barra degli strumenti
- Albero
- TreeItem
- Window
- Collega
- Caselle di controllo
- Pulsante
L'immagine seguente mostra un contenitore di testo (documento) con una tabella e un'immagine incorporati.
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 di 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 stessi e, in questo caso, i relativi intervalli di testo sono paragonabili agli intervalli di testo ottenuti dal relativo contenitore. In questo modo, i provider possono esporre informazioni client sui singoli oggetti TextPattern come se fossero uno dei 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 essere o meno 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 testo alternativo 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 pattern di controllo Text e TextRange espongono proprietà e metodi che facilitano la navigazione e l'esecuzione di query su oggetti incorporati.
Il contenuto testuale (o testo interno) di un contenitore di testo o di un oggetto incorporato, ad esempio una cella di tabella o un collegamento ipertestuale, viene esposto come un flusso di testo continuo sia nella vista di controllo che nella vista del contenuto dell'albero di Automazione interfaccia utente. I limiti dell'oggetto vengono ignorati. Se un client Automazione interfaccia utente recupera il testo da recitare, 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 ITextProvider GetSelection e GetCaretRange .
Il diagramma seguente mostra un flusso di testo con oggetti incorporati e i relativi intervalli di 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 alcuni aspetti da tenere presenti:
- Qualsiasi oggetto incorporato non compatibile è rappresentato dal carattere di sostituzione U+FFFC nell'archivio di testo del TextPattern dell'elemento contenitore. Viene anche considerato sia un'unità di caratteri che un'unità di parola.
- Gli oggetti incorporati compatibili possono essere costituiti da più caratteri e parole.
- L'elemento contenitore è l'elemento più in basso che si estende sull'intero intervallo di testo.
- Gli elementi figlio di un intervallo sono anche elementi figlio di un elemento contenitore parzialmente o completamente racchiuso nell'intervallo.
- Idealmente (soprattutto nel caso di elementi 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 trattato come una singola parola in modo che non vada oltre un limite di linea. - Un'eccezione alla regola precedente è la posizione in cui un'unità di testo di Word contiene oggetti completi all'interno di se stesso. Ad esempio,
<p>Hello <a href="#">link</a> here.</p>, che include contenitori inline, ha le parole "Hello", "link " e "here". Dove "link" ha un oggetto TextPattern come elemento contenitore e un oggetto collegamento come figlio. - Nel caso delle unità Character, l'oggetto è l'elemento contenitore (le unità di testo come questa non devono contenere 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 di uno degli oggetti TextPattern usando ITextRangeProvider::Compare e ITextRangeProvider::CompareEndpoints. Entrambi generano un valore numerico valido che specifica la 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.
Gerarchia di elementi Word TextPattern
- L'elemento del documento implementa TextPattern e Document restituisce l'intero intervallo di documenti di Word.
- Le singole pagine del documento implementano TextPattern e Document restituisce 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 pagine 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 contenente 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}.
La chiamata dei metodi IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren e IUIAutomationTextPattern::RangeFromChild determina 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 Automazione interfaccia utente più interno 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 dei metodi IUIAutomationTextRange::GetText, GetEnclosingElement e Move determina 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.
{L'immagine 
è incorporata nel testo}.
La chiamata dei metodi IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren e IUIAutomationTextPattern::RangeFromChild determina 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 dove 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 dei metodi IUIAutomationTextRange::GetText, GetEnclosingElement e Move determina 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 |
 |
Y |
 |
Z |
La chiamata dei metodi IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild e IUIAutomationTextRange::GetEnclosingElement determina 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 dell'immagine . |
| 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.