Vue d'ensemble de TextPattern et des objets incorporés

Notes

Cette documentation s’adresse aux développeurs .NET Framework qui souhaitent utiliser les classes UI Automation managées définies dans l’espace de noms System.Windows.Automation. Pour obtenir les dernières informations sur UI Automation, consultez API Windows Automation : UI Automation.

Cette vue d’ensemble décrit comment Microsoft UI Automation expose des objets incorporés ou des éléments enfants dans un document texte ou un conteneur.

Dans UI Automation, un objet incorporé est tout élément qui a des limites non textuelles, par exemple, une image, un lien hypertexte, un tableau ou un type de document tel qu’une feuille de calcul Microsoft Excel ou un fichier Microsoft Windows Media. Cette notion est différente de la définition standard, où un élément est créé dans une application et incorporé, ou lié, dans une autre. La modification de l’objet dans son application d’origine est sans importance dans le contexte d’UI Automation.

Objets incorporés et arborescence UI Automation

Les objets incorporés sont traités comme des éléments individuels au sein de la vue 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 que les autres contrôles dans UI Automation.

Exemple d’un conteneur de texte avec des objets incorporés tableau, image et lien hypertexte

Exemple de l’affichage du contenu pour une partie du conteneur de texte précédent

Exposer des objets incorporés à l'aide de TextPattern et TextPatternRange

Utilisées conjointement, la classe de modèle de contrôle TextPattern et la classe TextPatternRange exposent des méthodes et des propriétés 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 du contenu de l’arborescence UI Automation. Le contour des objets est ignoré. Si un client UI Automation récupère le texte à des fins de récitation, interprétation ou analyse de quelque façon que ce soit, vous devez vérifier les cas spéciaux de la plage de texte, tels qu’un tableau avec du contenu textuel ou d’autres objets incorporés. Vous pouvez le faire en appelant GetChildren pour obtenir un AutomationElement pour chaque objet incorporé, puis 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é.

Exemple de flux de texte avec des objets incorporés et leurs amplitudes

Quand il est nécessaire de parcourir le contenu d'une plage de texte, il faut effectuer une série d'étapes en arrière-plan pour assurer la bonne exécution de la méthode Move .

1. La plage de texte est normalisée : elle est réduite en une plage dégénérée au niveau du point de terminaison Start , rendant le point de terminaison End superflu. Cette étape est nécessaire pour supprimer toute ambiguïté dans des situations où une plage de texte couvre les limites d’une TextUnit : par exemple, {The URL https://www.microsoft.com is embedded in text où « { » et « } » sont les points de terminaison de la plage de texte.

2. La plage obtenue est déplacée vers l'arrière dans DocumentRange au début de la limite TextUnit demandée.

3. La plage est avancée ou reculée dans DocumentRange du nombre demandé de limites TextUnit .

4. La plage est ensuite étendue à partir d'un état de plage dégénérée en déplaçant le point de terminaison End d'une limite TextUnit demandée.

Exemples de la façon dont une plage de texte est ajustée pour Move() et ExpandToEnclosingUnit()

Scénarios courants

Les sections suivantes présentent les exemples de scénarios les plus courants qui impliquent des objets incorporés.

Légende des exemples :

{ = Start

} = End

Hyperlink

Exemple 1 - Plage de texte contenant un lien hypertexte textuel incorporé

{The URL https://www.microsoft.com is embedded in text}.

Méthode appelée	Résultats
GetText	Retourne la chaîne The URL https://www.microsoft.com is embedded in text.
GetEnclosingElement	Retourne l' AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l' AutomationElement qui représente le fournisseur de texte lui-même.
GetChildren	Retourne un AutomationElement qui représente le contrôle de lien hypertexte.
RangeFromChild où AutomationElement est l'objet retourné par la méthode GetChildren précédente.	Retourne la plage représentant https://www.microsoft.com.

Exemple 2 - Plage de texte couvrant partiellement un lien hypertexte textuel incorporé

L’URL https://{[www]} est incorporée dans du texte.

Méthode appelée	Résultats
GetText	Retourne la chaîne « www ».
GetEnclosingElement	Retourne l' AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit du contrôle de lien hypertexte.
GetChildren	Retourne null étant donné que la plage de texte ne couvre pas entièrement la chaîne d'URL.

Exemple 3 - Plage de texte couvrant 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.

{The URL} [https://www.microsoft.com](https://www.microsoft.com) is embedded in text.

Méthode appelée	Résultats
GetText	Retourne la chaîne « L'URL ».
GetEnclosingElement	Retourne l' AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l' AutomationElement qui représente le fournisseur de texte lui-même.
Move avec les paramètres de (TextUnit.Word, 1).	Déplace la plage de texte vers « http », 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 du texte.

Image

Exemple 1 - Plage de texte contenant une image incorporée

{L’image est incorporée dans le texte}.

Méthode appelée	Résultats
GetText	Retourne la chaîne « L' est incorporée dans le texte ». Tout texte alternatif associé à l'image n'est pas censé être inclus dans le flux de texte.
GetEnclosingElement	Retourne l' AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l' AutomationElement qui représente le fournisseur de texte lui-même.
GetChildren	Retourne un AutomationElement qui représente le contrôle image.
RangeFromChild où AutomationElement est l'objet retourné par la méthode GetChildren précédente.	Retourne la plage dégénérée qui représente «  ».

Exemple 2 - Plage de texte couvrant 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.

Méthode appelée	Résultats
GetText	Retourne la chaîne « L'image ».
GetEnclosingElement	Retourne l' AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l' AutomationElement qui représente le fournisseur de texte lui-même.
Move avec les paramètres de (TextUnit.Word, 1).	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 ni Move, ni sa valeur de retour (dans ce cas, 1).

Table de charge de travail

Tableau utilisé pour les exemples

Cellule avec l'image	Cellule avec le texte
	X
	Y
Image pour Z	Z

Exemple 1 - Obtenir le conteneur de texte à partir du contenu d'une cellule.

Méthode appelée	Résultats
GetItem avec des paramètres (0,0)	Retourne l' AutomationElement représentant le contenu de la cellule du tableau ; dans ce cas, l'élément est un contrôle de texte.
RangeFromChild où AutomationElement est l'objet retourné par la méthode GetItem précédente.	Retourne la plage qui couvre l’image .
GetEnclosingElement pour l'objet retourné par la méthode RangeFromChild précédente.	Retourne l' AutomationElement représentant la cellule du tableau ; dans ce cas, l'élément est un contrôle de texte qui prend en charge TableItemPattern.
GetEnclosingElement pour l'objet retourné par la méthode GetEnclosingElement précédente.	Retourne l' AutomationElement représentant le tableau.
GetEnclosingElement pour l'objet retourné par la méthode GetEnclosingElement précédente.	Retourne l' AutomationElement représentant le fournisseur de texte lui-même.

Exemple 2 - Obtenir le contenu textuel d'une cellule.

Méthode appelée	Résultats
GetItem avec des paramètres {1,1}.	Retourne l' AutomationElement représentant le contenu de la cellule du tableau ; dans ce cas, l'élément est un contrôle de texte.
RangeFromChild où AutomationElement est l'objet retourné par la méthode GetItem précédente.	Retourne « Y ».

Voir aussi

• TextPattern
• TextPatternRange
• ITextProvider
• ITextRangeProvider
• Accéder à des objets incorporés à l'aide d'UI Automation
• Exposer le contenu d'un tableau à l'aide d'UI Automation
• Accéder au texte à l'aide d'UI Automation
• Exemple de recherche et sélection TextPattern