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 的變數定義是否應該防止使用者修改文字。此屬性的預設值為 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 中的文字發生變更時，將引發此事件。事件的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 上的輸入欄位結果：

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

Note

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

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

TextChanged 事件會在 Entry 中的文字變更時引發，而 TextChangedEventArgs 則透過 OldTextValue 和 NewTextValue 屬性提供變更前後的文字：

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，並將由ReturnCommandParameter屬性指定的object傳遞給ReturnCommand。

Note

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

設定字元間距

將 Entry 的 CharacterSpacing 屬性設定為 double 值，即可套用字元間距。

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

結果是，Entry 所顯示的文字中，字元之間的間距為 CharacterSpacing 裝置無關單位。

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屬性可用來控制是否顯示清除按鈕，讓使用者可以清除文字。此屬性應設定為ClearButtonVisibility列舉成員：

表示永遠不會顯示清除按鈕。這是 ClearButtonVisibility 屬性的預設值。
WhileEditing 表示當 Entry 中具有焦點和文字時，會顯示一個清除按鈕。

以下範例顯示如何設定屬性：

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

下列螢幕快照顯示在 Android 上啟用了清除按鈕的元件：

Screenshot of a basic Entry with a clear button on 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 互動時所呈現的軟體輸入鍵盤，可以透過 Keyboard 屬性以程式設計方式設定為 Keyboard 類別中的下列屬性之一：Keyboard。

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

下列範例顯示設定 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);

自定義傳回金鑰

在具有焦點的情況下，可以通過將ReturnType屬性設定為ReturnType列舉中的一個值來自訂在軟式輸入鍵盤上顯示的傳回鍵外觀。

Default – 表示不需要任何特定的返回鍵，且會使用平台預設值。
Done – 表示「完成」的返回鍵。
Go – 表示 "Go" 傳回鍵。
Next – 表示「下一步」的傳回鍵。
Search – 表示「搜尋」鍵。
Send – 表示「Send」回車鍵。

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

<Entry ReturnType="Send" />

Note

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

當按下 Return 鍵時，會觸發事件，並執行由屬性所指定的任何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" />

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 2026-04-10

Entry

建立專案

設定字元間距

限制輸入長度

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

顯示清除按鈕

轉換文字

晦澀文字輸入

自訂鍵盤

自定義傳回金鑰

隱藏並顯示軟式輸入鍵盤

啟用和停用拼字檢查

啟用和停用文字預測

防止文字輸入

意見反應

其他資源