Comment UI Automation expose des objets incorporés
Cette rubrique décrit comment Microsoft UI Automation utilise les modèles de contrôle Text et TextRange pour exposer des objets incorporés (éléments enfants/descendants) dans un document texte ou un conteneur.
pour UI Automation, un objet incorporé est un élément qui a des limites non textuelles telles qu’une image, un lien hypertexte, un tableau ou un type de document (Microsoft Excel feuille de calcul, Microsoft Windows fichier multimédia, etc.).
Notes
Cela diffère de la définition OLE COM (Component Object Model) (voir objets incorporés), où un élément est créé dans une application et incorporé ou lié dans une autre application. Le fait que l’objet puisse être modifié dans son application d’origine est sans importance dans le contexte de l’Automation d’interface utilisateur.
Objets incorporés et arborescence UI Automation
Les objets incorporés sont traités comme des éléments individuels dans l’affichage de contrôle de l’arborescence UI Automation. Ils sont exposés en tant qu’enfants du conteneur de texte pour être accessibles via le même modèle objet que d’autres contrôles dans UI Automation.
Le tableau suivant répertorie des exemples d’éléments conteneur et non-conteneur.
Éléments conteneurs
Éléments non-conteneurs
- Calendrier
- Combobox
- DataGrid
- Document
- Modifier
- Group
- En-tête
- HeaderItem
- List
- Menu
- MenuBar
- Volet
- SplitButton
- Onglet
- Table de charge de travail
- Barre d’outils
- Arborescence
- TreeItem
- Fenêtre
- Lien
- Cases à cocher
- Bouton
L’illustration suivante montre un conteneur de texte (document) avec une table et une image incorporées.

L’affichage de contenu UI Automation du document précédent est illustré dans le diagramme suivant.

Objets incorporés « compatibles » et « non compatibles »
Certains fournisseurs UI Automation utilisent le même magasin de texte pour chaque objet TextPattern qu’ils contiennent. Les objets qui sont sauvegardés par le même magasin de texte que leur conteneur sont appelés objets incorporés « compatibles ». Ces objets peuvent être des objets TextPattern eux-mêmes et, dans ce cas, leurs plages de texte sont comparables aux plages de texte obtenues à partir de leur conteneur. Cela permet aux fournisseurs d’exposer des informations client relatives aux objets TextPattern individuels comme s’il s’agissait d’un fournisseur de texte volumineux.
Toutefois, les fournisseurs peuvent utiliser différents magasins de texte pour différents objets TextPattern incorporés dans un conteneur TextPattern. Les objets qui ne sont pas sauvegardés par le magasin de texte du conteneur sont appelés objets incorporés « non compatibles ». Ces types d’objets incorporés peuvent être ou ne pas être des objets basés sur TextPattern.
Le tableau suivant répertorie quelques exemples d’objets incorporés compatibles et non compatibles.
| Objets | Objets incorporés compatibles | Objets incorporés non compatibles |
|---|---|---|
| Objets incorporés non-TextPattern | Dans Microsoft Edge Table de données dans Microsoft Edge |
Dans RichTextBlock dans l’infrastructure XAML de Microsoft Images avec texte alt dans Microsoft Edge ListView avec ListItems dans RichTextBlock dans l’infrastructure XAML de Microsoft |
| Objets incorporés TextPattern | Contrôle d’entrée de type « text » dans Microsoft Edge Tableau dans un document Word |
élément TextBox dans un document Microsoft Word |
Exposer des objets incorporés
Les modèles de contrôle Text et TextRange exposent des propriétés et des méthodes qui facilitent la navigation et l’interrogation des objets incorporés.
Le contenu textuel (ou texte interne) d’un conteneur de texte et d’un objet incorporé, tel qu’un lien hypertexte ou une cellule de tableau, est exposé en tant que flux de texte unique et continu dans l’affichage de contrôle et l’affichage de contenu de l’arborescence UI Automation. les limites de l’objet sont ignorées. Si un client UI Automation récupère le texte à des fins de récit, d’interprétation ou d’analyse de quelque manière que ce soit, la plage de texte doit être vérifiée à la recherche de cas spéciaux, tels qu’une table avec du contenu textuel ou d’autres objets incorporés. Appelez IUIAutomationTextRange :: GetChildren pour obtenir une interface IUIAutomationElement pour chaque objet incorporé, puis appelez IUIAutomationTextPattern :: RangeFromChild pour obtenir une plage de texte pour chaque élément. Cette action se répète jusqu'à ce que tout le contenu textuel ait été récupéré.
Notes
Une plage dégénérée (ou réduite) est l’emplacement où le point de terminaison de démarrage et le point de terminaison de fin sont identiques. Les plages dégénérées sont souvent utilisées pour indiquer la position du curseur de texte via les méthodes ITextProvider GetSelection et GetCaretRange .
Le diagramme suivant montre un flux de texte avec des objets incorporés et leurs étendues de plage.

Objets incorporés et TextUnit
Un objet ITextProvider peut être parcouru et par un TextUnitspécifié. Les fournisseurs qui contiennent des objets incorporés peuvent être parcourus à peu près de la même façon, mais les objets incorporés affectent le parcours. Voici quelques éléments à connaître :
- Tout objet incorporé non compatible est représenté par le caractère de remplacement U + FFFC dans le magasin de texte du TextPattern de l’élément conteneur. Il est également considéré à la fois comme une unité de caractères et comme une unité de mot.
- Les objets incorporés compatibles peuvent être constitués de plusieurs caractères et mots.
- L’élément englobant est l’élément le plus bas qui couvre l’ensemble de la plage de texte.
- Les éléments enfants d’une plage sont également des éléments enfants d’un élément conteneur qui est partiellement ou complètement inclus dans la plage.
- Dans l’idéal (surtout dans le cas d’éléments de conteneur comme table), une limite de mot n’excède pas la limite de l’objet. Dans l’exemple suivant, le mot « bar » ne contient pas de position de texte en dehors de la
</td>balise (ne<br \>fait pas partie du mot « 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 général,
<br \>est traité comme un mot individuel, de sorte qu’il ne dépasse pas les limites d’une ligne. - Une exception à la règle précédente est l’emplacement où une unité de texte Word contient des objets complets au sein de celle-ci. Par exemple,
<p>Hello <a href="#">link</a> here.</p>, qui inclut des conteneurs insérés, contient les mots « Hello », « Link » et « here ». Où « Link » a un objet TextPattern en tant qu’élément englobant et un objet de lien comme enfant. - Dans le cas d’unités de caractères, l’objet est l’élément englobant (les unités de texte comme celui-ci ne doivent pas avoir d’enfants).
- Les objets d’annotation ne doivent pas être représentés en tant qu’objet incorporé. Par exemple, la présence d’autres spécificateurs Author dans un document co-créé.
- Les objets incorporés occupent au moins une position de curseur, les annotations sont simplement des métadonnées.
- Chaque limite d’objet (de début et de fin) est représentée par un saut de mise en forme dans la plage de documents TextPattern.
- Pour le format HTML, chaque balise HTML ne produit pas nécessairement un objet UI Automation. Par exemple, le contenu des balises d’accentuation n’a pas besoin d’être représenté comme élément, mais plutôt comme un flux de texte où UIA_IsItalicAttributeId retourne la valeur true.
- Le point de terminaison de démarrage est inclus et est le point de terminaison préféré alors que le point de terminaison de fin est exclusif. Cela est utile lorsque la plage est dégénérée et que les points de terminaison de début et de fin appartiennent à la même position pour cette plage.
Comparaison d’objets incorporés
Les objets TextPattern imbriqués qui se trouvent dans une relation enfant similaire et partagent le même magasin de texte de sauvegarde sont appelés comparables. Dans ce cas, les plages de l’un des objets TextPattern peuvent être comparées à l’aide de ITextRangeProvider :: compare et ITextRangeProvider :: CompareEndpoints. Les deux produisent une valeur numérique valide spécifiant leur position relative.
Un objet non TextPattern incorporé dans un objet TextPattern est comparable au TextPattern si l’objet a une plage valide dans TextPattern (ITextProvider :: RangeFromChild) et que le contenu situé derrière la plage de texte n’est pas vide et qu’il ne s’agit pas d’un caractère de remplacement.
Objets TextPattern incorporés et le document TextUnit
Pour les objets TextPattern incorporés, l’unité de document reconnaît uniquement le contenu contenu dans cet élément.
Hiérarchie d’éléments de Word TextPattern
- L’élément document implémente TextPattern et document retourne l’intégralité de la plage de documents Word.
- Les pages individuelles du document implémentent TextPattern et document renvoie le contenu de ces pages individuelles (même si les pages partagent le même magasin de texte avec l’ensemble du document TextPattern).
Contrôles de saisie de texte et de page Web dans Edge
- L’élément principal du volet de page Web implémente TextPattern et expose la totalité du contenu de la page Web.
- Les contrôles d’entrée de texte individuels prennent en charge TextPattern, où une plage de documents représente le texte contenu dans chaque champ d’entrée (même s’ils partagent le même magasin de texte avec l’ensemble de la page Web).
Scénarios courants
Cette section présente des exemples de scénarios courants qui impliquent des objets incorporés : liens hypertexte, images et tables. Dans les exemples suivants, l’accolade ouvrante ({) représente le point de terminaison de début de la plage de texte, et l’accolade fermante (}) représente le point de terminaison de fin.
HYPERLINK Example 1 : plage de texte qui contient un lien hypertexte textuel incorporé
La plage de texte suivante contient un lien hypertexte textuel incorporé.
{L’URL https://www.microsoft.com est incorporée dans le texte}.
L’appel des méthodes IUIAutomationTextRange :: gettext, GetEnclosingElement, GetChildrenet IUIAutomationTextPattern :: RangeFromChild entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationTextRange :: GetText | Retourne la chaîne « l’URL https://www.microsoft.com est incorporée dans le texte ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus profond qui englobe la plage de texte, dans ce cas, l’élément Automation qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange :: GetChildren | Retourne un élément UI Automation qui représente le contrôle de lien hypertexte. |
| IUIAutomationTextPattern :: RangeFromChild, où l’élément UI Automation a été retourné par la méthode IUIAutomationTextRange :: GetChildren précédente. | Retourne la plage qui représente « https://www.microsoft.com ». |
Exemple de lien hypertexte 2 : plage de texte couvrant partiellement un lien hypertexte textuel incorporé
La plage de texte suivante s’étend partiellement à un lien hypertexte de texte incorporé.
L’URL https://{www} est incorporée dans le texte.
L’appel des méthodes IUIAutomationTextRange :: gettext, GetEnclosingElementet GetChildren entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationTextRange :: GetText | Retourne la chaîne « www ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus profond qui englobe la plage de texte ; dans ce cas, le contrôle de lien hypertexte. |
| IUIAutomationTextRange :: GetChildren | Retourne la valeur null , car la plage de texte ne couvre pas l’intégralité de la chaîne d’URL. |
Exemple de lien hypertexte 3 : plage de texte couvrant partiellement le contenu d’un conteneur de texte
La plage de texte suivante s’étend partiellement au contenu d’un conteneur de texte. Le conteneur de texte a un lien hypertexte textuel incorporé qui ne fait pas partie de la plage de texte.
{URL} https://www.microsoft.com est incorporé dans le texte.
L’appel des méthodes IUIAutomationTextRange :: gettext, GetEnclosingElementet Move entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationTextRange :: GetText | Retourne la chaîne « L'URL ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus profond qui englobe la plage de texte, dans ce cas, l’élément qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange :: Move | Déplace la plage de texte vers « https:// », car le texte du lien hypertexte est composé de mots individuels. Dans ce cas, le lien hypertexte n'est pas traité comme un objet unique. L’URL {http} est incorporée dans le texte. |
Image exemple 1 : plage de texte qui contient une image incorporée
La plage de texte suivante contient une image incorporée d’une navette.
{Image
est incorporé dans le texte}.
L’appel des méthodes IUIAutomationTextRange :: gettext, GetEnclosingElement, GetChildrenet IUIAutomationTextPattern :: RangeFromChild entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationTextRange :: GetText | Retourne la chaîne « l’image est incorporée dans le texte ». Tout texte de remplacement associé à l’image n’est pas inclus dans le flux de texte. |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus profond qui englobe la plage de texte, dans ce cas, l’élément qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange :: GetChildren | Retourne un élément UI Automation qui représente le contrôle image. |
| IUIAutomationTextPattern :: RangeFromChild où l’élément UI Automation a été retourné par la méthode IUIAutomationTextRange :: GetChildren précédente. | Retourne la plage dégénérée. |
Exemple d’image 2 : plage de texte couvrant partiellement le contenu d’un conteneur de texte
La plage de texte suivante s’étend partiellement au contenu d’un conteneur de texte. Le conteneur de texte comporte une image incorporée qui ne fait pas partie de la plage de texte.
{Image}
est incorporé dans le texte.
L’appel des méthodes IUIAutomationTextRange :: gettext, GetEnclosingElementet Move entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationTextRange :: GetText | Retourne la chaîne « L'image ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus profond qui englobe la plage de texte, dans ce cas, l’élément qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange :: Move avec les paramètres de ( _ mot TextUnit, 2). | Déplace la plage de texte vers « est ». Étant donné que seuls les objets incorporés basés sur du texte sont considérés comme faisant partie du flux de texte, l’image de cet exemple n’affecte pas IUIAutomationTextRange :: Move ou sa valeur de retour, dans ce cas, 2. |
Table de charge de travail
Exemple de table 1 : obtient le conteneur de texte à partir du contenu d’une cellule
Le tableau suivant obtient le conteneur de texte à partir du contenu d’une cellule.
| Cellule avec l'image | Cellule avec le texte |
|---|---|
![]() |
X |
![]() |
O |
![]() |
Z |
L’appel des méthodes IUIAutomationGridPattern :: GetItem, IUIAutomationTextPattern :: RangeFromChildet IUIAutomationTextRange :: GetEnclosingElement entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationGridPattern :: GetItem avec les paramètres (0,0). | Retourne l’élément UI Automation qui représente le contenu de la cellule de tableau, dans ce cas, l’élément est un contrôle de texte. |
| iuiautomationtextpattern::rangefromchild | retourne la plage de l’image . |
| GetEnclosingElement pour l’objet retourné par la méthode IUIAutomationTextPattern :: RangeFromChild précédente. | Retourne l’élément UI Automation qui représente la cellule de tableau. Dans ce cas, l’élément est un contrôle de texte qui prend en charge le modèle de contrôle TableItem . |
| IUIAutomationTextRange :: GetEnclosingElement pour l’objet retourné par la méthode GetEnclosingElement précédente. | Retourne l’élément UI Automation qui représente la table. |
| IUIAutomationTextRange :: GetEnclosingElement pour l’objet retourné par la méthode GetEnclosingElement précédente. | Retourne l’élément UI Automation qui représente le fournisseur de texte lui-même. |
Exemple de table 2 : obtient le contenu de texte d’une cellule
Le tableau de l’exemple précédent obtient le contenu textuel d’une cellule.
L’appel des méthodes IUIAutomationGridPattern :: GetItem et IUIAutomationTextPattern :: RangeFromChild entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationGridPattern :: GetItem avec paramètres (1, 1). | Retourne l’élément UI Automation qui représente le contenu de la cellule de tableau. Dans ce cas, l’élément est un contrôle de texte. |
| IUIAutomationTextPattern :: RangeFromChild où l’élément UI Automation est l’objet retourné par la méthode IUIAutomationGridPattern :: GetItem précédente. | Retourne « Y ». |
Lors du déplacement d’un document par _ ligne TextUnit, si la plage de texte entre dans une table incorporée, chaque ligne de texte dans une cellule doit être traitée comme une ligne.

