Kotak edit kaya

  • Artikel

Anda bisa menggunakan kontrol RichEditBox untuk memasukkan dan mengedit dokumen teks kaya yang berisi teks, hyperlink, dan gambar yang diformat. Anda dapat membuat RichEditBox baca-saja dengan mengatur properti IsReadOnly-nya ke true.

Apakah ini kontrol yang tepat?

Gunakan RichEditBox untuk menampilkan dan mengedit file teks. Anda tidak menggunakan RichEditBox untuk memasukkan input pengguna ke dalam aplikasi Anda dengan cara Anda menggunakan kotak input teks standar lainnya. Sebaliknya, Anda menggunakannya untuk bekerja dengan file teks yang terpisah dari aplikasi Anda. Anda biasanya menyimpan teks yang dimasukkan ke dalam RichEditBox ke file .rtf.

  • Jika tujuan utama kotak teks multibaris adalah untuk membuat dokumen baca-saja (seperti entri blog atau konten pesan email), dan dokumen tersebut memerlukan teks kaya, gunakan blok teks kaya sebagai gantinya.
  • Saat mengambil teks yang hanya akan digunakan dan tidak diputar ulang kepada pengguna, gunakan kontrol input teks biasa.
  • Untuk semua skenario lainnya, gunakan kontrol input teks biasa.

Untuk informasi selengkapnya tentang memilih kontrol teks yang tepat, lihat artikel Kontrol teks .

Rekomendasi

  • Saat Anda membuat kotak teks kaya, sediakan tombol gaya dan terapkan tindakannya.
  • Gunakan font yang konsisten dengan gaya aplikasi Anda.
  • Buat tinggi kontrol teks cukup tinggi untuk mengakomodasi entri umum.
  • Jangan biarkan kontrol input teks Anda tumbuh tinggi saat pengguna mengetik.
  • Jangan gunakan kotak teks multibaris saat pengguna hanya memerlukan satu baris.
  • Jangan gunakan kontrol teks kaya jika kontrol teks biasa memadai.

Contoh

Kotak edit kaya ini memiliki dokumen teks kaya yang terbuka di dalamnya. Tombol pemformatan dan file bukan bagian dari kotak edit yang kaya, tetapi Anda harus menyediakan setidaknya satu set tombol gaya minimal dan menerapkan tindakannya.

Kotak teks kaya dengan dokumen terbuka

UWP dan WinUI 2

Penting

Informasi dan contoh dalam artikel ini dioptimalkan untuk aplikasi yang menggunakan SDK Aplikasi Windows dan WinUI 3, tetapi umumnya berlaku untuk aplikasi UWP yang menggunakan WinUI 2. Lihat referensi API UWP untuk informasi dan contoh spesifik platform.

Bagian ini berisi informasi yang Anda butuhkan untuk menggunakan kontrol di aplikasi UWP atau WinUI 2.

API untuk kontrol ini ada di namespace Windows.UI.Xaml.Controls .

Sebaiknya gunakan WinUI 2 terbaru untuk mendapatkan gaya dan templat terbaru untuk semua kontrol. WinUI 2.2 atau yang lebih baru menyertakan templat baru untuk kontrol ini yang menggunakan sudut bulat. Untuk informasi selengkapnya, lihat Radius sudut.

Membuat kotak edit kaya

Buka aplikasi Galeri WinUI 3 dan lihat RichEditBox beraksi.

Aplikasi WinUI 3 Gallery mencakup contoh interaktif sebagian besar kontrol, fitur, dan fungsi WinUI 3. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub

Secara default, RichEditBox mendukung pemeriksaan ejaan. Untuk menonaktifkan pemeriksa ejaan, atur properti IsSpellCheckEnabled ke false. Untuk informasi selengkapnya, lihat artikel Panduan untuk pemeriksaan ejaan .

Anda menggunakan properti Dokumen dari RichEditBox untuk mendapatkan kontennya. Konten RichEditBox adalah objek ITextDocument , tidak seperti kontrol RichTextBlock, yang menggunakan objek Blokir sebagai kontennya. Antarmuka ITextDocument menyediakan cara untuk memuat dan menyimpan dokumen ke aliran, mengambil rentang teks, mendapatkan pilihan aktif, membatalkan dan mengulangi perubahan, mengatur atribut pemformatan default, dan sebagainya.

Contoh ini memperlihatkan cara mengedit, memuat, dan menyimpan file Rich Text Format (.rtf) di RichEditBox.

<RelativePanel Margin="20" HorizontalAlignment="Stretch">
    <RelativePanel.Resources>
        <Style TargetType="AppBarButton">
            <Setter Property="IsCompact" Value="True"/>
        </Style>
    </RelativePanel.Resources>
    <AppBarButton x:Name="openFileButton" Icon="OpenFile"
                  Click="OpenButton_Click" ToolTipService.ToolTip="Open file"/>
    <AppBarButton Icon="Save" Click="SaveButton_Click"
                  ToolTipService.ToolTip="Save file"
                  RelativePanel.RightOf="openFileButton" Margin="8,0,0,0"/>

    <AppBarButton Icon="Bold" Click="BoldButton_Click" ToolTipService.ToolTip="Bold"
                  RelativePanel.LeftOf="italicButton" Margin="0,0,8,0"/>
    <AppBarButton x:Name="italicButton" Icon="Italic" Click="ItalicButton_Click"
                  ToolTipService.ToolTip="Italic" RelativePanel.LeftOf="underlineButton" Margin="0,0,8,0"/>
    <AppBarButton x:Name="underlineButton" Icon="Underline" Click="UnderlineButton_Click"
                  ToolTipService.ToolTip="Underline" RelativePanel.AlignRightWithPanel="True"/>

    <RichEditBox x:Name="editor" Height="200" RelativePanel.Below="openFileButton"
                 RelativePanel.AlignLeftWithPanel="True" RelativePanel.AlignRightWithPanel="True"/>
</RelativePanel>

private async void OpenButton_Click(object sender, RoutedEventArgs e)
{
    // Open a text file.
    Windows.Storage.Pickers.FileOpenPicker open =
        new Windows.Storage.Pickers.FileOpenPicker();
    open.SuggestedStartLocation =
        Windows.Storage.Pickers.PickerLocationId.DocumentsLibrary;
    open.FileTypeFilter.Add(".rtf");

    Windows.Storage.StorageFile file = await open.PickSingleFileAsync();

    if (file != null)
    {
        try
        {
            Windows.Storage.Streams.IRandomAccessStream randAccStream =
        await file.OpenAsync(Windows.Storage.FileAccessMode.Read);

            // Load the file into the Document property of the RichEditBox.
            editor.Document.LoadFromStream(Windows.UI.Text.TextSetOptions.FormatRtf, randAccStream);
        }
        catch (Exception)
        {
            ContentDialog errorDialog = new ContentDialog()
            {
                Title = "File open error",
                Content = "Sorry, I couldn't open the file.",
                PrimaryButtonText = "Ok"
            };

            await errorDialog.ShowAsync();
        }
    }
}

private async void SaveButton_Click(object sender, RoutedEventArgs e)
{
    Windows.Storage.Pickers.FileSavePicker savePicker = new Windows.Storage.Pickers.FileSavePicker();
    savePicker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.DocumentsLibrary;

    // Dropdown of file types the user can save the file as
    savePicker.FileTypeChoices.Add("Rich Text", new List<string>() { ".rtf" });

    // Default file name if the user does not type one in or select a file to replace
    savePicker.SuggestedFileName = "New Document";

    Windows.Storage.StorageFile file = await savePicker.PickSaveFileAsync();
    if (file != null)
    {
        // Prevent updates to the remote version of the file until we
        // finish making changes and call CompleteUpdatesAsync.
        Windows.Storage.CachedFileManager.DeferUpdates(file);
        // write to file
        Windows.Storage.Streams.IRandomAccessStream randAccStream =
            await file.OpenAsync(Windows.Storage.FileAccessMode.ReadWrite);

        editor.Document.SaveToStream(Windows.UI.Text.TextGetOptions.FormatRtf, randAccStream);

        // Let Windows know that we're finished changing the file so the
        // other app can update the remote version of the file.
        Windows.Storage.Provider.FileUpdateStatus status = await Windows.Storage.CachedFileManager.CompleteUpdatesAsync(file);
        if (status != Windows.Storage.Provider.FileUpdateStatus.Complete)
        {
            Windows.UI.Popups.MessageDialog errorBox =
                new Windows.UI.Popups.MessageDialog("File " + file.Name + " couldn't be saved.");
            await errorBox.ShowAsync();
        }
    }
}

private void BoldButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        charFormatting.Bold = Windows.UI.Text.FormatEffect.Toggle;
        selectedText.CharacterFormat = charFormatting;
    }
}

private void ItalicButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        charFormatting.Italic = Windows.UI.Text.FormatEffect.Toggle;
        selectedText.CharacterFormat = charFormatting;
    }
}

private void UnderlineButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        if (charFormatting.Underline == Windows.UI.Text.UnderlineType.None)
        {
            charFormatting.Underline = Windows.UI.Text.UnderlineType.Single;
        }
        else {
            charFormatting.Underline = Windows.UI.Text.UnderlineType.None;
        }
        selectedText.CharacterFormat = charFormatting;
    }
}

Pilih keyboard yang tepat untuk kontrol teks Anda

Untuk membantu pengguna memasukkan data menggunakan keyboard sentuh, atau Panel Input Lunak (SIP), Anda dapat mengatur cakupan input kontrol teks agar sesuai dengan jenis data yang diharapkan dimasukkan pengguna. Tata letak keyboard default biasanya sesuai untuk bekerja dengan dokumen teks kaya.

Untuk informasi selengkapnya tentang cara menggunakan cakupan input, lihat Menggunakan cakupan input untuk mengubah keyboard sentuh.

Dapatkan kode sampel