Entry

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

Entry 會定義下列屬性：

ClearButtonVisibility型 ClearButtonVisibility別為的控件是否顯示清除按鈕，讓使用者可以清除文字。此屬性的預設值可確保不會顯示清除按鈕。
HorizontalTextAlignment型 TextAlignment別為的，定義文字的水準對齊方式。
IsPassword型 bool別為的，指定專案是否應該以可視化方式遮蔽具型別的文字。
ReturnCommand型 ICommand別為的，定義在按下傳回鍵時要執行的命令。
ReturnCommandParameter型 object別為的，指定的參數 ReturnCommand。
ReturnType型 ReturnType別為的，指定傳回按鈕的外觀。
VerticalTextAlignment型 TextAlignment別為的，會定義文字的垂直對齊方式。

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

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

Entry 衍生自類別 InputView ，其繼承下列屬性：

CharacterSpacing類型為 double的，會設定文字內容中字元之間的間距，包括使用者輸入或顯示的文字和佔位元文字。
CursorPosition型 int別為的，定義游標在編輯器中的位置。
FontAttributes型 FontAttributes別為的，會決定文字樣式。
FontAutoScalingEnabled型 bool別為的，定義文字是否會反映操作系統中設定的縮放喜好設定。此屬性的預設值為 true。
FontFamily型 string別為的，會定義字型系列。
FontSize型 double別為的，會定義字型大小。
IsReadOnly型 bool別為的，定義是否應該防止使用者修改文字。此屬性的預設值為 true。
IsSpellCheckEnabled型 bool別為的，控制是否啟用拼字檢查。
IsTextPredictionEnabled型 bool別為的控件是否啟用文字預測和自動文字更正。
Keyboard型 Keyboard別為的，指定輸入文字時所顯示的軟式輸入鍵盤。
MaxLength型 int別為的，定義輸入長度上限。
Placeholder型 string別為的，定義當控件是空的時所顯示的文字。
PlaceholderColor型 Color別為的，會定義佔位元文字的色彩。
SelectionLength型 int別為的，表示控件內選取文字的長度。
Text型 string別為的，會定義輸入控件中的文字。
TextColor型 Color別為的，會定義輸入文字的色彩。
TextTransform型 TextTransform別為的，指定輸入文字的大小寫。

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

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

如需在上 Entry指定字型的詳細資訊，請參閱字型。

小提示

Android 在 .NET 10 中新增了對選取變更通知的支援。在 Android 上，原生控制項會從 AppCompatEditText 切換到 MauiAppCompatEditText，啟用Entry的選取變更追蹤。當選取範圍變更時， CursorPosition 和 SelectionLength 屬性會更新，以便您可以對選取範圍移動做出反應。

若要觀察選取更新，必須處理CursorPosition 和 SelectionLength的屬性變更。

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

或者，資料繫結屬性並在檢視模型中做出反應。

建立專案

下列範例示範如何建立 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 ：

Screenshot of a basic Entry on Android. Android 上基本項目的螢幕快照。

Note

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

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

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。

Note

類別 VisualElement ，位於繼承階層中 Entry ，也有 Focused 和 Unfocused 事件。

設定字元間距

將屬性設定為值，即可將字元間距套用至 Entrydouble ：CharacterSpacing

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

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

Note

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 上已開啟清除按鈕的：

Screenshot of a basic Entry with a clear buttonon 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 已遮蔽其輸入的：

Screenshot of a basic Entry with IsPassword set to true. 基本 Entry 的螢幕快照，其中 IsPassword 設定為 true。

自訂鍵盤

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

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

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

<Entry Keyboard="Chat" />

Keyboard 類別還具有 Create Factory 方法，可透過指定大小寫、拼字檢查和建議的行為來自訂鍵盤。 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 – 表示「Go」傳回索引鍵。
Next – 表示「下一步」傳回索引鍵。
Search – 表示「搜尋」傳回鍵。
Send – 表示「傳送」傳回密鑰。

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

<Entry ReturnType="Send" />

Note

傳回金鑰的確切外觀取決於平臺。在 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" />

Note

IsSpellCheckEnabled當屬性設定為 false，且未使用自定義鍵盤時，將會停用原生拼字檢查程式。不過，如果 Keyboard 已設定停用拼字檢查的，例如 Keyboard.Chat，則會 IsSpellCheckEnabled 忽略屬性。因此，屬性無法用來啟用明確停用的拼字檢查 Keyboard 。

啟用和停用文字預測

屬性 IsTextPredictionEnabled 會控制是否啟用文字預測和自動文字更正。根據預設，屬性會設定為 true。當使用者輸入文字時，會顯示文字預測。

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

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

Note

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

防止文字輸入

您可以將屬性設定IsReadOnly為 true，以防止使用者修改中的Entry文字：

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

Note

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-08-21

共用方式為

Entry

建立專案

設定字元間距

限制輸入長度

設定游標位置和文字選取長度

顯示清除按鈕

轉換文字

遮蔽文字專案

自訂鍵盤

自定義傳回金鑰

隱藏並顯示軟式輸入鍵盤

啟用和停用拼字檢查

啟用和停用文字預測

防止文字輸入

意見反應

其他資源