共用方式為

Editor

.NET 多平台應用程式 UI （.NET MAUI） Editor 可讓您輸入和編輯多行文字。

Editor 會定義下列屬性：

  • AutoSize型 EditorAutoSizeOption別為 的 ，定義編輯器是否會變更大小以容納用戶輸入。 根據預設，編輯器不會自動重設大小。
  • HorizontalTextAlignment型 TextAlignment別為 的 ，定義文字的水準對齊方式。
  • VerticalTextAlignment型 TextAlignment別為 的 ，會定義文字的垂直對齊方式。

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

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

Editor 衍生自 類別 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 事件，此事件會在變更中的 Editor 文字時引發。 事件 TextChangedEventArgs 隨附 TextChanged 的物件具有 NewTextValue 和 OldTextValue 屬性，分別指定新文字和舊文字。

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

小提示

在 Android 上，.NET 10 會將原生 Editor 檢視切換至 MauiAppCompatEditText，以啟用選取範圍變更追蹤。 隨著選取範圍的變更， CursorPosition 並 SelectionLength 會更新，以便您可以對選取範圍的移動做出反應。

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

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

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

建立編輯器

下列範例示範如何建立 Editor：

<Editor x:Name="editor"
        Placeholder="Enter your response here"
        HeightRequest="250"
        TextChanged="OnEditorTextChanged"
        Completed="OnEditorCompleted" />

對等的 C# 程式碼為：

Editor editor = new Editor { Placeholder = "Enter text", HeightRequest = 250 };
editor.TextChanged += OnEditorTextChanged;
editor.Completed += OnEditorCompleted;

下列螢幕快照顯示 Android 上產生的 Editor ：

Screenshot of a basic Editor on Android.Android 上基本編輯器的螢幕快照。

Note

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

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

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

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

Completed只有在使用者按下鍵盤上的 Tab 鍵或將另一個控件設為焦點，以結束輸入時，才會在 Windows 上引發事件。 事件的處理程式是泛型事件處理程式：

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

設定字元間距

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

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

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

Note

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

限制輸入長度

MaxLength屬性可用來限制 允許的Editor輸入長度。 此屬性應設定為正整數：

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

MaxLength屬性值 0 表示不允許輸入，而的值為 int.MaxValue，這是的Editor預設值，表示可能輸入的字元數目沒有有效限制。

自動調整編輯器的大小

Editor可以藉由將 屬性設定為 ，將 屬性TextChanges設定Editor.AutoSize為 ，以自動調整其內容的大小，這是 列舉的值EditorAutoSizeOption。 此列舉有兩個值：

  • Disabled 表示自動重設大小已停用，而且是預設值。
  • TextChanges 表示已啟用自動重設大小。

執行下列工作即可達成這點：

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

啟用自動重設大小時， Editor 當使用者以文字填滿時，的高度將會增加，而當使用者刪除文字時，高度將會減少。 這可用來確保 Editor 大小中的 DataTemplateCollectionView 對象正確無誤。

Important

Editor如果已設定 屬性，HeightRequest則不會自動重設大小。

轉換文字

Editor可以藉由將 TextTransform 屬性設定為 列舉值TextTransform，來轉換儲存在 屬性中的Text文字大小寫。 此列舉具有四個值：

  • None 表示不會轉換文字。
  • Default 表示將使用平台的預設行為。 此為 TextTransform 屬性的預設值。
  • Lowercase 表示文字將會轉換成小寫。
  • Uppercase 表示文字會轉換成大寫。

下列範例顯示將文字轉換成大寫：

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

自訂鍵盤

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

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

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

<Editor Keyboard="Chat" />

Keyboard 類別還具有 Create Factory 方法，可透過指定大小寫、拼字檢查和建議的行為來自訂鍵盤。 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# 程式碼為：

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

隱藏並顯示軟式輸入鍵盤

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

  • IsSoftInputShowing，它會檢查裝置目前是否顯示軟式輸入鍵盤。
  • HideSoftInputAsync，如果目前顯示，則會嘗試隱藏虛輸入鍵盤。
  • ShowSoftInputAsync，如果目前隱藏，則會嘗試顯示軟式輸入鍵盤。

下列範例示範如何隱藏具名 editor上的Editor軟輸入鍵盤，如果它目前顯示：

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

啟用和停用拼字檢查

屬性 IsSpellCheckEnabled 會控制是否啟用拼字檢查。 根據預設，屬性會設定為 true。 當使用者輸入文字時，會指出拼字錯誤。

不過，對於某些文字輸入案例，例如輸入使用者名稱，拼字檢查會提供負面體驗，因此應該藉由將 屬性設定 IsSpellCheckEnabled 為 false來停用：

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

Note

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

啟用和停用文字預測

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

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

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

Note

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

防止文字輸入

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

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

Note

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

行尾結束符號 （僅限 Windows）

當使用者在控件中新增多行時， Text 屬性只會包含行尾端的 “\r”，而不是 Windows 中的一般 “\r\n”。 沒有屬性可變更此行為，但可以變更文字以視需要包含此特定行尾。

#if WINDOWS
if (EditorText.Text.Contains("\r"))
{
    var textWithWindowsLineBreaks = EditorText.Text.Replace("\r", Environment.NewLine);

    // Do something with the text that has Windows line breaks
}
#endif

Note

請勿將更新的文字指派給 Text 控件的 屬性。 如果發生這種情況，將會還原原始行尾端 （“\r”）。

  • Last updated on