条目

使用 .NET Multi-platform App UI (.NET MAUI) Entry 可以输入和编辑单行文本。 此外，还可以将 Entry 用作密码字段。

Entry 定义以下属性：

• ClearButtonVisibility，类型为 ClearButtonVisibility，控制是否显示清除按钮，使用户能够清除文本。 此属性的默认值可确保不显示清除按钮。
• HorizontalTextAlignment，类型为 TextAlignment，定义文本的水平对齐方式。
• IsPassword，类型为 bool，指定条目是否应在视觉上遮挡键入的文本。
• ReturnCommand，类型为 ICommand，定义按下返回键时要执行的命令。
• object 类型的 ReturnCommandParameter 指定 ReturnCommand 的参数。
• ReturnType，类型为 ReturnType，指定返回按钮的外观。
• VerticalTextAlignment，类型为 TextAlignment，定义文本的垂直对齐方式。

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

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

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

• CharacterSpacing，类型为 double，设置输入文本中字符之间的间距。
• CursorPosition，类型为 int，用于定义游标在编辑器中的位置。
• FontAttributes，类型为 FontAttributes，用于确定文本样式。
• FontAutoScalingEnabled，类型为 bool，用于定义文本是否反映操作系统中设置的缩放首选项。 此属性的默认值为 true。
• string，类型的 FontFamily 定义字体系列。
• 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 事件，在 Entry 中更改文本时会引发该事件。 TextChanged 事件附带的 TextChangedEventArgs 对象具有 NewTextValue 和 OldTextValue 属性，分别表示新文本和旧文本。

有关在 Entry 上指定字体的信息，请参阅字体。

创建条目

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

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

等效 C# 代码如下：

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

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

注意

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

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

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

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

仅当用户通过按键盘上的 Return 键或通过按 Windows 上的 Tab 键结束了输入时，才会引发 Completed 事件。 事件的处理程序是一个泛型事件处理程序：

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

触发 Completed 事件后，将执行 ReturnCommand 属性指定的任何 ICommand，并将 ReturnCommandParameter 属性指定的 object 传递给 ReturnCommand。

注意

位于 Entry 继承层次结构中的 VisualElement 类还包含 Focused 和 Unfocused 事件。

设置字符间距

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

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

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

注意

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

输入长度限制

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

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

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

设置光标位置和文本选择长度

CursorPosition 属性可用于返回或设置将下一个字符插入到 Text 属性中存储的字符串中的位置:

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

CursorPosition 属性的默认值为 0，指示将在 Entry 的开头插入文本。

此外，SelectionLength 属性还可用于返回或设置 Entry 中的文本选择长度:

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

SelectionLength 属性的默认值为 0，表示未选择任何文本。

显示清除按钮

ClearButtonVisibility 属性可用于控制 Entry 是否显示清除按钮，使用户能够清除文本。 应将此属性设置为 ClearButtonVisibility 枚举成员：

• Never 指示永远不会显示清除按钮。 这是 ClearButtonVisibility 属性的默认值。
• WhileEditing 指示在有焦点和文本的情况下，将在 Entry 中显示清除按钮。

以下示例展示如何设置属性:

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

以下屏幕截图显示 Android 上已启用清除按钮的 Entry:

转换文本

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

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

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

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

遮盖文本条目

Entry 提供 IsPassword 属性，当设置为 true 时，该属性在视觉上会遮盖输入的文本:

<Entry IsPassword="true" />

以下屏幕截图显示输入已被遮盖的 Entry:

自定义键盘

用户与 Entry 交互时显示的软输入键盘可以通过 Keyboard 属性以编程方式设置为 Keyboard 类中的以下属性之一：

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

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

<Entry Keyboard="Chat" />

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

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

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

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

等效 C# 代码如下：

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

自定义返回键

软输入键盘上返回键的外观（在 Entry 具有焦点时显示）可以通过将 ReturnType 属性设置为 ReturnType 枚举的值来自定义：

• Default – 指示不需要任何特定的返回键，并且将使用平台默认值。
• Done – 指示“完成”返回键。
• Go – 指示“转到”返回键。
• Next – 指示“下一步”返回键。
• Search – 指示“搜索”返回键。
• Send – 指示“发送”返回键。

以下 XAML 示例展示如何设置返回键:

<Entry ReturnType="Send" />

注意

返回键的确切外观取决于平台。 在 iOS 上，返回键是基于文本的按钮。 但是，在 Android 和 Windows 上，返回键是基于图标的按钮。

按下 Return 键时，将触发 Completed 事件，并执行 ReturnCommand 属性指定的任何 ICommand。 此外，ReturnCommandParameter 属性指定的任何 object 都将作为参数传递给 ICommand。 有关命令的详细信息，请参阅命令。

隐藏并显示软输入键盘

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

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

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

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

启用和禁用拼写检查

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

但是，对于某些文本输入方案（如输入用户名），拼写检查会提供负面体验，应通过将 IsSpellCheckEnabled 属性设置为 false 予以禁用：

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

注意

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

启用和禁用文本预测

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

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

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

注意

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

阻止文本输入

可以通过将 IsReadOnly 属性设置为 true 来阻止用户修改 Entry 中的文本：

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

注意

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