編輯器

發行項
05/14/2024

.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別為的，定義是否應該防止使用者修改文字。此屬性的預設值為 false。
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指定字型的詳細資訊，請參閱字型。

建立編輯器

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

Android 上基本編輯器的螢幕快照。

注意

在 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文字中的字元會分開分隔裝置獨立單位。

注意

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 大小中的 DataTemplate CollectionView 對象正確無誤。

重要

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

注意

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

啟用和停用文字預測

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

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

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

注意

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

防止文字輸入

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

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

注意

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

共用方式為

編輯器