Benutzerdefinierte Texteingabe

Mit den kernen Text-APIs im Windows.UI.Text.Core-Namespace kann eine Windows-App Texteingaben von jedem auf Windows-Geräten unterstützten Textdienst empfangen. Die APIs ähneln den Text services Framework-APIs , in denen die App nicht über detaillierte Kenntnisse der Textdienste verfügen muss. Dadurch kann die App Text in einer beliebigen Sprache und von jedem Eingabetyp empfangen, z. B. Tastatur, Sprache oder Stift.

Wichtige APIs: Windows.UI.Text.Core, CoreTextEditContext

Gründe für die Verwendung von Core-Text-APIs

Bei vielen Apps reichen die XAML- oder HTML-Textfeld-Steuerelemente für die Texteingabe und -bearbeitung aus. Wenn Ihre App jedoch komplexe Textszenarien wie eine Textverarbeitungs-App verarbeitet, benötigen Sie möglicherweise die Flexibilität eines benutzerdefinierten Textbearbeitungssteuerelements. Sie können die CoreWindow-Tastatur-APIs verwenden, um Ihr Textbearbeitungssteuerelement zu erstellen. Diese bieten jedoch keine Möglichkeit zum Empfangen von kompositionsbasierten Texteingaben, die zur Unterstützung ostasiatischer Sprachen erforderlich sind.

Verwenden Sie stattdessen die Windows.UI.Text.Core-APIs , wenn Sie ein benutzerdefiniertes Textbearbeitungssteuerelement erstellen müssen. Diese APIs sind so konzipiert, dass Sie bei der Verarbeitung von Texteingaben in jeder Sprache sehr flexibel sind und ihnen die Optimale Texterfahrung für Ihre App bieten können. Texteingabe- und Bearbeitungssteuerelemente, die mit den Kerntext-APIs erstellt wurden, können Texteingaben von allen vorhandenen Texteingabemethoden auf Windows-Geräten, von Text Services Framework-basierten Eingabemethoden-Editoren (IMEs) und Handschrift auf PCs auf der WordFlow-Tastatur empfangen (die Autokorrektur, Vorhersage und Diktierfunktion) auf mobilen Geräten bereitstellt.

Aufbau

Es folgt eine einfache Darstellung des Texteingabesystems.

• "Application" stellt eine Windows-App dar, die ein benutzerdefiniertes Bearbeitungssteuerelement hostet, das mithilfe der wichtigsten Text-APIs erstellt wurde.
• Die Windows.UI.Text.Core-APIs erleichtern die Kommunikation mit Textdiensten über Windows. Die Kommunikation zwischen dem Textbearbeitungssteuerelement und den Textdiensten erfolgt in erster Linie über ein CoreTextEditContext-Objekt , das die Methoden und Ereignisse bereitstellt, um die Kommunikation zu erleichtern.

Textbereiche und Auswahl

Bearbeitungssteuerelemente bieten Platz für die Texteingabe, und Benutzer erwarten, text an einer beliebigen Stelle in diesem Bereich zu bearbeiten. Hier erläutern wir das Textpositionierungssystem, das von den Kerntext-APIs verwendet wird und wie Bereiche und Auswahlen in diesem System dargestellt werden.

Anwendungs-Caretposition

Textbereiche, die mit den Kerntext-APIs verwendet werden, werden in Bezug auf Caretpositionen ausgedrückt. Eine "Application Caret Position (ACP)" ist eine nullbasierte Zahl, die die Anzahl der Zeichen vom Anfang des Textstreams unmittelbar vor dem Caret angibt, wie hier gezeigt.

Textbereiche und Auswahl

Textbereiche und Auswahlen werden durch die CoreTextRange-Struktur dargestellt, die zwei Felder enthält:

Feld	Datentyp	Beschreibung
StartCaretPosition	Zahl [JavaScript] | System.Int32 [.NET] | int32 [C++]	Die Startposition eines Bereichs ist der ACP unmittelbar vor dem ersten Zeichen.
EndCaretPosition	Zahl [JavaScript] | System.Int32 [.NET] | int32 [C++]	Die Endposition eines Bereichs ist der ACP unmittelbar nach dem letzten Zeichen.

 

Beispielsweise gibt der Bereich [0, 5] in dem zuvor gezeigten Textbereich das Wort "Hello" an. StartCaretPosition muss immer kleiner oder gleich endCaretPosition sein. Der Bereich [5, 0] ist ungültig.

Einfügemarke

Die aktuelle Caretposition, die häufig als Einfügemarke bezeichnet wird, wird durch Festlegen des Werts "StartCaretPosition " auf " EndCaretPosition" dargestellt.

Nicht zusammenhängende Auswahl

Einige Bearbeitungssteuerelemente unterstützen nicht zusammenhängende Auswahlen. Beispielsweise unterstützen Microsoft Office-App s mehrere beliebige Auswahlen, und viele Quellcode-Editoren unterstützen die Spaltenauswahl. Die Kerntext-APIs unterstützen jedoch keine nicht zusammenhängenden Auswahlen. Bearbeitungssteuerelemente dürfen nur eine einzelne zusammenhängende Auswahl melden, meistens der aktive Unterbereich der nicht zusammenhängenden Auswahl.

Die folgende Abbildung zeigt z. B. einen Textstrom mit zwei nicht zusammenhängenden Auswahlen: [0, 1] und [6, 11], für den das Bearbeitungssteuerelement nur einen Bericht erstellen darf (entweder [0, 1] oder [6, 11]).

Arbeiten mit Text

Die CoreTextEditContext-Klasse ermöglicht den Textfluss zwischen Windows und Bearbeitungssteuerelementen über das TextUpdating-Ereignis, das TextRequested-Ereignis und die NotifyTextChanged-Methode.

Ihr Bearbeitungssteuerelement empfängt Text über TextUpdating-Ereignisse , die generiert werden, wenn Benutzer mit Texteingabemethoden wie Tastaturen, Sprache oder IMEs interagieren.

Wenn Sie Text in Ihrem Bearbeitungssteuerelement ändern, z. B. durch Einfügen von Text in das Steuerelement, müssen Sie Windows durch Aufrufen von NotifyTextChanged benachrichtigen.

Wenn der Textdienst den neuen Text erfordert, wird ein TextRequested-Ereignis ausgelöst. Sie müssen den neuen Text im TextRequested-Ereignishandler angeben.

Akzeptieren von Textaktualisierungen

Ihr Bearbeitungssteuerelement sollte in der Regel Textaktualisierungsanforderungen akzeptieren, da sie den Text darstellen, den der Benutzer eingeben möchte. Im TextUpdating-Ereignishandler werden diese Aktionen von Ihrem Bearbeitungssteuerelement erwartet:

1. Fügen Sie den in CoreTextTextUpdatingEventArgs.Text angegebenen Text an der in CoreTextTextUpdatingEventArgs.Range angegebenen Position ein.
2. Platzieren Sie die Auswahl an der in CoreTextTextUpdatingEventArgs.NewSelection angegebenen Position.
3. Benachrichtigen Sie das System, dass das Update erfolgreich war, indem Sie "CoreTextTextUpdatingEventArgs.Result" auf "CoreTextTextUpdatingResult.Succeeded" festlegen.

Dies ist beispielsweise der Status eines Bearbeitungssteuerelements, bevor der Benutzer "d" eingibt. Die Einfügemarke befindet sich bei [10, 10].

Wenn der Benutzer "d" eingibt, wird ein TextUpdating-Ereignis mit den folgenden CoreTextTextUpdatingEventArgs-Daten ausgelöst:

• Bereich = [10, 10]
• Text = "d"
• NewSelection = [11, 11]

Wenden Sie in Ihrem Bearbeitungssteuerelement die angegebenen Änderungen an, und legen Sie "Result" auf "Erfolgreich" fest. Dies ist der Status des Steuerelements, nachdem die Änderungen angewendet wurden.

Ablehnen von Textaktualisierungen

Manchmal können Sie keine Textaktualisierungen anwenden, da sich der angeforderte Bereich in einem Bereich des Bearbeitungssteuerelements befindet, der nicht geändert werden sollte. In diesem Fall sollten Sie keine Änderungen anwenden. Benachrichtigen Sie stattdessen das System, dass das Update fehlgeschlagen ist, indem Sie "CoreTextTextUpdatingEventArgs.Result" auf "CoreTextTextUpdatingResult.Failed" festlegen.

Betrachten Sie beispielsweise ein Bearbeitungssteuerelement, das nur eine E-Mail-Adresse akzeptiert. Leerzeichen sollten abgelehnt werden, da E-Mail-Adressen keine Leerzeichen enthalten können. Wenn textUpdating-Ereignisse für die Leertaste ausgelöst werden, sollten Sie "Result" einfach auf "Fehler" im Bearbeitungssteuerelement festlegen.

Benachrichtigen von Textänderungen

Manchmal nimmt das Bearbeitungssteuerelement Änderungen an Text vor, z. B. wenn Text eingefügt oder automatisch korrigiert wird. In diesen Fällen müssen Sie die Textdienste über diese Änderungen benachrichtigen, indem Sie die NotifyTextChanged-Methode aufrufen.

Dies ist z. B. der Status eines Bearbeitungssteuerelements, bevor der Benutzer "World" einfüge. Die Einfügemarke befindet sich bei [6, 6].

Der Benutzer führt die Einfügeaktion und das Bearbeitungssteuerelement aus, nachdem die Änderungen angewendet wurden:

In diesem Fall sollten Sie NotifyTextChanged mit den folgenden Argumenten aufrufen:

• modifiedRange = [6, 6]
• newLength = 5
• newSelection = [11, 11]

Ein oder mehrere TextRequested-Ereignisse folgen, die Sie behandeln, um den Text zu aktualisieren, mit dem die Textdienste arbeiten.

Überschreiben von Textaktualisierungen

Möglicherweise möchten Sie in Ihrem Bearbeitungssteuerelement eine Textaktualisierung außer Kraft setzen, um Features für die automatische Korrektur bereitzustellen.

Betrachten Sie z. B. ein Bearbeitungssteuerelement, das ein Korrekturfeature bereitstellt, das Kontraktionen formalisiert. Dies ist der Status des Bearbeitungssteuerelements, bevor der Benutzer die Leertaste eingibt, um die Korrektur auszulösen. Die Einfügemarke befindet sich bei [3, 3].

Der Benutzer drückt die LEERTASTE, und es wird ein entsprechendes TextUpdating-Ereignis ausgelöst. Das Bearbeitungssteuerelement akzeptiert die Textaktualisierung. Dies ist der Status des Bearbeitungssteuerelements für einen kurzen Moment, bevor die Korrektur abgeschlossen ist. Die Einfügemarke befindet sich bei [4, 4].

Außerhalb des TextUpdating-Ereignishandlers nimmt das Bearbeitungssteuerelement die folgende Korrektur vor. Dies ist der Status des Bearbeitungssteuerelements, nachdem die Korrektur abgeschlossen ist. Die Einfügemarke befindet sich bei [5, 5].

In diesem Fall sollten Sie NotifyTextChanged mit den folgenden Argumenten aufrufen:

• modifiedRange = [1, 2]
• newLength = 2
• newSelection = [5, 5]

Ein oder mehrere TextRequested-Ereignisse folgen, die Sie behandeln, um den Text zu aktualisieren, mit dem die Textdienste arbeiten.

Bereitstellen von angeforderten Text

Es ist wichtig, dass Textdienste über den richtigen Text verfügen, um Features wie autokorrektur oder Vorhersage bereitzustellen, insbesondere für Text, der bereits im Bearbeitungssteuerelement vorhanden ist, vom Laden eines Dokuments, z. B. von Text, der vom Bearbeitungssteuerelement eingefügt wird, wie in vorherigen Abschnitten erläutert. Wenn ein TextRequested-Ereignis ausgelöst wird, müssen Sie daher den Text angeben, der sich derzeit im Bearbeitungssteuerelement für den angegebenen Bereich befindet.

Es gibt Zeiten, in denen der Bereich in CoreTextTextRequest einen Bereich angibt, den das Bearbeitungssteuerelement nicht aufnehmen kann. Der Bereich ist z. B. größer als die Größe des Bearbeitungssteuerelements zum Zeitpunkt des TextRequested-Ereignisses, oder das Ende des Bereichs ist außerhalb der Grenzen. In diesen Fällen sollten Sie den bereich zurückgeben, der sinnvoll ist, was in der Regel eine Teilmenge des angeforderten Bereichs ist.

Verwandte Artikel

Beispiele

• Beispiel für ein benutzerdefiniertes Bearbeitungssteuerelement

Archivbeispiele

• Beispiel für die XAML-Textbearbeitung