Eingabe

Mit der .NET Multi-Platform App UI (.NET MAUI) Entry können Sie eine einzelne Textzeile eingeben und bearbeiten. Darüber hinaus kann das Feld Entry als Kennwortfeld verwendet werden.

Entry definiert die folgenden Eigenschaften:

• ClearButtonVisibility vom Typ ClearButtonVisibility, steuert, ob eine Schaltfläche zum Löschen angezeigt wird, mit der der Benutzer den Text löschen kann. Der Standardwert dieser Eigenschaft stellt sicher, dass keine Schaltfläche zum Löschen angezeigt wird.
• HorizontalTextAlignment, vom Typ TextAlignment, definiert die horizontale Ausrichtung des Textes.
• IsPassword, vom Typ bool, gibt an, ob der Eintrag text visuell verdeckt werden soll.
• ReturnCommand, vom Typ ICommand, definiert den Befehl, der ausgeführt werden soll, wenn die Eingabetaste gedrückt wird.
• ReturnCommandParameter, vom Typ object, gibt den Parameter für den ReturnCommand an.
• ReturnType, vom Typ ReturnType, gibt die Darstellung der Rückgabeschaltfläche an.
• VerticalTextAlignment vom Typ TextAlignment: Vertikale Ausrichtung des Texts im Suchfeld.

Diese Eigenschaften werden von BindableProperty-Objekten unterstützt, was bedeutet, dass sie Ziele von Datenbindungen sein können und formatiert werden können.

Darüber hinaus definiert Entry ein Completed-Ereignis, das ausgelöst wird, wenn der Benutzer den Text im Entry mit der Eingabetaste abschließt.

Entry leitet sich von der Klasse InputView ab, von der sie die folgenden Eigenschaften erbt:

• CharacterSpacing, vom Typ double, legt den Abstand zwischen den Zeichen im eingegebenen Text fest.
• CursorPosition, vom Typ int, definiert die Position des Cursors innerhalb des Editors.
• FontAttributes, vom Typ FontAttributes, bestimmt die Textformatvorlage.
• FontAutoScalingEnabled, vom Typ bool, definiert, ob der Text Skalierungspräferenzen im Betriebssystem entspricht. Der Standardwert dieser Eigenschaft ist true.
• FontFamily, vom Typ string, definiert die Schriftartfamilie.
• FontSize, vom Typ double, definiert den Schriftgrad.
• IsReadOnly, vom Typ bool, legt fest, ob der Benutzer daran gehindert werden soll, Text zu ändern. Der Standardwert dieser Eigenschaft ist false.
• IsSpellCheckEnabled, vom Typ bool, steuert, ob die Rechtschreibprüfung aktiviert ist.
• IsTextPredictionEnabled, vom Typ bool, steuert, ob Textvorhersage und automatische Textkorrektur aktiviert ist.
• Keyboard, vom Typ Keyboard, gibt die Softeingabetastatur an, die beim Eingeben von Text angezeigt wird.
• MaxLength, vom Typ int, definiert die maximale Eingabelänge.
• Placeholder, vom Typ string, definiert den Text, der angezeigt wird, wenn das Steuerelement leer ist.
• PlaceholderColor, vom Typ Color, definiert die Farbe des Platzhaltertextes.
• SelectionLength, vom Typ int, stellt die Länge des markierten Texts innerhalb des Steuerelements dar.
• Text, vom Typ string, definiert den in das Steuerelement eingegebenen Text.
• TextColor, vom Typ Color, definiert die Farbe des eingegebenen Textes.
• TextTransform, vom Typ TextTransform, gibt die Schreibweise des eingegebenen Textes an.

Diese Eigenschaften werden von BindableProperty-Objekten unterstützt, was bedeutet, dass sie Ziele von Datenbindungen sein können und formatiert werden können.

Darüber hinaus definiert InputView ein TextChanged-Ereignis, das ausgelöst wird, wenn sich der Text in Entry ändert. Das TextChangedEventArgs-Objekt, das das TextChanged-Ereignis begleitet, hat die Eigenschaften NewTextValue und OldTextValue, die den neuen bzw. alten Text angeben.

Für Informationen über die Angabe von Schriftarten auf einem Entry, siehe Schriftarten.

Erstellen eines Eintrags

Das folgende Beispiel zeigt, wie ein Entry erstellt wird.

<Entry x:Name="entry"
       Placeholder="Enter text"
       TextChanged="OnEntryTextChanged"
       Completed="OnEntryCompleted" />

Der entsprechende C#-Code lautet:

Entry entry = new Entry { Placeholder = "Enter text" };
entry.TextChanged += OnEntryTextChanged;
entry.Completed += OnEntryCompleted;

Der folgende Screenshot zeigt das Ergebnis Entry auf Android:

Hinweis

Unter iOS kann die Softeingabetastatur ein Texteingabefeld abdecken, wenn sich das Feld am unteren Rand des Bildschirms befindet, wodurch es schwierig ist, Text einzugeben. In einer .NET MAUI iOS-App scrollen Seiten jedoch automatisch, wenn die Softeingabetastatur ein Texteingabefeld abdecken würde, sodass sich das Feld über der Bildschirmtastatur befindet. Die KeyboardAutoManagerScroll.Disconnect-Methode im Microsoft.Maui.Platform-Namespace kann aufgerufen werden, um dieses Standardverhalten zu deaktivieren. Die KeyboardAutoManagerScroll.Connect-Methode kann aufgerufen werden, um das Verhalten erneut zu aktivieren, nachdem sie deaktiviert wurde.

Auf eingegebenen Text kann durch Lesen der Eigenschaft Text zugegriffen werden, und die Ereignisse TextChanged und Completed signalisieren, dass der Text geändert oder vervollständigt wurde.

Das Ereignis TextChanged wird ausgelöst, wenn sich der Text in Entry ändert, und TextChangedEventArgs liefert über die Eigenschaften OldTextValue und NewTextValue den Text vor und nach der Änderung:

void OnEntryTextChanged(object sender, TextChangedEventArgs e)
{
    string oldText = e.OldTextValue;
    string newText = e.NewTextValue;
    string myText = entry.Text;
}

Das Completed-Ereignis wird ausgelöst, wenn der Benutzer die Eingabe beendet hat, indem die EINGABETASTE auf der Tastatur oder die TAB-TASTE unter Windows gedrückt hat. Der Handler für das Ereignis ist ein generischer Ereignishandler:

void OnEntryCompleted(object sender, EventArgs e)
{
   string text = ((Entry)sender).Text;
}

Nachdem das Completed-Ereignis ausgelöst wurde, wird jedes ICommand, das durch die ReturnCommand-Eigenschaft angegeben wurde, ausgeführt, wobei das object, das durch die ReturnCommandParameter-Eigenschaft angegeben wurde, an das ReturnCommand übergeben wird.

Hinweis

Die Klasse VisualElement, die sich in der Vererbungshierarchie Entry befindet, hat auch Focused- und Unfocused-Ereignisse.

Zeichenabstand

Der Zeichenabstand kann auf ein Entry angewendet werden, indem die Eigenschaft CharacterSpacing auf einen double-Wert gesetzt wird:

<Entry ...
       CharacterSpacing="10" />

Dies hat zur Folge, dass die Zeichen im Text, der von der Entry angezeigt wird, einen Abstand von CharacterSpacing geräteunabhängigen Einheiten aufweisen.

Hinweis

Der Wert der Eigenschaft CharacterSpacing wird auf den Text angewendet, der durch die Eigenschaften Text und Placeholder angezeigt wird.

Begrenzen von Eingabelängen

Die MaxLength-Eigenschaft begrenzt die für Entry zulässige Eingabelänge. Diese Eigenschaft sollte auf eine positive ganze Zahl festgelegt werden:

<Entry ...
       MaxLength="10" />

Ein MaxLength-Eigenschaftswert von 0 bedeutet, dass keine Eingabe zulässig ist, und ein Wert von int.MaxValue, der der Standardwert für Entry ist, bedeutet, dass es keine effektive Begrenzung für die Anzahl der Zeichen gibt, die eingegeben werden können.

Festlegen der Cursorposition und der Textauswahllänge

Die CursorPosition-Eigenschaft kann verwendet werden, um die Position zurückzugeben oder festzulegen, an der das nächste Zeichen in die in der Text-Eigenschaft gespeicherte Zeichenkette eingefügt werden soll:

<Entry Text="Cursor position set"
       CursorPosition="5" />

Der Standardwert der Eigenschaft CursorPosition ist 0, was bedeutet, dass der Text am Anfang der Entry eingefügt wird.

Darüber hinaus kann die Eigenschaft SelectionLength verwendet werden, um die Länge der Textauswahl innerhalb des Entry zurückzugeben oder festzulegen:

<Entry Text="Cursor position and selection length set"
       CursorPosition="2"
       SelectionLength="10" />

Der Standardwert der Eigenschaft SelectionLength ist 0, was bedeutet, dass kein Text ausgewählt ist.

Anzeigen einer Schaltfläche zum Löschen

Die ClearButtonVisibility-Eigenschaft kann verwendet werden, um zu steuern, ob ein Entry eine Schaltfläche zum Löschen anzeigt, mit der der Benutzer den Text löschen kann. Diese Eigenschaft sollte auf einen ClearButtonVisibility-Enumerationsmember festgelegt werden:

• Never gibt an, dass nie eine Schaltfläche zum Löschen angezeigt wird. Dies ist der Standardwert der ClearButtonVisibility-Eigenschaft.
• WhileEditing zeigt an, dass in der Entry eine leere Schaltfläche angezeigt wird, während sie den Fokus und Text hat.

Im folgenden Beispiel wird die Festlegung der Eigenschaft gezeigt:

<Entry Text=".NET MAUI"
       ClearButtonVisibility="WhileEditing" />

Der folgende Screenshot zeigt eine Entry auf Android mit aktivierter Schaltfläche „Löschen“:

Transformieren von Text

Ein Entry kann die Schreibweise seines in der Text-Eigenschaft gespeicherten Textes ändern, indem er die TextTransform-Eigenschaft auf einen Wert der TextTransform-Enumeration setzt. Diese Enumeration weist vier Werte auf:

• None gibt an, dass der Text nicht transformiert wird.
• Default gibt an, dass das plattformspezifische Standardverhalten verwendet wird. Dies ist der Standardwert der Eigenschaft TextTransform.
• Lowercase gibt an, dass der Text in Kleinbuchstaben umgewandelt wird.
• Uppercase gibt an, dass der Text in Großbuchstaben umgewandelt wird.

Das folgende Beispiel zeigt das Transformieren von Text in Großbuchstaben:

<Entry Text="This text will be displayed in uppercase."
       TextTransform="Uppercase" />

Obskurer Texteintrag

Entry bietet die Eigenschaft IsPassword, die eingegebenen Text optisch verdeckt, wenn sie auf true gesetzt ist:

<Entry IsPassword="true" />

Der folgende Screenshot zeigt ein Entry, dessen Eingabe unkenntlich gemacht wurde:

Anpassen der Tastatur

Die Bildschirmtastatur, die angezeigt wird, wenn Benutzer mit einem Entry interagieren, kann programmatisch über die Keyboard-Eigenschaft auf eine der folgenden Eigenschaften der Keyboard-Klasse eingestellt werden:

• Chat: wird zum Schreiben von Texten verwendet und in Situationen, in denen Emojis nützlich sind.
• Default: die Standardtastatur.
• Email: wird beim Eingeben von E-Mail-Adressen verwendet.
• Numeric: wird beim Eingeben von Zahlen verwendet.
• Plain: wird beim Eingeben von Text verwendet, ohne Angabe von KeyboardFlags.
• Telephone: wird beim Eingeben von Telefonnummern verwendet.
• Text: wird beim Eingeben von Text verwendet.
• Url: Wird beim Eingeben von Dateipfaden und Webadressen verwendet.

Das folgende Beispiel zeigt die Einstellung der Eigenschaft Keyboard:

<Entry Keyboard="Chat" />

Die Keyboard-Klasse verfügt auch über eine Create-Factorymethode, die zum Anpassen einer Tastatur durch Festlegen des Verhaltens für Groß-/Kleinschreibung, Rechtschreibprüfung und Vorschläge verwendet werden kann. KeyboardFlags-Enumerationswerte werden als Argumente der Methode festgelegt, wobei das benutzerdefinierte Keyboard zurückgegeben wird. Die KeyboardFlags-Enumeration verfügt über folgende Werte:

• None: der Tastatur werden keine Features hinzugefügt.
• CapitalizeSentence: gibt an, dass der erste Buchstabe des ersten Worts jedes Satzes automatisch groß geschrieben wird.
• Spellcheck: gibt an, dass die Rechtschreibprüfung für den eingegebenen Text durchgeführt wird.
• Suggestions: gibt an, dass Wortvervollständigungen für den eingegebenen Text angeboten werden.
• CapitalizeWord: gibt an, dass der erste Buchstabe von jedem Wort automatisch groß geschrieben wird.
• CapitalizeCharacter: gibt an, dass jedes Zeichen automatisch groß geschrieben wird.
• CapitalizeNone: gibt an, dass keine automatische Großschreibung erfolgt.
• All: gibt an, dass für den eingegebenen Text die Rechtschreibprüfung, die Vervollständigung von Wörtern und die Großschreibung am Satzanfang erfolgen.

Das folgende XAML-Codebeispiel zeigt, wie Sie den Standardwert für Keyboard anpassen können, um Wortvervollständigungen anzubieten und jedes eingegebene Zeichen groß zu schreiben:

<Entry Placeholder="Enter text here">
    <Entry.Keyboard>
        <Keyboard x:FactoryMethod="Create">
            <x:Arguments>
                <KeyboardFlags>Suggestions,CapitalizeCharacter</KeyboardFlags>
            </x:Arguments>
        </Keyboard>
    </Entry.Keyboard>
</Entry>

Der entsprechende C#-Code lautet:

Entry entry = new Entry { Placeholder = "Enter text here" };
entry.Keyboard = Keyboard.Create(KeyboardFlags.Suggestions | KeyboardFlags.CapitalizeCharacter);

Anpassen der Eingabetaste

Das Erscheinungsbild der Eingabetaste auf der Bildschirmtastatur, die angezeigt wird, wenn ein Entry den Fokus hat, kann angepasst werden, indem die Eigenschaft ReturnType auf einen Wert der Enumeration ReturnType gesetzt wird:

• Default – gibt an, dass kein bestimmter Rückgabeschlüssel erforderlich ist und dass der Plattformstandard verwendet wird.
• Done – gibt einen „Fertig“-Rückgabeschlüssel an.
• Go – gibt einen „Go“-Rückgabeschlüssel an.
• Next – gibt einen „Next“-Rückgabeschlüssel an.
• Search – gibt einen „Search“-Rückgabeschlüssel an.
• Send – gibt eine „Senden“-Rückgabetaste an.

Das folgende XAML-Beispiel zeigt, wie die Return-Taste gesetzt wird:

<Entry ReturnType="Send" />

Hinweis

Die genaue Darstellung des Rückgabeschlüssels hängt von der Plattform ab. Unter iOS ist die Rückgabetaste eine textbasierte Schaltfläche. Unter Android und Windows ist die Rückgabetaste jedoch eine symbolbasierte Schaltfläche.

Wenn die EINGABETASTE gedrückt wird, wird das Completed-Ereignis ausgelöst, und alle ICommand, die durch die Eigenschaft ReturnCommand angegeben werden, werden ausgeführt. Darüber hinaus wird jedes object, das durch die ReturnCommandParameter-Eigenschaft angegeben wird, als Parameter an ICommand übergeben. Weitere Informationen zu Befehlen finden Sie unter Befehlsübersicht.

Ausblenden und Anzeigen der Bildschirmtastatur

Die Klasse SoftInputExtensions im Namespace Microsoft.Maui bietet eine Reihe von Erweiterungsmethoden, die die Interaktion mit der Bildschirmtastatur auf Steuerelementen unterstützen, die die Texteingabe unterstützen. Die Klasse enthält die folgenden Methoden:

• IsSoftInputShowing, um festzustellen, ob das Gerät derzeit die Bildschirmtastatur anzeigt.
• HideSoftInputAsync, wodurch versucht wird, die Soft-Eingabe-Tastatur auszublenden, wenn sie gerade angezeigt wird.
• ShowSoftInputAsync, wodurch versucht wird, die Soft-Eingabe-Tastatur einzublenden, wenn sie derzeit verborgen ist.

Das folgende Beispiel zeigt, wie man die Bildschirmtastatur auf einem Entry mit dem Namen entry ausblendet, wenn sie gerade angezeigt wird:

if (entry.IsSoftInputShowing())
    await entry.HideSoftInputAsync(System.Threading.CancellationToken.None);

Aktivieren und Deaktivieren der Rechtschreibprüfung

Die IsSpellCheckEnabled-Eigenschaft steuert, ob die Rechtschreibprüfung aktiviert ist. Standardmäßig ist die Eigenschaft auf true eingestellt. Wenn der Benutzer Text eingibt, werden Rechtschreibfehler angegeben.

Für einige Texteingabeszenarien, wie z. B. die Eingabe eines Benutzernamens, ist die Rechtschreibprüfung jedoch nachteilig und sollte durch Setzen der Eigenschaft IsSpellCheckEnabled auf false deaktiviert werden:

<Entry ... IsSpellCheckEnabled="false" />

Hinweis

Wenn die Eigenschaft IsSpellCheckEnabled auf false gesetzt ist und keine benutzerdefinierte Tastatur verwendet wird, wird die native Rechtschreibprüfung deaktiviert. Wenn jedoch eine Keyboard festgelegt wurde, die die Rechtschreibprüfung deaktiviert, wie z. B. Keyboard.Chat, wird die Eigenschaft IsSpellCheckEnabled ignoriert. Daher kann die Eigenschaft nicht verwendet werden, um die Rechtschreibprüfung für einen Keyboard zu aktivieren, der sie ausdrücklich deaktiviert.

Aktivieren und Deaktivieren der Textvorhersage

Die IsTextPredictionEnabled-Eigenschaft steuert, ob Textvorhersage und automatische Textkorrektur aktiviert sind. Standardmäßig ist die Eigenschaft auf true eingestellt. Während der Benutzer Text eingibt, werden Wortvorhersagen dargestellt.

Für einige Texteingabeszenarien, wie z. B. die Eingabe eines Benutzernamens, bieten die Textvorhersage und die automatische Textkorrektur jedoch ein negatives Erlebnis und sollten durch Setzen der Eigenschaft IsTextPredictionEnabled auf false deaktiviert werden:

<Entry ... IsTextPredictionEnabled="false" />

Hinweis

Wenn die Eigenschaft IsTextPredictionEnabled auf false gesetzt ist und keine benutzerdefinierte Tastatur verwendet wird, sind die Textvorhersage und die automatische Textkorrektur deaktiviert. Wenn jedoch eine Keyboard gesetzt wurde, die die Textvorhersage deaktiviert, wird die Eigenschaft IsTextPredictionEnabled ignoriert. Daher kann die Eigenschaft nicht verwendet werden, um die Textvorhersage für einen Keyboard zu aktivieren, der sie ausdrücklich deaktiviert.

Verhindern der Texteingabe

Benutzer können daran gehindert werden, den Text in einem Entry zu ändern, indem sie die Eigenschaft IsReadOnly auf true setzen:

<Entry Text="User input won't be accepted."
       IsReadOnly="true" />

Hinweis

Die IsReadonly-Eigenschaft verändert das Erscheinungsbild eines Entry nicht, im Gegensatz zur IsEnabled-Eigenschaft, die auch das Erscheinungsbild des Entry in Grau ändert.