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

Remarque

Cette documentation est destinée 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 informations les plus récentes 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 n’importe quel é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. Cela diffère de la définition standard, où un élément est créé dans une application et incorporé, ou lié, dans un autre. Si l’objet peut être modifié dans son application d’origine n’est pas pertinent dans le contexte d’UI Automation.

Objets incorporés et arborescence d'automatisation de l'interface utilisateur

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 qu’ils puissent être accessibles via le même modèle que d’autres contrôles dans UI Automation.

Exemple de conteneur de texte avec des objets incorporés table, image et lien hypertexte

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

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

Utilisée conjointement, la TextPattern classe de modèle de contrôle et la TextPatternRange classe exposent des méthodes et des propriétés 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é sous la forme d’un flux de texte unique et continu dans la vue de contrôle et l’affichage de contenu de l’arborescence UI Automation ; les limites d’objet sont ignorées. Si un client UI Automation récupère le texte à des fins de récitation, d’interprétation ou d’analyse d’une certaine manière, 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. Pour ce faire, appelez GetChildren pour obtenir un AutomationElement pour chaque objet incorporé, puis appelez RangeFromChild pour obtenir une plage de texte pour chaque élément. Cette opération est effectuée de manière récursive jusqu’à ce que tout le contenu textuel ait été récupéré.

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

Lorsqu’il est nécessaire de parcourir le contenu d’une plage de texte, une série d’étapes est impliquée en arrière-plan pour que la Move méthode s’exécute correctement.

1. La plage de texte est normalisée ; autrement dit, la plage de texte est réduite à une plage dégénérée au niveau du Start point de terminaison, ce qui rend le End point de terminaison superflu. Cette étape est nécessaire pour supprimer l’ambiguïté dans les situations où une plage de texte s’étend sur les TextUnit limites : par exemple, {The URL https://www.microsoft.com is embedded in text où « { » et « } » sont les points de terminaison de plage de texte.

2. La plage résultante est déplacée vers l’arrière dans le DocumentRange jusqu’au début de la limite demandée TextUnit.

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 l’ajustement d’une plage de texte pour Move() et ExpandToEnclosingUnit()

Scénarios courants

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

Légende des exemples présentés :

{ = Start

} = End

Lien hypertexte

Exemple 1 : plage de texte qui contient un lien hypertexte de texte incorporé

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

Méthode appelée	Résultat
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 précédente GetChildren .	Renvoie la plage qui représente https://www.microsoft.com.

Exemple 2 : plage de texte qui s’étend partiellement sur un lien hypertexte de texte incorporé

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

Méthode appelée	Résultat
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 , car la plage de texte ne couvre pas toute la chaîne d’URL.

Exemple 3 : plage de texte qui couvre partiellement le contenu d’un conteneur de texte. Le conteneur de texte a un lien hypertexte de texte 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ésultat
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 l’étendue de plage de texte sur « http », car le texte du lien hypertexte est composé de mots individuels. Dans ce cas, le lien hypertexte n’est pas traité comme un seul objet. L’URL {[http]} est incorporée dans le texte.

Image

Exemple 1 : plage de texte qui contient une image incorporée

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

Méthode appelée	Résultat
GetText	Retourne la chaîne « L' est incorporée dans le texte ». On ne peut pas s'attendre à ce que tout texte de remplacement associé à l’image soit 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 précédente GetChildren .	Retourne la plage dégénérée qui représente « ».

Exemple 2 : plage de texte qui couvre partiellement le contenu d’un conteneur de texte. Le conteneur de texte a une image incorporée qui ne fait pas partie de la plage de texte.

{L’image} est incorporé dans du texte.

Méthode appelée	Résultat
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 pas Move ou sa valeur de retour (1 dans ce cas).

Tableau

Table utilisée pour des exemples

Cellule avec image	Cellule avec du texte
	X
	O
Image pour Z	Z

Exemple 1 : obtenir le conteneur de texte à partir du contenu d’une cellule.

Méthode appelée	Résultat
GetItem avec des paramètres (0,0)	Renvoie le AutomationElement contenu de la cellule de tableau ; dans ce cas, l’élément est un contrôle de texte.
RangeFromChild où AutomationElement est l’objet retourné par la méthode précédente GetItem .	Retourne la plage qui couvre l'image .
GetEnclosingElement pour l’objet retourné par la méthode précédente RangeFromChild .	Renvoie la AutomationElement représentation de la cellule de 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 précédente GetEnclosingElement .	Retourne l' AutomationElement représentant le tableau.
GetEnclosingElement pour l’objet retourné par la méthode précédente GetEnclosingElement .	Retourne l’élément AutomationElement qui représente le fournisseur de texte lui-même.

Exemple 2 : Obtenir le contenu texte d’une cellule.

Méthode appelée	Résultat
GetItem avec des paramètres de (1,1).	Renvoie le AutomationElement contenu de la cellule de tableau ; dans ce cas, l’élément est un contrôle de texte.
RangeFromChild où AutomationElement est l’objet retourné par la méthode précédente GetItem .	Retourne « Y ».

Voir aussi

• TextPattern
• TextPatternRange
• ITextProvider
• ITextRangeProvider
• Accéder aux objets incorporés à l’aide d’UI Automation
• Exposer le contenu d’une table à l’aide d’UI Automation
• Accéder au texte à l’aide d’UI Automation
• Exemple de recherche et de sélection TextPattern