Xamarin.Forms 編輯器

發行項
07/21/2020

控件 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預設值，表示可能輸入的字元數目沒有有效限制。

字元間距

將屬性設定為值，即可將字元間距套用至 Editor double ：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>

使用 BackgroundColor 的編輯器範例

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

事件和互動性

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：NewTextValue OldTextValue

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>

編輯器 API

共用方式為

Xamarin.Forms 編輯器

設定和讀取文字

設定佔位元文字

防止文字輸入

轉換文字

限制輸入長度

字元間距

自動調整編輯器的大小

自訂鍵盤

啟用和停用拼字檢查

啟用和停用文字預測

顏色

事件和互動性

已完成

TextChanged

其他資源

共用方式為

Xamarin.Forms 編輯器

設定和讀取文字

設定佔位元文字

防止文字輸入

轉換文字

限制輸入長度

字元間距

自動調整編輯器的大小

自訂鍵盤

啟用和停用拼字檢查

啟用和停用文字預測

顏色

事件和互動性

已完成

TextChanged

相關連結

其他資源