Tautan konten dalam kontrol teks

Tautan konten menyediakan cara untuk menyematkan data kaya di kontrol teks Anda, yang memungkinkan pengguna menemukan dan menggunakan informasi selengkapnya tentang seseorang atau tempat tanpa meninggalkan konteks aplikasi Anda.

Penting

Fitur Windows yang mengaktifkan tautan konten tidak tersedia di versi Windows setelah Windows 10 versi 1903. Tautan konten untuk kontrol teks XAML tidak akan berfungsi dalam versi Windows yang lebih baru dari versi 1903.

Saat pengguna mengawali entri dengan simbol at (@) di RichEditBox, mereka akan menampilkan daftar saran orang dan/atau tempat yang cocok dengan entri. Kemudian, misalnya, saat pengguna memilih tempat, ContentLink untuk tempat tersebut disisipkan ke dalam teks. Saat pengguna memanggil tautan konten dari RichEditBox, flyout ditampilkan dengan peta dan info tambahan tentang tempat tersebut.

API Penting: Kelas ContentLink, kelas ContentLinkInfo, kelas RichEditTextRange

Catatan

API untuk tautan konten tersebar di namespace berikut: Windows.UI.Xaml.Controls, Windows.UI.Xaml.Documents, dan Windows.UI.Text.

Tautan konten dalam kontrol edit kaya vs. blok teks

Ada dua cara berbeda untuk menggunakan tautan konten:

1. Di RichEditBox, pengguna dapat membuka pemilih untuk menambahkan tautan konten dengan mengawali teks dengan simbol @. Tautan konten disimpan sebagai bagian dari konten teks kaya.
2. Dalam TextBlock atau RichTextBlock, tautan konten adalah elemen teks dengan penggunaan dan perilaku seperti Hyperlink.

Berikut tampilan tautan konten secara default di RichEditBox dan di TextBlock.

Perbedaan penggunaan, penyajian, dan perilaku dibahas secara rinci di bagian berikut. Tabel ini memberikan perbandingan cepat perbedaan utama antara tautan konten di RichEditBox dan blok teks.

Fitur	RichEditBox	blok teks
Penggunaan	Instans ContentLinkInfo	Elemen teks ContentLink
Kursor	Ditentukan oleh jenis tautan konten, tidak dapat diubah	Ditentukan oleh properti Kursor, null secara default
ToolTip	Tidak dirender	Memperlihatkan teks sekunder

Mengaktifkan tautan konten di RichEditBox

Penggunaan tautan konten yang paling umum adalah membiarkan pengguna dengan cepat menambahkan informasi dengan memberi awalan nama orang atau tempat dengan simbol ampersand (@) dalam teks mereka. Saat diaktifkan di RichEditBox, ini membuka pemilih dan memungkinkan pengguna menyisipkan seseorang dari daftar kontak mereka, atau tempat terdekat, tergantung pada apa yang telah Anda aktifkan.

Tautan konten dapat disimpan dengan konten teks kaya, dan Anda dapat mengekstraknya untuk digunakan di bagian lain aplikasi Anda. Misalnya, di aplikasi email, Anda mungkin mengekstrak info orang tersebut dan menggunakannya untuk mengisi kotak Kepada dengan alamat email.

Catatan

Pemilih tautan konten adalah aplikasi yang merupakan bagian dari Windows, sehingga berjalan dalam proses terpisah dari aplikasi Anda.

Penyedia tautan konten

Anda mengaktifkan tautan konten di RichEditBox dengan menambahkan satu atau beberapa penyedia tautan konten ke koleksi RichEditBox.ContentLinkProviders . Ada 2 penyedia tautan konten yang disertakan dalam kerangka kerja XAML.

• ContactContentLinkProvider – mencari kontak menggunakan aplikasi Orang.
• PlaceContentLinkProvider – mencari tempat menggunakan aplikasi Peta.

Penting

Nilai default untuk properti RichEditBox.ContentLinkProviders adalah null, bukan koleksi kosong. Anda perlu secara eksplisit membuat ContentLinkProviderCollection sebelum Anda menambahkan penyedia tautan konten.

Berikut cara menambahkan penyedia tautan konten di XAML.

<RichEditBox>
    <RichEditBox.ContentLinkProviders>
        <ContentLinkProviderCollection>
            <ContactContentLinkProvider/>
            <PlaceContentLinkProvider/>
        </ContentLinkProviderCollection>
    </RichEditBox.ContentLinkProviders>
</RichEditBox>

Anda juga dapat menambahkan penyedia tautan konten dalam Gaya dan menerapkannya ke beberapa RichEditBoxes seperti ini.

<Page.Resources>
    <Style TargetType="RichEditBox" x:Key="ContentLinkStyle">
        <Setter Property="ContentLinkProviders">
            <Setter.Value>
                <ContentLinkProviderCollection>
                    <PlaceContentLinkProvider/>
                    <ContactContentLinkProvider/>
                </ContentLinkProviderCollection>
            </Setter.Value>
        </Setter>
    </Style>
</Page.Resources>

<RichEditBox x:Name="RichEditBox01" Style="{StaticResource ContentLinkStyle}" />
<RichEditBox x:Name="RichEditBox02" Style="{StaticResource ContentLinkStyle}" />

Berikut cara menambahkan penyedia tautan konten dalam kode.

RichEditBox editor = new RichEditBox();
editor.ContentLinkProviders = new ContentLinkProviderCollection
{
    new ContactContentLinkProvider(),
    new PlaceContentLinkProvider()
};

Warna tautan konten

Tampilan tautan konten ditentukan oleh latar depan, latar belakang, dan ikonnya. Dalam RichEditBox, Anda dapat mengatur properti ContentLinkForegroundColor dan ContentLinkBackgroundColor untuk mengubah warna default.

Anda tidak dapat mengatur kursor. Kursor dirender oleh RichEditbox berdasarkan jenis tautan konten - kursor Orang untuk tautan orang, atau kursor Pin untuk tautan tempat.

Objek ContentLinkInfo

Ketika pengguna membuat pilihan dari pemilih orang atau tempat, sistem membuat objek ContentLinkInfo dan menambahkannya ke properti ContentLinkInfo dari RichEditTextRange saat ini.

Objek ContentLinkInfo berisi informasi yang digunakan untuk menampilkan, memanggil, dan mengelola tautan konten.

• DisplayText – Ini adalah string yang ditampilkan saat tautan konten dirender. Di RichEditBox, pengguna dapat mengedit teks tautan konten setelah dibuat, yang mengubah nilai properti ini.
• SecondaryText – String ini ditampilkan di tipsalat tautan konten yang dirender.
  • Di tautan Tempatkan konten yang dibuat oleh pemilih, tautan berisi alamat lokasi, jika tersedia.
• Uri – Tautan ke informasi selengkapnya tentang subjek tautan konten. Uri ini dapat membuka aplikasi atau situs web yang diinstal.
• Id - Ini adalah penghitung baca-saja, per kontrol yang dibuat oleh kontrol RichEditBox. Ini digunakan untuk melacak ContentLinkInfo ini selama tindakan seperti menghapus atau mengedit. Jika ContentLinkInfo dipotong dan ditempelkan kembali ke kontrol, nilai Id akan mendapatkan Id baru. Nilai id bertahas.
• LinkContentKind – String yang menjelaskan jenis tautan konten. Tipe konten bawaan adalah Tempat dan Kontak. Nilai ini peka huruf besar/kecil.

Menautkan jenis konten

Ada beberapa situasi di mana LinkContentKind penting.

• Saat pengguna menyalin tautan konten dari RichEditBox dan menempelkannya ke RichEditBox lain, kedua kontrol harus memiliki ContentLinkProvider untuk tipe konten tersebut. Jika tidak, tautan ditempelkan sebagai teks.
• Anda dapat menggunakan LinkContentKind di penanganan aktivitas ContentLinkChanged untuk menentukan apa yang harus dilakukan dengan tautan konten saat Anda menggunakannya di bagian lain aplikasi Anda. Lihat bagian Contoh untuk informasi selengkapnya.
• LinkContentKind memengaruhi bagaimana sistem membuka Uri saat tautan dipanggil. Kita akan melihat ini dalam diskusi peluncuran Uri berikutnya.

Peluncuran Uri

Properti Uri berfungsi seperti properti NavigateUri hyperlink. Saat pengguna mengkliknya, pengguna meluncurkan Uri di browser default, atau di aplikasi yang terdaftar untuk protokol tertentu yang ditentukan dalam nilai Uri.

Perilaku khusus untuk 2 konten tautan bawaan dijelaskan di sini.

Memesan

Pemilih Tempat membuat ContentLinkInfo dengan akar Uri .https://maps.windows.com/ Tautan ini dapat dibuka dengan 3 cara:

• Jika LinkContentKind = "Places", link akan membuka kartu info di flyout. Flyout mirip dengan flyout pemilih tautan konten. Ini adalah bagian dari Windows, dan berjalan dalam proses terpisah dari aplikasi Anda.
• Jika LinkContentKind bukan "Places", LinkContentKind mencoba membuka aplikasi Peta ke lokasi yang ditentukan. Misalnya, ini dapat terjadi jika Anda telah memodifikasi LinkContentKind di penanganan aktivitas ContentLinkChanged.
• Jika Uri tidak dapat dibuka di aplikasi Peta, peta dibuka di browser default. Ini biasanya terjadi ketika pengaturan Aplikasi untuk situs web pengguna tidak mengizinkan membuka Uri dengan aplikasi Peta.

Sosial

Pemilih Orang membuat ContentLinkInfo dengan Uri yang menggunakan protokol ms-people.

• Jika LinkContentKind = "Orang", link akan membuka kartu info dalam flyout. Flyout mirip dengan flyout pemilih tautan konten. Ini adalah bagian dari Windows, dan berjalan dalam proses terpisah dari aplikasi Anda.
• Jika LinkContentKind bukan "Orang", LinkContentKind akan membuka aplikasi Orang. Misalnya, ini dapat terjadi jika Anda telah memodifikasi LinkContentKind di penanganan aktivitas ContentLinkChanged.

Tip

Untuk informasi selengkapnya tentang membuka aplikasi dan situs web lain dari aplikasi Anda, lihat topik di bawah Luncurkan aplikasi dengan Uri.

Dipanggil

Saat pengguna memanggil tautan konten, peristiwa ContentLinkInvoked dinaikkan sebelum perilaku default meluncurkan Uri terjadi. Anda dapat menangani peristiwa ini untuk mengambil alih atau membatalkan perilaku default.

Contoh ini menunjukkan bagaimana Anda dapat mengambil alih perilaku peluncuran default untuk tautan Tempatkan konten. Alih-alih membuka peta di kartu info Tempat, aplikasi Peta, atau browser web default, Anda menandai peristiwa sebagai Ditangani dan membuka peta dalam kontrol WebView dalam aplikasi.

<RichEditBox x:Name="editor"
             ContentLinkInvoked="editor_ContentLinkInvoked">
    <RichEditBox.ContentLinkProviders>
        <ContentLinkProviderCollection>
            <PlaceContentLinkProvider/>
        </ContentLinkProviderCollection>
    </RichEditBox.ContentLinkProviders>
</RichEditBox>

<WebView x:Name="webView1"/>

private void editor_ContentLinkInvoked(RichEditBox sender, ContentLinkInvokedEventArgs args)
{
    if (args.ContentLinkInfo.LinkContentKind == "Places")
    {
        args.Handled = true;
        webView1.Navigate(args.ContentLinkInfo.Uri);
    }
}

ContentLinkChanged

Anda dapat menggunakan peristiwa ContentLinkChanged untuk diberi tahu saat tautan konten ditambahkan, dimodifikasi, atau dihapus. Ini memungkinkan Anda mengekstrak tautan konten dari teks dan menggunakannya di tempat lain di aplikasi Anda. Ini ditampilkan nanti di bagian Contoh.

Properti ContentLinkChangedEventArgs adalah:

• ChangedKind - Enum ContentLinkChangeKind ini adalah tindakan dalam ContentLink. Misalnya, jika ContentLink disisipkan, dihapus, atau diedit.
• Info - ContentLinkInfo yang menjadi target tindakan.

Kejadian ini dimunculkan untuk setiap tindakan ContentLinkInfo. Misalnya, jika pengguna menyalin dan menempelkan beberapa tautan konten ke RichEditBox sekaligus, peristiwa ini dinaikkan untuk setiap item yang ditambahkan. Atau jika pengguna memilih dan menghapus beberapa tautan konten secara bersamaan, peristiwa ini dinaikkan untuk setiap item yang dihapus.

Kejadian ini dinaikkan pada RichEditBox setelah peristiwa TextChanging dan sebelum peristiwa TextChanged .

Menghitung tautan konten di RichEditBox

Anda bisa menggunakan properti RichEditTextRange.ContentLink untuk mendapatkan tautan konten dari dokumen edit yang kaya. Enumerasi TextRangeUnit memiliki nilai ContentLink untuk menentukan tautan konten sebagai unit yang akan digunakan saat menavigasi rentang teks.

Contoh ini memperlihatkan bagaimana Anda dapat menghitung semua tautan konten di RichEditBox, dan mengekstrak orang ke dalam daftar.

<StackPanel Width="300">
    <RichEditBox x:Name="Editor" Height="200">
        <RichEditBox.ContentLinkProviders>
            <ContentLinkProviderCollection>
                <ContactContentLinkProvider/>
                <PlaceContentLinkProvider/>
            </ContentLinkProviderCollection>
        </RichEditBox.ContentLinkProviders>
    </RichEditBox>

    <Button Content="Get people" Click="Button_Click"/>

    <ListView x:Name="PeopleList" Header="People">
        <ListView.ItemTemplate>
            <DataTemplate x:DataType="ContentLinkInfo">
                <TextBlock>
                    <ContentLink Info="{x:Bind}" Background="Transparent"/>
                </TextBlock>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>
</StackPanel>

private void Button_Click(object sender, RoutedEventArgs e)
{
    PeopleList.Items.Clear();
    RichEditTextRange textRange = Editor.Document.GetRange(0, 0) as RichEditTextRange;

    do
    {
        // The Expand method expands the Range EndPosition 
        // until it finds a ContentLink range. 
        textRange.Expand(TextRangeUnit.ContentLink);
        if (textRange.ContentLinkInfo != null
            && textRange.ContentLinkInfo.LinkContentKind == "People")
        {
            PeopleList.Items.Add(textRange.ContentLinkInfo);
        }
    } while (textRange.MoveStart(TextRangeUnit.ContentLink, 1) > 0);
}

Elemen teks ContentLink

Untuk menggunakan tautan konten dalam kontrol TextBlock atau RichTextBlock, Anda menggunakan elemen teks ContentLink (dari namespace Layanan Windows.UI.Xaml.Documents).

Sumber umum untuk ContentLink dalam blok teks adalah:

• Tautan konten yang dibuat oleh pemilih yang Anda ekstrak dari kontrol RichTextBlock.
• Tautan konten untuk tempat yang Anda buat dalam kode Anda.

Untuk situasi lain, elemen teks Hyperlink biasanya sesuai.

Tampilan ContentLink

Tampilan tautan konten ditentukan oleh latar depan, latar belakang, dan kursornya. Dalam blok teks, Anda dapat mengatur properti Latar Depan (dari TextElement) dan Latar Belakang untuk mengubah warna default.

Secara default, kursor Tangan ditampilkan saat pengguna mengarahkan kursor ke tautan konten. Tidak seperti RichEditBlock, kontrol blok teks tidak mengubah kursor secara otomatis berdasarkan jenis tautan. Anda dapat mengatur properti Kursor untuk mengubah kursor berdasarkan jenis tautan atau faktor lainnya.

Berikut adalah contoh ContentLink yang digunakan dalam TextBlock. ContentLinkInfo dibuat dalam kode dan ditetapkan ke properti Info elemen teks ContentLink yang dibuat di XAML.

<StackPanel>
    <TextBlock>
        <Span xml:space="preserve">
            <Run>This volcano erupted in 1980: </Run><ContentLink x:Name="placeContentLink" Cursor="Pin"/>
            <LineBreak/>
        </Span>
    </TextBlock>

    <Button Content="Show" Click="Button_Click"/>
</StackPanel>

private void Button_Click(object sender, RoutedEventArgs e)
{
    var info = new Windows.UI.Text.ContentLinkInfo();
    info.DisplayText = "Mount St. Helens";
    info.SecondaryText = "Washington State";
    info.LinkContentKind = "Places";
    info.Uri = new Uri("https://maps.windows.com?cp=46.1912~-122.1944");
    placeContentLink.Info = info;
}

Tip

Saat Anda menggunakan ContentLink dalam kontrol teks dengan elemen teks lain di XAML, tempatkan konten dalam kontainer Rentang dan terapkan xml:space="preserve" atribut ke Rentang untuk mempertahankan spasi kosong antara ContentLink dan elemen lainnya.

Contoh

Dalam contoh ini, pengguna dapat memasukkan seseorang atau menempatkan tautan konten ke dalam RickTextBlock. Anda menangani peristiwa ContentLinkChanged untuk mengekstrak tautan konten dan selalu memperbaruinya di daftar orang atau daftar tempat.

Dalam templat item untuk daftar, Anda menggunakan TextBlock dengan elemen teks ContentLink untuk menampilkan info tautan konten. ListView menyediakan latar belakangnya sendiri untuk setiap item, sehingga latar belakang ContentLink diatur ke Transparan.

<StackPanel Orientation="Horizontal" Grid.Row="1">
    <RichEditBox x:Name="Editor"
                 ContentLinkChanged="Editor_ContentLinkChanged"
                 Margin="20" Width="300" Height="200"
                 VerticalAlignment="Top">
        <RichEditBox.ContentLinkProviders>
            <ContentLinkProviderCollection>
                <ContactContentLinkProvider/>
                <PlaceContentLinkProvider/>
            </ContentLinkProviderCollection>
        </RichEditBox.ContentLinkProviders>
    </RichEditBox>

    <ListView x:Name="PeopleList" Header="People">
        <ListView.ItemTemplate>
            <DataTemplate x:DataType="ContentLinkInfo">
                <TextBlock>
                    <ContentLink Info="{x:Bind}"
                                 Background="Transparent"
                                 Cursor="Person"/>
                </TextBlock>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>

    <ListView x:Name="PlacesList" Header="Places">
        <ListView.ItemTemplate>
            <DataTemplate x:DataType="ContentLinkInfo">
                <TextBlock>
                    <ContentLink Info="{x:Bind}"
                                 Background="Transparent"
                                 Cursor="Pin"/>
                </TextBlock>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>
</StackPanel>

private void Editor_ContentLinkChanged(RichEditBox sender, ContentLinkChangedEventArgs args)
{
    var info = args.ContentLinkInfo;
    var change = args.ChangeKind;
    ListViewBase list = null;

    // Determine whether to update the people or places list.
    if (info.LinkContentKind == "People")
    {
        list = PeopleList;
    }
    else if (info.LinkContentKind == "Places")
    {
        list = PlacesList;
    }

    // Determine whether to add, delete, or edit.
    if (change == ContentLinkChangeKind.Inserted)
    {
        Add();
    }
    else if (args.ChangeKind == ContentLinkChangeKind.Removed)
    {
        Remove();
    }
    else if (change == ContentLinkChangeKind.Edited)
    {
        Remove();
        Add();
    }

    // Add content link info to the list. It's bound to the
    // Info property of a ContentLink in XAML.
    void Add()
    {
        list.Items.Add(info);
    }

    // Use ContentLinkInfo.Id to find the item,
    // then remove it from the list using its index.
    void Remove()
    {
        var items = list.Items.Where(i => ((ContentLinkInfo)i).Id == info.Id);
        var item = items.FirstOrDefault();
        var idx = list.Items.IndexOf(item);

        list.Items.RemoveAt(idx);
    }
}