Editor

.NET Multi-platform App UI (.NET MAUI) Editor 允许输入和编辑多行文本。

Editor 定义以下属性：

• AutoSize，类型为 EditorAutoSizeOption，用于定义编辑器是否更改大小以适应用户输入。 默认情况下，编辑器不会自动调整大小。
• HorizontalTextAlignment，类型为 TextAlignment，用于定义文本的水平对齐方式。
• VerticalTextAlignment，类型为 TextAlignment，用于定义文本的垂直对齐方式。

这些属性由 BindableProperty 对象提供支持，表示它们可以是数据绑定的目标，并可以设置样式。

Editor，类型为 Completed，当用户使用回车键在 Editor 中完成文本时会引发该事件。

Editor 派生自 InputView 类，它从该类继承以下属性：

• CharacterSpacing类型 double，设置文本内容中的字符之间的间距，包括用户输入的文本或显示的文本和占位符文本。
• CursorPosition，类型为 int，用于定义游标在编辑器中的位置。
• FontAttributes，类型为 FontAttributes，用于确定文本样式。
• FontAutoScalingEnabled，类型为 bool，用于定义文本是否反映操作系统中设置的缩放首选项。 此属性的默认值为 true。
• FontFamily，类型的 string 定义字体系列。
• FontSize，类型为 double，定义字号。
• IsReadOnly，类型为 bool，定义是否应阻止用户修改文本。 此属性的默认值为 false。
• IsSpellCheckEnabled，类型为 bool，控制是否启用拼写检查。
• IsTextPredictionEnabled，类型为 bool，控制是否启用文本预测和自动文本更正。
• Keyboard，类型为 Keyboard，指定输入文本时显示的软输入键盘。
• MaxLength，类型为 int，用于定义最大输入长度。
• Placeholder，类型为 string，用于定义控件为空时显示的文本。
• PlaceholderColor，类型为 Color，用于定义占位符文本的颜色。
• SelectionLength，类型为 int，表示控件中选定文本的长度。
• Text，类型为 string，用于定义输入控件中的文本。
• TextColor，类型为 Color，用于定义输入文本的颜色。
• TextTransform，类型为 TextTransform，用于指定输入文本的大小写。

这些属性由 BindableProperty 对象提供支持，表示它们可以是数据绑定的目标，并可以设置样式。

此外，InputView 定义了 TextChanged 事件，在 Editor 中更改文本时会引发该事件。 TextChangedEventArgs 事件附带的 TextChanged 对象具有 NewTextValue 和 OldTextValue 属性，分别表示新文本和旧文本。

有关在 Editor 中指定字体的信息，请参阅字体。

小窍门

在 Android 上，.NET 10 将本机视图 Editor 切换为 MauiAppCompatEditText启用选择更改跟踪。 随着选择的更改，CursorPosition和SelectionLength会更新，以便你可以对选择的移动做出反应。

若要观察选择更新，请处理 CursorPosition 和 SelectionLength 的属性更改：

editor.PropertyChanged += (s, e) =>
{
    if (e.PropertyName == nameof(Editor.CursorPosition) ||
        e.PropertyName == nameof(Editor.SelectionLength))
    {
        var start = editor.CursorPosition;
        var length = editor.SelectionLength;
        // Respond to selection change (Android .NET 10+)
    }
};

或者，数据绑定属性并在视图模型中做出反应。

创建 Editor

以下示例演示了如何创建 Editor：

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

等效 C# 代码如下：

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

以下屏幕截图显示了 Android 上生成的 Editor：

Note

在 iOS 上，当字段靠近屏幕底部时，软输入键盘会覆盖文本输入字段，因此很难输入文本。 但是，在 .NET MAUI iOS 应用中，当软输入键盘覆盖文本输入字段时，页面会自动滚动，以便字段位于软输入键盘上方。 可以调用 KeyboardAutoManagerScroll.Disconnect 命名空间中的 Microsoft.Maui.Platform 方法来禁用此默认行为。 在禁用该行为后，可以调用 KeyboardAutoManagerScroll.Connect 方法来重新启用该行为。

可以通过读取 Text 属性来访问输入的文本，并且 TextChanged 和 Completed 事件表示文本已更改或已完成。

当 TextChanged 中的文本发生更改，并且 Editor 通过 TextChangedEventArgs 和 OldTextValue 属性提供更改前后的文本时，将引发 NewTextValue 事件:

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

仅当用户通过按键盘上的 Completed 键或将焦点置于另一个控件时，才会在 Windows 上引发 事件。 事件的处理程序是一个泛型事件处理程序：

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

设置字符间距

可以通过将 Editor 属性设置为 CharacterSpacing 值，将字符间距应用于 double:

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

结果是，Editor 显示的文本中的字符为间隔开来的 CharacterSpacing 独立于设备的单位。

Note

CharacterSpacing 属性值会应用于通过 Text 和 Placeholder 属性显示的文本。

输入长度限制

MaxLength 属性可用于限制 Editor 允许的输入长度。 此属性应设置为正整数：

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

MaxLength 属性值为 0 时指示不允许输入任何内容，值为 int.MaxValue（即 Editor 的默认值）时指示对可输入的字符数没有有效限制。

自动调整编辑器大小

可以通过将 Editor 属性设置为 Editor.AutoSize（即 TextChanges 枚举的值），使 EditorAutoSizeOption 自动调整大小以适应其内容。 此枚举有两个值：

• Disabled 指示自动调整大小已禁用，并且是默认值。
• TextChanges 指示自动调整大小已启用。

这可通过以下操作实现：

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

启用自动调整大小后，当用户向 Editor 填充文本时，其高度将增加，当用户删除文本时，其高度会降低。 这可用于确保 Editor 中 DataTemplate 中的 CollectionView 对象大小正确。

Important

如果设置了 Editor 属性，则 HeightRequest 不会自动调整大小。

转换文本

Editor 可以通过将 Text 属性设置为 TextTransform 枚举的值转换其文本的大小写(存储在 TextTransform 属性中)。 此枚举有四个值：

• None 指示不会转换文本。
• Default 指示将使用平台的默认行为。 这是 TextTransform 属性的默认值。
• Lowercase 指示文本将被转换为小写。
• Uppercase 指示文本将被转换为大写。

以下示例展示了如何将文本转换为大写：

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

自定义键盘

对于用户与 Editor 交互时显示的键盘，可以通过 Keyboard 属性以编程方式将其设置为 Keyboard 类中的以下属性之一：

• Chat – 用于可使用表情符号的文本和位置。
• Default – 默认键盘。
• Email – 输入电子邮件地址时使用。
• Numeric – 输入数字时使用。
• Plain – 输入文本时使用，无需指定任何 KeyboardFlags。
• Telephone – 输入电话号码时使用。
• Text – 输入文本时使用。
• Url – 用于输入文件路径和 Web 地址。

以下示例演示如何设置 Keyboard 属性：

<Editor Keyboard="Chat" />

Keyboard 类还具有 Create 工厂方法，可用于通过指定大小写、拼写检查和建议行为来自定义键盘。 KeyboardFlags 枚举值指定为方法的参数，并返回自定义的 Keyboard。 KeyboardFlags 枚举包含以下值：

• None – 无功能添加到键盘。
• CapitalizeSentence – 指示自动大写输入的每句话的第一个词的首字母。
• Spellcheck – 指示对输入的文本执行拼写检查。
• Suggestions – 指示对输入的文本执行单词自动完成。
• CapitalizeWord – 指示自动大写每个词的首字母。
• CapitalizeCharacter – 指示自动大写每个字符。
• CapitalizeNone – 指示不执行自动大写。
• All – 指示对输入的文本执行拼写检查、单词自动完成和句子首字母大写。

以下 XAML 代码示例演示如何自定义默认 Keyboard 来执行单词自动完成并将输入的每个字符的首字母大写：

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

等效 C# 代码如下：

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

隐藏并显示软输入键盘

SoftInputExtensions 命名空间中的 Microsoft.Maui 类，提供一系列支持在允许文本输入的控件上与软输入键盘交互的扩展方法。 该类定义以下方法：

• IsSoftInputShowing，检查设备当前是否显示软输入键盘。
• HideSoftInputAsync，会尝试隐藏软输入键盘（如果当前显示）。
• ShowSoftInputAsync，会尝试显示软输入键盘（如果当前已隐藏）。

以下示例演示如何隐藏 Editor 上名为 editor 的软输入键盘（如果它当前显示）：

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

启用和禁用拼写检查

IsSpellCheckEnabled 属性控制是否启用拼写检查。 默认情况下，该属性设置为 true。 用户输入文本时，将指示拼写错误。

但是，对于某些文本输入场景（例如输入用户名），拼写检查会带来负面体验，因此应通过将 IsSpellCheckEnabled 属性设置为 false 来禁用拼写检查：

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

Note

将 IsSpellCheckEnabled 属性设置为 false，并且未使用自定义键盘时，将禁用本机拼写检查器。 但是，如果已设置禁用拼写检查的 Keyboard（如 Keyboard.Chat），则可忽略 IsSpellCheckEnabled 属性。 因此，不能使用该属性对显式禁用它的 Keyboard 启用拼写检查。

启用和禁用文本预测

IsTextPredictionEnabled 属性控制是否启用文本预测和自动文本更正。 默认情况下，该属性设置为 true。 用户输入文本时，将显示单词预测。

但是，对于某些文本输入方案（例如输入用户名），文本预测和自动文本更正会提供负面体验，应通过将 IsTextPredictionEnabled 属性设置为 false 予以禁用：

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

Note

将 IsTextPredictionEnabled 属性设置为 false 且未使用自定义键盘时，将禁用文本预测和自动文本更正。 但是，如果已设置禁用文本预测的 Keyboard，则可忽略 IsTextPredictionEnabled 属性。 因此，不能使用该属性对显式禁用它的 Keyboard 启用文本预测。

阻止文本输入

可以通过将 Editor 属性（默认值为 IsReadOnly）设置为 false 来阻止用户修改 true 中的文本：

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

Note

与 IsReadonly 属性会将 Editor 的视觉效果外观更改为灰色不同，IsEnabled 属性不会更改 Editor 的视觉效果外观。

行尾（仅限 Windows）

当用户在控件中添加多行时，该 Text 属性将仅包含行尾的“\r”，而不是 Windows 中正常的“\r\n”。 没有更改此行为的属性，但可以更改文本以包含此特定行尾（如果需要）。

#if WINDOWS
if (EditorText.Text.Contains("\r"))
{
    var textWithWindowsLineBreaks = EditorText.Text.Replace("\r", Environment.NewLine);

    // Do something with the text that has Windows line breaks
}
#endif

Note

不要将更新的文本 Text 分配给控件的属性。 如果发生这种情况，将还原原始行结尾（“\r”）。