Xamarin.Forms 編輯器

發行項
01/10/2024

控件 Editor 用來接受多行輸入。

設定和讀取文字

和 Editor其他文字呈現檢視一樣，會公開 Text 屬性。這個屬性可用來設定和讀取所呈現的 Editor文字。下列範例示範如何在 XAML 中設定 Text 屬性：

<Editor x:Name="editor" Text="I am an Editor" />

在 C# 中：

var editor = new Editor { Text = "I am an Editor" };

若要讀取文字，請存取 Text C# 中的屬性：

var text = editor.Text;

設定佔位元文字

Editor可以設定為在未儲存使用者輸入時顯示佔位元文字。這可藉由將 Placeholder 屬性設定為 string來完成，而且通常用來指出適合 Editor的內容類型。此外，您可以將屬性設定 PlaceholderColor 為 Color，以控制佔位元文字色彩：

<Editor Placeholder="Enter text here" PlaceholderColor="Olive" />

var editor = new Editor { Placeholder = "Enter text here", PlaceholderColor = Color.Olive };

防止文字輸入

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

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

var editor = new Editor { Text = "This is a read-only Editor", IsReadOnly = true });

注意

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

轉換文字

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

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

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

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

對等的 C# 程式碼為：

Editor editor = new Editor
{
    Text = "This text will be displayed in uppercase.",
    TextTransform = TextTransform.Uppercase
};

限制輸入長度

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

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

var editor = new Editor { ... MaxLength = 10 };

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

字元間距

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

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

對等的 C# 程式碼為：

Editor editor = new editor { CharacterSpacing = 10 };

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

注意

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

自動調整編輯器的大小

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

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

這可以在程序代碼中完成，如下所示：

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

var editor = new Editor { Text = "Enter text here", AutoSize = EditorAutoSizeOption.TextChanges };

啟用自動重設大小時， Editor 當使用者以文字填滿時，的高度將會增加，而當使用者刪除文字時，高度將會減少。

注意

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

自訂鍵盤

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

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

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

<Editor Keyboard="Chat" />

對等的 C# 程式碼為：

var editor = new Editor { Keyboard = 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# 程式碼為：

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

啟用和停用拼字檢查

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

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

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

var editor = new Editor { ... IsSpellCheckEnabled = false };

注意

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

啟用和停用文字預測

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

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

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

var editor = new Editor { ... IsTextPredictionEnabled = false };

注意

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

顏色

Editor 可以設定為透過 BackgroundColor 屬性使用自定義背景色彩。必須特別小心，以確保每個平臺上都能使用色彩。由於每個平臺的文字色彩都有不同的預設值，因此您可能需要為每個平臺設定自定義背景色彩。如需優化每個平臺 UI 的詳細資訊，請參閱使用平台調整。

在 C# 中：

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        //dark blue on UWP & Android, light blue on iOS
        var editor = new Editor { BackgroundColor = Device.RuntimePlatform == Device.iOS ? Color.FromHex("#A4EAFF") : Color.FromHex("#2c3e50") };
        layout.Children.Add(editor);
    }
}

在 XAML 中：

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="TextSample.EditorPage"
    Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor>
                <Editor.BackgroundColor>
                    <OnPlatform x:TypeArguments="x:Color">
                        <On Platform="iOS" Value="#a4eaff" />
                        <On Platform="Android, UWP" Value="#2c3e50" />
                    </OnPlatform>
                </Editor.BackgroundColor>
            </Editor>
        </StackLayout>
    </ContentPage.Content>
</ContentPage>

Editor with BackgroundColor Example

請確定您選擇的背景和文字色彩可在每個平臺上使用，且不會遮蔽任何佔位元文字。

事件和互動性

Editor 會公開兩個事件：

TextChanged – 在編輯器中的文字變更時引發。提供變更前後的文字。
Completed – 當使用者按下鍵盤上的傳回鍵結束輸入時引發。

注意

繼承 VisualElement 來源的 Entry 類別也有 Focused 和 Unfocused 事件。

已完成

事件 Completed 可用來回應與 Editor互動的完成。 Completed 當使用者在鍵盤上輸入傳回鍵或按下 UWP 上的 Tab 鍵，以欄位結束輸入時引發。事件的處理程式是泛型事件處理程式，採用傳送者和 EventArgs：

void EditorCompleted (object sender, EventArgs e)
{
    var text = ((Editor)sender).Text; // sender is cast to an Editor to enable reading the `Text` property of the view.
}

已完成的事件可以在程式代碼和 XAML 中訂閱：

在 C# 中：

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        var editor = new Editor ();
        editor.Completed += EditorCompleted;
        layout.Children.Add(editor);
    }
}

在 XAML 中：

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TextSample.EditorPage"
Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor Completed="EditorCompleted" />
        </StackLayout>
    </ContentPage.Content>
</Contentpage>

TextChanged

事件 TextChanged 可用來回應欄位內容中的變更。

TextChanged 每當 Text 變更的 Editor 時，就會引發。事件的處理程式會採用的 TextChangedEventArgs實例。 TextChangedEventArgs可透過與屬性存取的舊值與新值EditorText：NewTextValueOldTextValue

void EditorTextChanged (object sender, TextChangedEventArgs e)
{
    var oldText = e.OldTextValue;
    var newText = e.NewTextValue;
}

已完成的事件可以在程式代碼和 XAML 中訂閱：

程式碼：

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        var editor = new Editor ();
        editor.TextChanged += EditorTextChanged;
        layout.Children.Add(editor);
    }
}

在 XAML 中：

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TextSample.EditorPage"
Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor TextChanged="EditorTextChanged" />
        </StackLayout>
    </ContentPage.Content>
</ContentPage>

Xamarin.Forms 編輯器

設定和讀取文字

設定佔位元文字

防止文字輸入

轉換文字

限制輸入長度

字元間距

自動調整編輯器的大小

自訂鍵盤

啟用和停用拼字檢查

啟用和停用文字預測

顏色

事件和互動性

已完成

TextChanged

相關連結

其他資源