Xamarin.Forms编辑器

项目
05/05/2024

Editor 控件用于接受多行输入。

设置和读取文本

与其他文本呈现视图一样，Editor 属性公开 Text 属性。此属性可用来设置和读取由 Editor 呈现的文本。下面的示例演示了如何在 XAML 中设置 Text 属性：

<Editor x:Name="editor" Text="I am an Editor" />

在 C# 中：

var editor = new Editor { Text = "I am an Editor" };

若要读取文本，请在 C# 中访问 Text 属性：

var text = editor.Text;

设置占位符文本

Editor 可以设置为在未存储用户输入时显示占位符文本。这是通过将 Placeholder 属性设置为一个 string 实现的，并且经常用来指示适合 Editor 的内容类型。此外，可以通过将 PlaceholderColor 属性设置为一种 Color 来控制占位符文本颜色：

<Editor Placeholder="Enter text here" PlaceholderColor="Olive" />

var editor = new Editor { Placeholder = "Enter text here", PlaceholderColor = Color.Olive };

阻止文本输入

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

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

var editor = new Editor { Text = "This is a read-only Editor", IsReadOnly = true });

注意

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

转换文本

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

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

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

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

等效 C# 代码如下：

Editor editor = new Editor
{
    Text = "This text will be displayed in uppercase.",
    TextTransform = TextTransform.Uppercase
};

输入长度限制

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

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

var editor = new Editor { ... MaxLength = 10 };

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

字符间距

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

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

等效 C# 代码如下：

Editor editor = new editor { CharacterSpacing = 10 };

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

注意

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

自动调整编辑器大小

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

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

这可在代码中通过以下操作来实现：

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

var editor = new Editor { Text = "Enter text here", AutoSize = EditorAutoSizeOption.TextChanges };

启用自动调整大小后，当用户向 Editor 填充文本时，其高度将增加，当用户删除文本时，其高度会降低。

注意

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

自定义键盘

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

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

这可以通过以下操作以 XAML 实现：

<Editor Keyboard="Chat" />

等效 C# 代码如下：

var editor = new Editor { Keyboard = Keyboard.Chat };

可以在我们的 Recipes 存储库中找到每个键盘的示例。

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# 代码如下：

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

启用和禁用拼写检查

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

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

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

var editor = new Editor { ... IsSpellCheckEnabled = false };

注意

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

启用和禁用文本预测

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

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

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

var editor = new Editor { ... IsTextPredictionEnabled = false };

注意

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

颜色

可通过 BackgroundColor 属性将 Editor 设置为使用自定义背景色。需要特别小心，以确保颜色在每个平台上都可用。由于每个平台都有不同的文本颜色默认值，因此你可能需要为每个平台设置自定义背景色。若要详细了解如何优化每个平台的 UI，请参阅使用平台调整。

在 C# 中：

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        //dark blue on UWP & Android, light blue on iOS
        var editor = new Editor { BackgroundColor = Device.RuntimePlatform == Device.iOS ? Color.FromHex("#A4EAFF") : Color.FromHex("#2c3e50") };
        layout.Children.Add(editor);
    }
}

在 XAML 中：

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="TextSample.EditorPage"
    Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor>
                <Editor.BackgroundColor>
                    <OnPlatform x:TypeArguments="x:Color">
                        <On Platform="iOS" Value="#a4eaff" />
                        <On Platform="Android, UWP" Value="#2c3e50" />
                    </OnPlatform>
                </Editor.BackgroundColor>
            </Editor>
        </StackLayout>
    </ContentPage.Content>
</ContentPage>

Editor with BackgroundColor Example

确保所选背景和文本颜色在每个平台上都可用，并且不会遮挡任何占位符文本。

事件和交互性

Editor 公开两个事件：

TextChanged - 当编辑器中的文本更改时引发。提供更改前后的文本。
Completed - 当用户通过按键盘上的回车键结束输入时引发。

注意

Entry 从中进行继承的 VisualElement 类也有 Focused 和 Unfocused 事件。

已完成

Completed 事件用来响应与 Editor 的交互的完成。当用户通过输入键盘上的回车键（或按 UWP 上的 Tab 键）结束输入时，将引发 Completed。该事件的处理程序是一个泛型事件处理程序，采用发送方和 EventArgs：

void EditorCompleted (object sender, EventArgs e)
{
    var text = ((Editor)sender).Text; // sender is cast to an Editor to enable reading the `Text` property of the view.
}

可以在代码和 XAML 中订阅 completed 事件：

在 C# 中：

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        var editor = new Editor ();
        editor.Completed += EditorCompleted;
        layout.Children.Add(editor);
    }
}

在 XAML 中：

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TextSample.EditorPage"
Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor Completed="EditorCompleted" />
        </StackLayout>
    </ContentPage.Content>
</Contentpage>

TextChanged

TextChanged 事件用来响应字段内容的更改。

每当 Editor 的 Text 更改时都会引发 TextChanged。该事件的处理程序采用 TextChangedEventArgs 的实例。 TextChangedEventArgs 通过 OldTextValue 和 NewTextValue 属性提供对 EditorText 的旧值和新值的访问：

void EditorTextChanged (object sender, TextChangedEventArgs e)
{
    var oldText = e.OldTextValue;
    var newText = e.NewTextValue;
}

可以在代码和 XAML 中订阅 completed 事件：

在代码中：

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        var editor = new Editor ();
        editor.TextChanged += EditorTextChanged;
        layout.Children.Add(editor);
    }
}

在 XAML 中：

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TextSample.EditorPage"
Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor TextChanged="EditorTextChanged" />
        </StackLayout>
    </ContentPage.Content>
</ContentPage>

Xamarin.Forms编辑器

设置和读取文本

设置占位符文本

阻止文本输入

转换文本

输入长度限制

字符间距

自动调整编辑器大小

自定义键盘

启用和禁用拼写检查

启用和禁用文本预测

颜色

事件和交互性

已完成

TextChanged

相关链接

其他资源