Übersicht über TextPattern und eingebettete ObjekteTextPattern and Embedded Objects Overview

Hinweis

Diese Dokumentation ist für .NET Framework-Entwickler vorgesehen, die die verwalteten BenutzeroberflächenautomatisierungUI Automation-Klassen verwenden möchten, die im System.Windows.Automation-Namespace definiert sind.This documentation is intended for .NET Framework developers who want to use the managed BenutzeroberflächenautomatisierungUI Automation classes defined in the System.Windows.Automation namespace. Die neuesten Informationen zu BenutzeroberflächenautomatisierungUI Automationfinden Sie unter Windows Automation-API: Automatisierungder Benutzeroberfläche.For the latest information about BenutzeroberflächenautomatisierungUI Automation, see Windows Automation API: UI Automation.

In dieser Übersicht wird beschrieben, wie von der Microsoft-UI-AutomatisierungMicrosoft UI Automation eingebettete Objekte oder untergeordnete Elemente innerhalb eines Textdokuments oder Containers verfügbar gemacht werden.This overview describes how Microsoft-UI-AutomatisierungMicrosoft UI Automation exposes embedded objects, or child elements, within a text document or container.

Eingebettete Objekte sind in der BenutzeroberflächenautomatisierungUI Automation Elemente mit Nicht-Textgrenzen, z. B. Bilder, Links, Tabellen oder Dokumenttypen wie Microsoft ExcelMicrosoft Excel -Arbeitsblätter oder Microsoft Windows MediaMicrosoft Windows Media -Dateien.In BenutzeroberflächenautomatisierungUI Automation an embedded object is any element that has non-textual boundaries; for example, an image, hyperlink, table, or document type such as an Microsoft ExcelMicrosoft Excel spreadsheet or Microsoft Windows MediaMicrosoft Windows Media file. Dies weicht von der Standarddefinition ab, in der Elemente in einer Anwendung erstellt und einer anderen eingebettet bzw. mit einer anderen verknüpft sind.This differs from the standard definition, where an element is created in one application and embedded, or linked, within another. Ob das Objekt innerhalb der ursprünglichen Anwendung bearbeitet werden kann, ist im Kontext der BenutzeroberflächenautomatisierungUI Automationnicht relevant.Whether the object can be edited within its original application is irrelevant in the context of BenutzeroberflächenautomatisierungUI Automation.

Eingebettete Objekte und die Benutzeroberflächenautomatisierungs-StrukturEmbedded Objects and the UI Automation Tree

Eingebettete Objekte werden als einzelne Elemente innerhalb der Steuerelementansicht der BenutzeroberflächenautomatisierungUI Automation -Struktur behandelt.Embedded objects are treated as individual elements within the control view of the BenutzeroberflächenautomatisierungUI Automation tree. Sie werden als untergeordnete Elemente des Textcontainers verfügbar gemacht, sodass über dasselbe Model wie bei anderen Steuerelementen in der BenutzeroberflächenautomatisierungUI Automationauf diese zugegriffen werden kann.They are exposed as children of the text container so that they can be accessed through the same model as other controls in BenutzeroberflächenautomatisierungUI Automation.

Eingebettete Tabelle mit Bild in einem Text ContainerEmbedded Table with Image in a Text Container
Beispiel für einen Textcontainer mit Tabelle, Bild und eingebetteten LinkobjektenExample of a Text Container with Table, Image, and Hyperlink Embedded Objects

Inhaltsansicht für das vorherige BeispielContent view for the preceding example
Beispiel der Inhaltsansicht für einen Teil des vorherigen TextcontainersExample of the Content View for a Portion of the Preceding Text Container

Verfügbarmachen von eingebetteten Objekten mithilfe von TextPattern und TextPatternRangeExpose Embedded Objects Using TextPattern and TextPatternRange

Die TextPattern -Steuerelementmuster-Klasse wird in Verbindung mit der TextPatternRange -Klasse verwendet, um Methoden und Eigenschaften verfügbar zu machen, die das Navigieren und Abfragen von eingebetteten Objekten erleichtern.Used in conjunction, the TextPattern control pattern class and the TextPatternRange class expose methods and properties that facilitate navigation and querying of embedded objects.

Der Textinhalt (oder innere Text) eines Textcontainers und ein eingebettetes Objekt, z. B. ein Link oder eine Tabellenzelle, werden in der Steuerelementansicht und der Inhaltsansicht der BenutzeroberflächenautomatisierungUI Automation -Struktur als einzelner, kontinuierlicher Textstream verfügbar gemacht, Objektgrenzen werden dabei ignoriert.The textual content (or inner text) of a text container and an embedded object, such as a hyperlink or table cell, is exposed as a single, continuous text stream in both the control view and the content view of the BenutzeroberflächenautomatisierungUI Automation tree; object boundaries are ignored. Wenn ein Benutzeroberflächenautomatisierungs-Client den Text abruft, um ihn zu lesen, zu interpretieren oder zu analysieren, sollte der Textbereich auf bestimmte Fälle überprüft werden, z. B. auf Tabellen mit Textinhalt oder andere eingebettete Objekte.If a UI Automation client is retrieving the text for the purpose of reciting, interpreting, or analyzing in some manner, the text range should be checked for special cases, such as a table with textual content or other embedded objects. Dies geschieht durch Aufrufen von GetChildren , um ein AutomationElement für alle eingebetteten Elemente abzurufen, und anschließend durch Aufrufen von RangeFromChild , um einen Textbereich für alle Elemente abzurufen.This can be accomplished by calling GetChildren to obtain an AutomationElement for each embedded object and then calling RangeFromChild to obtain a text range for each element. Dies wird rekursiv ausgeführt, bis der gesamte Textinhalt abgerufen wurde.This is done recursively until all textual content has been retrieved.

Text Bereiche, die sich von eingebetteten Objekten überspannen.Text ranges spanned by embedded objects.
Beispiel für einen Textstream mit eingebetteten Objekten und deren BereichsabschnittenExample of a text stream with embedded objects and their range spans

Wenn der Inhalt eines Textbereichs durchlaufen werden muss, ist eine Reihe von Hintergrundschritten erforderlich, um die Move -Methode erfolgreich auszuführen.When it is necessary to traverse the content of a text range, a series of steps are involved behind the scenes in order for the Move method to execute successfully.

  1. Der Textbereich ist normalisiert. Dies bedeutet, dass dieser auf einen degenerierten Bereich am Start -Endpunkt reduziert ist, wodurch der End -Endpunkt überflüssig wird.The text range is normalized; that is, the text range is collapsed to a degenerate range at the Start endpoint, which makes the End endpoint superfluous. Dieser Schritt ist erforderlich, um Mehrdeutigkeit in Situationen zu beseitigen, in TextUnit denen ein Textbereich Grenzen {The URL https://www.microsoft.com is embedded in text umfasst, z. b. wobei "{" und "}" die Endpunkte des Text Bereichs sind.This step is necessary to remove ambiguity in situations where a text range spans TextUnit boundaries: for example, {The URL https://www.microsoft.com is embedded in text where "{" and "}" are the text range endpoints.

  2. Der resultierende Bereich wird im DocumentRange zurück an den Anfang der angeforderten TextUnit -Grenze verschoben.The resulting range is moved backward in the DocumentRange to the beginning of the requested TextUnit boundary.

  3. Der Bereich wird um die angeforderte Anzahl von DocumentRange -Grenzen nach vorne oder nach hinten im TextUnit verschoben.The range is moved forward or backward in the DocumentRange by the requested number of TextUnit boundaries.

  4. Anschließend wird der Bereich von einem degenerierten Bereichszustand erweitert, indem der End -Endpunkt um eine angeforderte TextUnit -Grenze verschoben wird.The range is then expanded from a degenerate range state by moving the End endpoint by one requested TextUnit boundary.

Bereichs Anpassungen durch Verschieben & expandumeinclosingunitRange adjustments by Move & ExpandToEnclosingUnit
Beispiele für die Anpassung eines Textbereichs für Move() und ExpandToEnclosingUnit()Examples of how a text range is adjusted for Move() and ExpandToEnclosingUnit()

Häufige SzenarienCommon Scenarios

In den folgenden Abschnitten sind Beispiele für die häufigsten Szenarien dargestellt, in denen eingebettete Objekte verwendet werden.The following sections present examples of the most common scenarios that involve embedded objects.

Legende für die dargestellten Beispiele:Legend for the examples shown:

{ = Start{ = Start

} = End} = End

Beispiel 1: Ein Textbereich, der einen eingebetteten Textlink enthältExample 1 - A text range that contains an embedded text hyperlink

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

Aufgerufene MethodeMethod called ErgebnisResult
GetText Gibt die Zeichenfolge The URL https://www.microsoft.com is embedded in text zurück.Returns the string The URL https://www.microsoft.com is embedded in text.
GetEnclosingElement Gibt das den Textbereich einschließende, innerste AutomationElement zurück, in diesem Fall das AutomationElement , das den Textanbieter darstellt.Returns the innermost AutomationElement that encloses the text range; in this case, the AutomationElement that represents the text provider itself.
GetChildren Gibt ein AutomationElement zurück, das das Linksteuerelement darstellt.Returns an AutomationElement representing the hyperlink control.
RangeFromChild , wobei AutomationElement das von der vorherigen GetChildren -Methode zurückgegebene Objekt ist.RangeFromChild where AutomationElement is the object returned by the previous GetChildren method. Gibt den Bereich zurück, der https://www.microsoft.com"" darstellt.Returns the range that represents "https://www.microsoft.com".

Beispiel 2: Ein Textbereich, der einen eingebetteten Textlink nur teilweise enthältExample 2 - A text range that partially spans an embedded text hyperlink

Die URL https://{[www]} ist in den Text eingebettet.The URL https://{[www]} is embedded in text.

Aufgerufene MethodeMethod called ErgebnisResult
GetText Gibt die Zeichenfolge „www“ zurück.Returns the string "www".
GetEnclosingElement Gibt das den Textbereich einschließende, innerste AutomationElement zurück, in diesem Fall das Linksteuerelement.Returns the innermost AutomationElement that encloses the text range; in this case, the hyperlink control.
GetChildren Gibt null zurück, da der Textbereich nicht die gesamte URL-Zeichenfolge umfasst.Returns null since the text range doesn't span the entire URL string.

Beispiel 3: ein Textbereich, der den Inhalt eines Text Containers teilweise umfasst. Der Text Container enthält einen eingebetteten Text Hyperlink, der nicht Teil des Text Bereichs ist.Example 3 - A text range that partially spans the content of a text container. The text container has an embedded text hyperlink that is not part of the text range.

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

Aufgerufene MethodeMethod called ErgebnisResult
GetText Gibt die Zeichenfolge „Die URL“ zurück.Returns the string "The URL".
GetEnclosingElement Gibt das den Textbereich einschließende, innerste AutomationElement zurück, in diesem Fall das AutomationElement , das den Textanbieter darstellt.Returns the innermost AutomationElement that encloses the text range; in this case, the AutomationElement that represents the text provider itself.
Move mit den Parametern (TextUnit.Word, 1).Move with parameters of (TextUnit.Word, 1). Verschiebt den Textbereichsabschnitt nach „http“, da der Text des Links aus einzelnen Wörtern besteht.Moves the text range span to "http" since the text of the hyperlink is comprised of individual words. In diesem Fall wird der Link nicht als einzelnes Objekt behandelt.In this case, the hyperlink is not treated as a single object.

Die URL {[http]} ist in den Text eingebettet.The URL {[http]} is embedded in text.

BildImage

Beispiel 1: Ein Textbereich, der ein eingebettetes Bild enthältExample 1 - A text range that contains an embedded image

{Das Image Embedded Image example ist in Text eingebettet}.{The image Embedded Image Example is embedded in text}.

Aufgerufene MethodeMethod called ErgebnisResult
GetText Gibt die Zeichenfolge „Das Bild ist in den Text eingebettet“ zurück.Returns the string "The is embedded in text". Ein dem Bild zugeordneter Alternativtext (ALT) kann nicht im Textstream miteingeschlossen werden.Any ALT text associated with the image cannot be expected to be included in the text stream.
GetEnclosingElement Gibt das den Textbereich einschließende, innerste AutomationElement zurück, in diesem Fall das AutomationElement , das den Textanbieter darstellt.Returns the innermost AutomationElement that encloses the text range; in this case, the AutomationElement that represents the text provider itself.
GetChildren Gibt ein AutomationElement zurück, das das Bildsteuerelement darstellt.Returns an AutomationElement representing the image control.
RangeFromChild , wobei AutomationElement das von der vorherigen GetChildren -Methode zurückgegebene Objekt ist.RangeFromChild where AutomationElement is the object returned by the previous GetChildren method. Gibt den degenerierten Bereich zurück, der "eingebettetes Bildbeispiel" darstellt.Returns the degenerate range that represents "Embedded Image Example".

Beispiel 2: ein Textbereich, der den Inhalt eines Text Containers teilweise umfasst. Der Text Container verfügt über ein eingebettetes Bild, das nicht Teil des Text Bereichs ist.Example 2 - A text range that partially spans the content of a text container. The text container has an embedded image that is not part of the text range.

{Das Image} Beispiel für eingebettetes Bild ist in den Text eingebettet.{The image} Embedded Image Example is embedded in text.

Aufgerufene MethodeMethod called ErgebnisResult
GetText Gibt die Zeichenfolge „Das Bild“ zurück.Returns the string "The image".
GetEnclosingElement Gibt das den Textbereich einschließende, innerste AutomationElement zurück, in diesem Fall das AutomationElement , das den Textanbieter darstellt.Returns the innermost AutomationElement that encloses the text range; in this case, the AutomationElement that represents the text provider itself.
Move mit den Parametern (TextUnit.Word, 1).Move with parameters of (TextUnit.Word, 1). Verschiebt den Textbereichsabschnitt nach „ist“.Moves the text range span to "is ". Da nur textbasierte eingebettete Objekte als Teil des Textstreams betrachtet werden, hat das Bild in diesem Beispiel keine Auswirkungen auf das Move-Objekt oder dessen Rückgabewert (in diesem Fall 1).Because only text-based embedded objects are considered part of the text stream, the image in this example does not affect Move or its return value (1 in this case).

TabelleTable

Für Beispiele verwendete TabelleTable used for examples

Zelle mit BildCell with Image Zelle mit TextCell with Text
Beispiel für eingebettetes BildEmbedded Image Example XX
Eingebettetes Bildbeispiel 2Embedded Image Example 2 JY
Eingebettetes Bildbeispiel 3Embedded Image Example 3

Bild für ZImage for Z
ZZ

Beispiel 1: Abrufen des Textcontainers aus dem Inhalt einer ZelleExample 1 - Get the text container from the content of a cell.

Aufgerufene MethodeMethod Called ErgebnisResult
GetItem mit den Parametern (0,0)GetItem with parameters (0,0) Gibt das AutomationElement zurück, das den Inhalt der Tabellenzelle darstellt; in diesem Fall ist das Element ein Textsteuerelement.Returns the AutomationElement representing the content of the table cell; in this case, the element is a text control.
RangeFromChild , wobei AutomationElement das von der vorherigen GetItem -Methode zurückgegebene Objekt ist.RangeFromChild where AutomationElement is the object returned by the previous GetItem method. Gibt den Bereich zurück, der das Bildbeispiel(./media/uia-textpattern-embedded-objects-overview-imageexample.PNG "UIA_TextPattern_Embedded_Objects_Overview_ImageExample")für Bild ![eingebettete Bilder]umfasst.Returns the range that spans the image Embedded Image Example.
GetEnclosingElement für das von der vorherigen RangeFromChild -Methode zurückgegebene Objekt.GetEnclosingElement for the object returned by the previous RangeFromChild method. Gibt das AutomationElement zurück, das die Tabellenzelle darstellt; in diesem Fall ist das Element ein Textsteuerelement, das TableItemPattern unterstützt.Returns the AutomationElement representing the table cell; in this case, the element is a text control that supports TableItemPattern.
GetEnclosingElement für das von der vorherigen GetEnclosingElement -Methode zurückgegebene Objekt.GetEnclosingElement for the object returned by the previous GetEnclosingElement method. Gibt das AutomationElement zurück, das die Tabelle darstellt.Returns the AutomationElement representing the table.
GetEnclosingElement für das von der vorherigen GetEnclosingElement -Methode zurückgegebene Objekt.GetEnclosingElement for the object returned by the previous GetEnclosingElement method. Gibt das AutomationElement zurück, das den Textanbieter darstellt.Returns the AutomationElement that represents the text provider itself.

Beispiel 2: Abrufen des Textinhalts einer ZelleExample 2 - Get the text content of a cell.

Aufgerufene MethodeMethod Called ErgebnisResult
GetItem mit den Parametern {1,1}.GetItem with parameters of (1,1). Gibt das AutomationElement zurück, das den Inhalt der Tabellenzelle darstellt; in diesem Fall ist das Element ein Textsteuerelement.Returns the AutomationElement representing the content of the table cell; in this case, the element is a text control.
RangeFromChild , wobei AutomationElement das von der vorherigen GetItem -Methode zurückgegebene Objekt ist.RangeFromChild where AutomationElement is the object returned by the previous GetItem method. Gibt „Y“ zurück.Returns "Y".

Siehe auchSee also