共用方式為


Entry

.NET 多平台應用程式 UI (.NET MAUI) Entry 可讓您輸入和編輯單行文字。 此外, Entry 也可以當做密碼欄位使用。

Entry 會定義下列屬性:

  • ClearButtonVisibilityClearButtonVisibility別為 的控件是否顯示清除按鈕,讓使用者可以清除文字。 此屬性的預設值可確保不會顯示清除按鈕。
  • HorizontalTextAlignmentTextAlignment別為 的 ,定義文字的水準對齊方式。
  • IsPasswordbool別為 的 ,指定專案是否應該以可視化方式遮蔽具型別的文字。
  • ReturnCommandICommand別為的 ,定義在按下傳回鍵時要執行的命令。
  • ReturnCommandParameterobject別為 的 ,指定 的參數 ReturnCommand
  • ReturnTypeReturnType別為 的 ,指定傳回按鈕的外觀。
  • VerticalTextAlignmentTextAlignment別為 的 ,會定義文字的垂直對齊方式。

這些屬性是由 BindableProperty 物件所支援,這表示這些屬性可以是數據系結的目標,並設定樣式。

此外, Entry 定義 Completed 事件,當使用者使用傳回鍵完成 中的 Entry 文字時,就會引發此事件。

Entry 衍生自 類別 InputView ,其繼承下列屬性:

  • CharacterSpacing類型 double為的 ,會設定輸入文字中字元之間的間距。
  • CursorPositionint別為 的 ,定義游標在編輯器中的位置。
  • FontAttributesFontAttributes別為 的 ,會決定文字樣式。
  • FontAutoScalingEnabledbool別為 的 ,定義文字是否會反映操作系統中設定的縮放喜好設定。 此屬性的預設值為 true
  • FontFamilystring別為的 ,會定義字型系列。
  • FontSizedouble別為 的 ,會定義字型大小。
  • IsReadOnlybool別為 的 ,定義是否應該防止使用者修改文字。 此屬性的預設值為 false
  • IsSpellCheckEnabledbool別為 的 ,控制是否啟用拼字檢查。
  • IsTextPredictionEnabledbool別為 的控件是否啟用文字預測和自動文字更正。
  • KeyboardKeyboard別為 的 ,指定輸入文字時所顯示的軟式輸入鍵盤。
  • MaxLengthint別為 的 ,定義輸入長度上限。
  • Placeholderstring別為 的 ,定義當控件是空的時所顯示的文字。
  • PlaceholderColorColor別為 的 ,會定義佔位元文字的色彩。
  • SelectionLengthint別為 的 ,表示控件內選取文字的長度。
  • Textstring別為 的 ,會定義輸入控件中的文字。
  • TextColorColor別為 的 ,會定義輸入文字的色彩。
  • TextTransformTextTransform別為 的 ,指定輸入文字的大小寫。

這些屬性是由 BindableProperty 物件所支援,這表示這些屬性可以是數據系結的目標,並設定樣式。

此外, InputView 定義 TextChanged 事件,此事件會在變更中的 Entry 文字時引發。 事件 TextChangedEventArgs 隨附 TextChanged 的物件具有 NewTextValueOldTextValue 屬性,分別指定新文字和舊文字。

如需在 上 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

Android 上基本項目的螢幕快照。

注意

在 iOS 上,當欄位靠近螢幕底部時,軟式輸入鍵盤可以覆蓋文字輸入欄位,因此很難輸入文字。 不過,在 .NET MAUI iOS 應用程式中,當軟輸入鍵盤涵蓋文字輸入欄位時,頁面會自動捲動,讓字段位於軟式輸入鍵盤上方。 KeyboardAutoManagerScroll.Disconnect您可以在 命名空間中Microsoft.Maui.Platform呼叫 方法,以停用此預設行為。 KeyboardAutoManagerScroll.Connect您可以呼叫 方法,在停用之後重新啟用行為。

輸入的文字可以藉由讀取 Text 屬性來存取,而 TextChangedCompleted 事件表示文字已變更或已完成。

TextChanged當變更中的Entry文字,以及TextChangedEventArgs透過和 NewTextValue 屬性在變更OldTextValue前後提供文字時,就會引發 事件:

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

Completed當使用者按下鍵盤上的 Return 鍵或按下 Windows 上的 Tab 鍵來結束輸入時,就會引發事件。 事件的處理程式是泛型事件處理程式:

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

Completed引發事件之後,會執行 屬性所ReturnCommand指定的任何 ICommand ,並將 object 屬性所ReturnCommandParameter指定的 傳遞給 ReturnCommand

注意

類別 VisualElement ,位於繼承階層中 Entry ,也有 FocusedUnfocused 事件。

設定字元間距

將屬性設定為值,即可將字元間距套用至 Entry doubleCharacterSpacing

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

結果是 ,所顯示的EntryCharacterSpacing文字中的字元會分開分隔裝置獨立單位。

注意

CharacterSpacing屬性值會套用至 和 Placeholder 屬性所Text顯示的文字。

限制輸入長度

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" />

下列螢幕快照顯示 Entry Android 上已開啟清除按鈕的 :

Android 上具有清除按鈕的基本項目螢幕快照。

轉換文字

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 的螢幕快照,其中 IsPassword 設定為 true。

自訂鍵盤

當使用者透過 屬性以程式設計方式設定與 Entry 互動時所呈現的軟輸入鍵盤,從類別設定為下列其中一個屬性KeyboardKeyboard

  • Chat - 用於收發簡訊和 Emoji 有用的地方。
  • Default - 預設鍵盤。
  • Email - 輸入電子郵件地址時使用。
  • Numeric - 輸入數字時使用。
  • Plain - 輸入文字時使用,不指定任何 KeyboardFlags
  • Telephone - 輸入電話號碼時使用。
  • Text - 輸入文字時使用。
  • Url - 用於輸入檔案路徑與網址。

下列範例顯示設定 Keyboard 屬性:

<Entry Keyboard="Chat" />

Keyboard 類別還具有 Create Factory 方法,可透過指定大小寫、拼字檢查和建議的行為來自訂鍵盤。 KeyboardFlags 列舉值會被指定為方法的引數,並傳回自訂的 KeyboardKeyboardFlags 列舉包含下列值:

  • 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 – 表示 「Go」 傳回索引鍵。
  • Next – 表示「下一步」傳回索引鍵。
  • Search – 表示「搜尋」傳回鍵。
  • Send – 表示「傳送」傳回密鑰。

下列 XAML 範例示範如何設定傳回索引鍵:

<Entry ReturnType="Send" />

注意

傳回金鑰的確切外觀取決於平臺。 在 iOS 上,傳回鍵是文字型按鈕。 不過,在 Android 和 Windows 上,傳回鍵是以圖示為基礎的按鈕。

按下 Return 鍵時,Completed會引發 事件,並執行 屬性所ReturnCommand指定的任何ICommand事件。 此外,屬性所ReturnCommandParameter指定的任何object都會傳遞至 ICommand 做為參數。 如需命令的詳細資訊,請參閱 命令

隱藏並顯示軟式輸入鍵盤

命名空間 SoftInputExtensions 中的 Microsoft.Maui 類別提供一系列擴充方法,可支援與支援文字輸入之控件上的軟輸入鍵盤互動。 類別會定義下列方法:

  • 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。 當使用者輸入文字時,會顯示文字預測。

不過,對於某些文字輸入案例,例如輸入使用者名稱、文字預測和自動文字更正,會提供負面體驗,而且應該藉由將 屬性設定 IsTextPredictionEnabledfalse來停用:

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

注意

IsTextPredictionEnabled當屬性設定為 false,且未使用自定義鍵盤時,會停用文字預測和自動文字更正。 不過,如果 Keyboard 已設定停用文字預測的 ,則會 IsTextPredictionEnabled 忽略 屬性。 因此,屬性無法用來為明確停用的 啟用文字預測 Keyboard

防止文字輸入

您可以將 屬性設定IsReadOnlytrue,以防止使用者修改中的Entry文字:

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

注意

屬性 IsReadonly 不會改變 的 Entry視覺外觀,不同於 IsEnabled 屬性,也會將 的視覺外觀 Entry 變更為灰色。