Editor

Die .NET Multiplatform App UI (.NET MAUI) Editor ermöglicht die Eingabe und Bearbeitung mehrerer Textzeilen.

Editor definiert die folgenden Eigenschaften:

• AutoSize, vom Typ EditorAutoSizeOption, legt fest, ob der Editor die Größe ändert, um sich den Benutzereingaben anzupassen. Standardmäßig nimmt der Editor keine automatische Größenanpassung vor.
• HorizontalTextAlignment, vom Typ TextAlignment, definiert die horizontale Ausrichtung des Textes.
• VerticalTextAlignment vom Typ TextAlignment, definiert die 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 Editor ein Completed-Ereignis, das ausgelöst wird, wenn der Benutzer den Text im Editor mit der Eingabetaste abschließt.

Editor 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 Editor ä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 Editor, siehe Schriftarten.

Erstellen eines Editors

Das folgende Beispiel zeigt, wie ein Editor erstellt wird.

<Editor x:Name="editor"
        Placeholder="Enter your response here"
        HeightRequest="250"
        TextChanged="OnEditorTextChanged"
        Completed="OnEditorCompleted" />

Der entsprechende C#-Code lautet:

Editor editor = new Editor { Placeholder = "Enter text", HeightRequest = 250 };
editor.TextChanged += OnEditorTextChanged;
editor.Completed += OnEditorCompleted;

Der folgende Screenshot zeigt das Ergebnis Editor 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 Editor ändert, und TextChangedEventArgs liefert über die Eigenschaften OldTextValue und NewTextValue den Text vor und nach der Änderung:

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

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

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

Zeichenabstand

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

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

Dies hat zur Folge, dass die Zeichen im Text, der von der Editor 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 Editor zulässige Eingabelänge. Diese Eigenschaft sollte auf eine positive ganze Zahl festgelegt werden:

<Editor ... 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 Editor ist, bedeutet, dass es keine effektive Begrenzung für die Anzahl der Zeichen gibt, die eingegeben werden können.

Editor mit automatischer Größenanpassung

Ein Editor kann auf automatische Größe gebracht werden, indem die Editor.AutoSize-Eigenschaft auf TextChanges gesetzt wird, was ein Wert der EditorAutoSizeOption-Enumeration ist. Diese Enumeration weist zwei Werte auf:

• Disabled bedeutet, dass die automatische Größenanpassung deaktiviert ist und ist der Standardwert.
• TextChanges zeigt an, dass die automatische Größenänderung aktiviert ist.

Dies kann folgendermaßen erfüllt werden:

<Editor Text="Enter text here"
        AutoSize="TextChanges" />

Wenn die automatische Größenanpassung aktiviert ist, vergrößert sich die Höhe von Editor, wenn der/die Benutzer*in es mit Text füllt, und sie verringert sich, wenn der/die Benutzer*in Text löscht. Damit kann sichergestellt werden, dass Editor-Objekte in einer DataTemplate in einer CollectionView die korrekte Größe haben.

Wichtig

Ein Editor hat keine automatische Größenanpassung, wenn die Eigenschaft HeightRequest festgelegt wurde.

Transformieren von Text

Ein Editor 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:

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

Anpassen der Tastatur

Die Tastatur, die angezeigt wird, wenn Benutzer*innen mit einem Editor interagieren, kann programmatisch über die Keyboard-Eigenschaft auf eine der folgenden Eigenschaften der Keyboard-Klasse festgelegt 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:

<Editor 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:

<Editor>
    <Editor.Keyboard>
        <Keyboard x:FactoryMethod="Create">
            <x:Arguments>
                <KeyboardFlags>Suggestions,CapitalizeCharacter</KeyboardFlags>
            </x:Arguments>
        </Keyboard>
    </Editor.Keyboard>
</Editor>

Der entsprechende C#-Code lautet:

Editor editor = new Editor();
editor.Keyboard = Keyboard.Create(KeyboardFlags.Suggestions | KeyboardFlags.CapitalizeCharacter);

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 Editor mit dem Namen editor ausblendet, wenn sie gerade angezeigt wird:

if (editor.IsSoftInputShowing())
    await editor.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 etwa die Eingabe eines Benutzernamens, stellt die Rechtschreibprüfung jedoch eine negative Erfahrung dar und sollte daher durch Setzen der Eigenschaft IsSpellCheckEnabled auf false deaktiviert werden:

<Editor ... 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:

<Editor ... 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*innen können daran gehindert werden, den Text in einem Editor zu ändern, indem sie die IsReadOnly-Eigenschaft, die einen Standardwert von false hat, auf true setzen:

<Editor Text="This is a read-only Editor"
        IsReadOnly="true" />

Hinweis

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