Comment UI Automation expose les 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.
Par UI Automation, un objet incorporé est un élément qui a des limites non textuelles telles qu’une image, un lien hypertexte, une table ou un type de document (feuille de calcul Microsoft Excel, fichier Microsoft Windows Media, 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. La possibilité de modifier l’objet dans son application d’origine n’est pas pertinente dans le contexte de UI Automation.
Objets incorporés et arborescence UI Automation
Les objets incorporés sont traités comme des éléments individuels dans la vue de contrôle de l’arborescence UI Automation. Ils sont exposés en tant qu’enfants du conteneur de texte afin d’ê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-conteneur
- Calendrier
- Combobox
- DataGrid
- Document
- Modifier
- Groupe
- En-tête
- HeaderItem
- Liste
- Menu
- MenuBar
- Volet
- SplitButton
- Onglet
- Table de charge de travail
- Barre d'outils
- Arborescence
- TreeItem
- Fenêtre
- Lien
- Cases
- Bouton
L’image suivante montre un conteneur de texte (document) avec une table et une image incorporées.
La vue de contenu UI Automation du document précédent est illustrée 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 soutenus 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 sur les 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 non sauvegardés par le magasin de texte du conteneur sont appelés objets incorporés « non compatibles ». Ces types d’objets incorporés peuvent ou non être des objets 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 | Bouton dans Microsoft Edge Table de données dans Microsoft Edge |
Bouton dans RichTextBlock dans l’infrastructure XAML de Microsoft Images avec texte de remplacement 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 |
Exposition d’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 d’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 du contenu de l’arborescence UI Automation. Le contour des objets est ignoré. Si un client UI Automation récupère le texte à réciter, interpréter ou analyser d’une manière ou d’une autre, la plage de texte doit être vérifiée pour des cas spéciaux, tels qu’un tableau contenant 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’endroit où le point de terminaison de début et le point de terminaison sont identiques. Les plages dégénérées sont souvent utilisées pour indiquer la position du curseur de texte par le biais des méthodes GetSelection et GetCaretRangeITextProvider.
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 TextUnit spécifié. Les fournisseurs qui contiennent des objets incorporés peuvent être parcourus de la même manière, mais les objets incorporés affectent la traversée. Voici quelques points à prendre en compte :
- 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 une unité de mot.
- Les objets incorporés compatibles peuvent se composer de plusieurs caractères et mots.
- L’élément englobant est l’élément le plus bas qui s’étend sur 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 enfermé dans la plage.
- Idéalement (en particulier dans le cas d’éléments de conteneur comme Table) une limite de mot ne va pas au-delà de la limite de l’objet. Dans l’exemple suivant, l’unité de mot « Bar » ne contient aucune position de texte qui se trouve en dehors de la
</td>balise (<br \>ne 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 telle sorte qu’il ne va pas au-delà d’une limite de ligne. - Une exception à la règle précédente est qu’une unité de texte Word contient des objets complets en elle-même. Par exemple,
<p>Hello <a href="#">link</a> here.</p>, qui inclut les conteneurs inline, a les mots « Hello », « link » et « here ». Où « link » a un objet TextPattern comme élément englobant et un objet link comme enfant. - Dans le cas des unités de caractère, l’objet est l’élément englobant (les unités de texte comme celle-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 d’auteur dans un document co-écrit.
- Les objets incorporés occupent au moins une position de curseur, l’annotation n’est que des métadonnées.
- Chaque limite d’objet (début et fin) est représentée par un saut de format dans la plage de documents TextPattern.
- Pour le code HTML, chaque balise html n’entraîne pas nécessairement un objet UI Automation. Par exemple, le contenu des balises d’accentuation n’a pas besoin d’être représenté en tant qu’élément, mais plutôt en tant que flux de texte où UIA_IsItalicAttributeId retourne TRUE.
- Le point de terminaison de début est inclusif et est le point de terminaison préféré, tandis que le point de terminaison est exclusif. Cela est utile lorsque la plage dégénère 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 stockage 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 aboutissent à une valeur numérique valide spécifiant leur position relative.
Un objet non TextPattern incorporé dans un objet TextPattern est comparable à TextPattern si l’objet a une plage valide dans le TextPattern (ITextProvider::RangeFromChild) et que le contenu derrière la plage de texte n’est pas vide et n’est pas un caractère de remplacement.
Objets TextPattern incorporés et Document TextUnit
Pour les objets TextPattern incorporés, l’unité Document reconnaît uniquement le contenu contenu dans cet élément.
Word hiérarchie d’éléments TextPattern
- L’élément document implémente TextPattern et Document retourne l’ensemble de la plage de documents Word.
- Les pages individuelles du document implémentent TextPattern et Document retourne 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 d’entrée de page web et de texte dans Edge
- L’élément Volet main page web implémente TextPattern et expose l’ensemble 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 impliquant des objets incorporés : liens hypertexte, images et tableaux. Dans les exemples suivants, l’accolade gauche ({) représente le point de terminaison De début de la plage de texte, et l’accolade droite (}) représente le point de terminaison De fin.
Exemple HyperLink 1 : Plage de texte qui contient un lien hypertexte de texte incorporé
La plage de texte suivante contient un lien hypertexte de texte incorporé.
{L’URL https://www.microsoft.com est incorporée dans le texte}.
L’appel des méthodes IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren et IUIAutomationTextPattern::RangeFromChild entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationTextRange::GetText | Renvoie la chaîne « L’URL https://www.microsoft.com est incorporée dans le texte ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément le plus interne UI Automation qui entoure 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 représentant 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 HyperLink 2 : Plage de texte qui s’étend partiellement sur un lien hypertexte de texte incorporé
La plage de texte suivante couvre partiellement un lien hypertexte de texte incorporé.
L’URL https://{www} est incorporée dans le texte.
L’appel des méthodes IUIAutomationTextRange::GetText, GetEnclosingElement et GetChildren aboutit aux 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 le plus interne UI Automation qui entoure la plage de texte ; dans ce cas, le contrôle de lien hypertexte. |
| IUIAutomationTextRange::GetChildren | Retourne NULL , car la plage de texte ne couvre pas toute la chaîne d’URL. |
Exemple HyperLink 3 : plage de texte qui couvre partiellement le contenu d’un conteneur de texte
La plage de texte suivante couvre partiellement le 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.
{L’URL} https://www.microsoft.com est incorporé dans le texte.
L’appel des méthodes IUIAutomationTextRange::GetText, GetEnclosingElement et 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 le plus interne UI Automation qui entoure la plage de texte, dans ce cas, l’élément qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange::Move | Déplace l’étendue de plage de texte sur « 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. |
Exemple d’image 1 : Plage de texte qui contient une image incorporée
La plage de texte suivante contient une image incorporée d’une navette.
{ 
est incorporée dans du texte}.
L’appel des méthodes IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren et IUIAutomationTextPattern::RangeFromChild entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationTextRange::GetText | Renvoie la chaîne « L’image est incorporée dans le texte ». Tout texte ALT associé à l’image n’est pas inclus dans le flux de texte. |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément le plus interne UI Automation qui entoure 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 représentant le contrôle d’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 qui couvre partiellement le contenu d’un conteneur de texte
La plage de texte suivante couvre partiellement le 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.
{L’image} est incorporée dans du texte.
L’appel des méthodes IUIAutomationTextRange::GetText, GetEnclosingElement et 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 le plus interne UI Automation qui entoure 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 (TextUnit_Word, 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 tableau 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::RangeFromChild et IUIAutomationTextRange::GetEnclosingElement entraîne les comportements décrits dans le tableau suivant.
| Méthode appelée | Résultats |
|---|---|
| IUIAutomationGridPattern::GetItem avec des 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 . |
| GetEnclosingElement pour l’objet retourné par la méthode IUIAutomationTextPattern::RangeFromChild précédente. | Retourne l’élément UI Automation représentant la cellule du 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 représentant 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 tableau 2 : obtient le contenu textuel 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 des 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 ». |
Lorsque vous parcourez un document par TextUnit_Line, si la plage de texte entre dans un tableau incorporé, chaque ligne de texte d’une cellule doit être traitée comme une ligne.
Rubriques connexes
Conceptuel
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour