Ссылки на содержимое в текстовых элементах управления

Ссылки на содержимое предоставляют способ внедрения расширенных данных в текстовые элементы управления, что позволяет пользователю находить и использовать дополнительные сведения о человеке или месте без выхода из контекста приложения.

Когда пользователь предваряет запись знаком at (@) в RichEditBox, отображается список людей и/или предложений мест, соответствующих записи. Затем, например, когда пользователь выбирает место, ContentLink для этого места вставляется в текст. Когда пользователь вызывает ссылку на содержимое из RichEditBox, всплывающий элемент отображается с картой и дополнительными сведениями о месте.

Важные API: класс ContentLink, класс ContentLinkInfo, класс RichEditTextRange

Ссылки на контент в элементах управления форматированным текстом и текстовым блоком

Существует два разных способа использования ссылок на содержимое:

1. В RichEditBox пользователь может открыть средство выбора, чтобы добавить ссылку на содержимое, префиксируя текст с символом @. Ссылка на содержимое хранится как часть содержимого с форматированным текстом.
2. В TextBlock или RichTextBlockссылка на содержимое — это текстовый элемент, аналогичный гиперссылкепо использованию и поведению.

Вот как ссылки на содержимое выглядят по умолчанию в RichEditBox и в TextBlock.

ссылка

Различия в использовании, отрисовке и поведении подробно описаны в следующих разделах. Эта таблица позволяет быстро сравнить основные различия между ссылкой на содержимое в RichEditBox и текстовом блоке.

Включение ссылок на содержимое в RichEditBox

Наиболее распространенное использование ссылки на содержимое заключается в том, чтобы пользователь быстро добавлял информацию путем префикса пользователя или имени места с символом амперсанда (@) в тексте. Когда этот параметр включен в RichEditBox, открывается средство выбора, которое позволяет пользователю вставлять человека из своего списка контактов или близлежащее место, в зависимости от того, что именно активировано.

Ссылка на содержимое может быть сохранена с содержимым форматированного текста, и ее можно извлечь для использования в других частях приложения. Например, в почтовом приложении вы можете извлечь информацию о пользователе и использовать её, чтобы заполнить поле "Кому" адресом электронной почты.

Поставщики ссылок на содержимое

Чтобы включить ссылки на содержимое в RichEditBox, добавьте одного или нескольких поставщиков ссылок на содержимое в коллекцию RichEditBox.ContentLinkProviders . Существует 2 поставщика ссылок на содержимое, встроенные в платформу XAML.

• ContactContentLinkProvider — ищет контакты с помощью приложения людей.
• PlaceContentLinkProvider — ищет места с помощью приложения Maps.

Вот как добавить поставщиков ссылок на содержимое в XAML.

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

Вы также можете добавить поставщиков ссылок на содержимое в Style и применить его к нескольким RichEditBoxes вот так.

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

Вот как добавить поставщиков ссылок содержимого в код.

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

Цвета ссылок на содержимое

Внешний вид ссылки на содержимое определяется его передним планом, фоном и значком. В RichEditBox можно задать свойства ContentLinkForegroundColor и ContentLinkBackgroundColor для изменения цветов по умолчанию.

Невозможно задать курсор. Курсор отображается в RichEditbox в зависимости от типа ссылки на содержимое — курсор Персона для ссылки на личность или курсор Место для ссылки на местоположение.

Объект ContentLinkInfo

Когда пользователь делает выбор из списка людей или мест, система создает объект ContentLinkInfo и добавляет его в свойство ContentLinkInfo текущего RichEditTextRange.

Объект ContentLinkInfo содержит сведения, используемые для отображения, вызова и управления ссылкой на содержимое.

• DisplayText — это строка, отображаемая при отрисовке ссылки на содержимое. В RichEditBox пользователь может изменить текст ссылки на содержимое после его создания, что изменяет значение этого свойства.
• SecondaryText — эта строка отображается в подсказке отображаемой ссылки на содержимое.
  • В ссылке на содержимое места, созданной средством выбора, содержится адрес, если он доступен.
• URI — ссылка на дополнительные сведения о тематическом содержимом. Этот URI может открыть установленное приложение или веб-сайт.
• идентификатор — это счетчик только для чтения, создаваемый для каждого элемента управления элементом управления RichEditBox. Он используется для отслеживания этого ContentLinkInfo во время таких действий, как удаление или изменение. Если ContentLinkInfo вырезается и вставляется обратно в элемент управления, он получит новый идентификатор. Значения идентификатора являются добавочными.
• LinkContentKind — строка, описывающая тип ссылки на содержимое. Встроенные типы контента — это Места и Контакты. Учитывается регистр значения.

Тип содержимого ссылки

Существует несколько ситуаций, когда LinkContentKind имеет важное значение.

• Когда пользователь копирует ссылку на содержимое из RichEditBox и вставляет его в другой RichEditBox, оба элемента управления должны иметь ContentLinkProvider для этого типа контента. В противном случае ссылка вставлена в виде текста.
• LinkContentKind можно использовать в обработчике событий ContentLinkChanged, чтобы определить, что делать с ссылкой на содержимое при использовании в других частях приложения. Дополнительные сведения см. в разделе "Пример".
• LinkContentKind влияет на то, как система открывает URI при вызове ссылки. Мы рассмотрим это дальше при обсуждении запуска Uri.

Запуск URI

Свойство URI работает так же, как свойство NavigateUri гиперссылки. Когда пользователь щелкает его, он запускает URI в браузере по умолчанию или в приложении, зарегистрированном для определенного протокола, указанного в значении URI.

Здесь описано конкретное поведение для 2 встроенных типов содержимого ссылки.

Места

Средство выбора местоположения создает объект ContentLinkInfo с корнем URI https://maps.windows.com/. Эту ссылку можно открыть 3 способами:

• Если LinkContentKind = "Места", откроется информационная карточка во всплывающем окне. Всплывающее меню аналогично меню выбора ссылок содержимого. Она входит в состав Windows и выполняется в отдельном процессе приложения.
• Если LinkContentKind не является "Places", он пытается открыть приложение Maps в указанном расположении. Например, это может произойти, если вы изменили LinkContentKind в обработчике событий ContentLinkChanged.
• Если URI не удается открыть в приложении "Карты", карта открывается в браузере по умолчанию. Обычно это происходит, когда настройки приложений для веб-сайтов не позволяют открывать Uri с помощью приложения Maps.

Люди

Средство выбора "Люди" создает ContentLinkInfo с URI, использующим протокол ms-people.

• Если LinkContentKind = "Люди", откроется информационная карточка в выпадающем окне. Всплывающее меню аналогично меню выбора ссылок содержимого. Она входит в состав Windows и выполняется в отдельном процессе приложения.
• Если LinkContentKind не "Люди", откроется приложение "Люди". Например, это может произойти, если вы изменили LinkContentKind в обработчике событий ContentLinkChanged.

Вызывается

Когда пользователь вызывает ссылку на содержимое, событие ContentLinkInvoked возникает до того, как будет происходить поведение по умолчанию при запуске URI. Это событие можно обрабатывать для переопределения или отмены поведения по умолчанию.

В этом примере показано, как переопределить поведение запуска по умолчанию для ссылки на содержимое Place. Вместо открытия карты через карточку информации о месте, приложение "Карты" или веб-браузер по умолчанию, вы помечаете событие как завершенное и открываете карту в элементе управления WebView.

<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 можно использовать для уведомления при добавлении, изменении или удалении ссылки на содержимое. Это позволяет извлечь ссылку на содержимое из текста и использовать ее в других местах в приложении. Это показано далее в разделе "Примеры".

Свойства ContentLinkChangedEventArgs:

• ChangedKind — перечисление ContentLinkChangeKind представляет собой действие в ContentLink. Например, если ContentLink вставляется, удаляется или редактируется.
• Info — объект ContentLinkInfo, который был целью действия.

Это событие вызывается для каждого действия ContentLinkInfo. Например, если пользователь копирует и вставляет несколько ссылок содержимого в RichEditBox одновременно, это событие вызывается для каждого добавленного элемента. Или если пользователь выбирает и удаляет несколько ссылок на содержимое одновременно, это событие вызывается для каждого удаленного элемента.

Это событие генерируется в RichEditBox после события TextChanging и до события TextChanged.

Перечисление ссылок на содержимое в RichEditBox

Свойство RichEditTextRange.ContentLink можно использовать для получения ссылки на содержимое из документа с расширенными возможностями редактирования. Перечисление TextRangeUnit имеет значение ContentLink, чтобы указать ссылку на содержимое как единицу, используемую при переходе по текстовому диапазону.

В этом примере показано, как перечислить все ссылки на содержимое в RichEditBox и извлечь людей в список.

<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);
}

Текстовый элемент ContentLink

Чтобы использовать ссылку на содержимое в элементе управления TextBlock или RichTextBlock, используйте текстовый элемент ContentLink (из пространства имен Windows.UI.Xaml.Documents).

Типичные источники для КонтентСсылки в текстовом блоке:

• Ссылка на содержимое, созданная с помощью средства выбора, которое вы извлекли из элемента управления RichTextBlock.
• Ссылка на содержимое для объекта, создаваемого в вашем коде.

Для других ситуаций текстовый элемент Гиперссылки обычно подходит.

Внешний вид ContentLink

Внешний вид ссылки на содержимое определяется его передним планом, фоном и курсором. В текстовом блоке можно задать передний план (из TextElement) и свойства фона, чтобы изменить цвета по умолчанию.

По умолчанию курсор руки отображается при наведении указателя мыши на ссылку содержимого. В отличие от RichEditBlock, элементы управления блоком текста не изменяют курсор автоматически на основе типа ссылки. Свойство Cursor можно задать для изменения курсора на основе типа ссылки или других факторов.

Ниже приведен пример ContentLink, используемый в TextBlock. ContentLinkInfo создается в коде и назначается свойству Info текстового элемента ContentLink, созданного в 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;
}

Примеры

В этом примере пользователь может ввести человека или поместить ссылку на содержимое в RickTextBlock. Вы обрабатываете событие ContentLinkChanged, чтобы извлечь ссылки на содержимое и сохранить их up-to-date в списке людей или списке мест.

В шаблонах элементов для списков используется textBlock с текстовым элементом ContentLink для отображения сведений о ссылке на содержимое. ListView предоставляет собственный фон для каждого элемента, поэтому фон ContentLink имеет значение "Прозрачный".

<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);
    }
}