テキスト制御のコンテンツリンク

[アーティクル]
12/29/2023

コンテンツリンクにより、テキストコントロールにリッチデータを埋め込むことができます。これによってユーザーは、アプリのコンテキストから離れることなく、人物や場所に関する詳しい情報を見つけることができます。

重要

コンテンツリンクを可能にする Windows の機能は、Windows 10 バージョン 1903 より後のバージョンの Windows では利用できません。 XAML テキストコントロールのコンテンツリンクは、バージョン 1903 より後のバージョンの Windows では機能しません。

RichEditBox でユーザーがアットマーク (@) を使用してエントリにプレフィックスを付けると、そのエントリに一致する人々および/または場所の候補のリストが表示されます。たとえば、ユーザーが場所を選択すると、その場所の ContentLink がテキストに挿入されます。ユーザーが RichEditBox からコンテンツリンクを呼び出すと、ポップアップがマップと場所に関する追加情報と共に表示されます。

重要な API: ContentLink クラス、ContentLinkInfo クラス、RichEditTextRange クラス

Note

コンテンツリンクの API は、Windows.UI.Xaml.Controls、Windows.UI.Xaml.Documents、Windows.UI.Text の各名前空間に分散されます。

リッチエディットコントロールとテキストブロックコントロールのコンテンツリンク

コンテンツリンクを使用するには、次の 2 つの異なる方法があります。

RichEditBox では、ユーザーはピッカーを開き、テキストの前に @ 記号を付けることでコンテンツリンクを追加できます。コンテンツリンクは、リッチテキストコンテンツの一部として格納されます。
TextBlock または RichTextBlock では、コンテンツリンクはハイパーリンクと同様の使用法と動作を持つテキスト要素です。

RichEditBox と TextBlock のコンテンツリンクの既定の外観を次に示します。

リッチエディットボックスのコンテンツリンクテキストブロック内のコンテンツリンク

使用方法、レンダリング、動作の違いについては、次のセクションで詳しく説明します。次の表は、RichEditBox のコンテンツリンクとテキストブロックのメインの違いを簡単に比較したものです。

機能	RichEditBox	テキストブロック
使用方法	ContentLinkInfo のインスタンス	ContentLink テキスト要素
Cursor	コンテンツリンクの種類によって決まる、変更できません	Cursor プロパティによって決定され、既定では null です
ToolTip	レンダリングされていない	セカンダリテキストを表示する

RichEditBox でコンテンツリンクを有効にする

コンテンツリンクの最も一般的な用途は、ユーザーがテキストにアンパサンド (@) 記号を付けることで、ユーザーに情報をすばやく追加できるようにすることです。 RichEditBox で有効にすると、ピッカーが開き、ユーザーは、有効にした内容に応じて、連絡先リストまたは近くの場所からユーザーを挿入できます。

コンテンツリンクはリッチテキストコンテンツと共に保存でき、それを抽出してアプリの他の部分で使用できます。たとえば、メールアプリでは、ユーザー情報を抽出し、それを使用して [宛先] ボックスにメールアドレスを設定できます。

Note

コンテンツリンクピッカーは Windows の一部であるアプリであるため、アプリとは別のプロセスで実行されます。

コンテンツリンクプロバイダー

RichEditBox でコンテンツリンクを有効にするには、1 つ以上のコンテンツリンクプロバイダーを RichEditBox.ContentLinkProviders コレクションに追加します。 XAML フレームワークには、2 つのコンテンツリンクプロバイダーが組み込まれています。

ContactContentLinkProvider – People アプリを使用して連絡先を検索します。
PlaceContentLinkProvider – Maps アプリを使用して場所を検索します。

重要

RichEditBox.ContentLinkProviders プロパティの既定値は null であり、空のコレクションではありません。コンテンツリンクプロバイダーを追加する前に、ContentLinkProviderCollection を明示的に作成する必要があります。

XAML でコンテンツリンクプロバイダーを追加する方法を次に示します。

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

このように、スタイルにコンテンツリンクプロバイダーを追加し、それを複数の RichEditBox に適用することもできます。

<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 プロパティを設定して、既定の色を変更できます。

カーソルを設定することはできません。カーソルは、コンテンツリンクの種類 (人物リンクの場合は Person カーソル、場所リンクの場合はピンカーソル) に基づいて RichEditbox によってレンダリングされます。

ContentLinkInfo オブジェクト

ユーザーがユーザーまたは場所の選択ウィンドウから選択を行うと、システムによって ContentLinkInfo オブジェクトが作成され、現在の RichEditTextRange の ContentLinkInfo プロパティに追加されます。

ContentLinkInfo オブジェクトには、コンテンツリンクの表示、呼び出し、管理に使用される情報が含まれています。

DisplayText – コンテンツリンクがレンダリングされるときに表示される文字列です。 RichEditBox では、ユーザーはコンテンツリンクの作成後にテキストを編集できます。これにより、このプロパティの値が変更されます。
SecondaryText – この文字列は、レンダリングされたコンテンツリンクのツールチップに表示されます。
- ピッカーによって作成された [場所] コンテンツリンクには、場所のアドレス (使用可能な場合) が含まれます。
Uri – コンテンツリンクの件名に関する詳細情報へのリンク。この URI は、インストールされているアプリまたは Web サイトを開くことができます。
Id - これは、RichEditBox コントロールによって作成された、コントロールごとの読み取り専用のカウンターです。これは、削除や編集などのアクション中にこの ContentLinkInfo を追跡するために使用されます。 ContentLinkInfo が切り取られてコントロールに貼り付けられると、新しい Id が取得されます。ID 値は増分されます。
LinkContentKind – コンテンツリンクの種類を記述する文字列。組み込みのコンテンツタイプは、場所と 連絡先です。この値は大文字と小文字の区別があります。

リンクコンテンツの種類

LinkContentKind が重要となる状況がいくつかあります。

ユーザーが RichEditBox からコンテンツリンクをコピーして別の RichEditBox に貼り付ける場合、両方のコントロールにそのコンテンツタイプの ContentLinkProvider が必要です。そうでない場合、リンクはテキストとして貼り付けられます。
ContentLinkChanged イベントハンドラーで LinkContentKind を使用して、アプリの他の部分でコンテンツリンクを使用する場合のコンテンツリンクの操作を決定できます。詳細については、「例」のセクションを参照してください。
LinkContentKind は、リンクが呼び出されたときにシステムが URI を開く方法に影響します。これは、次に起動する URI の説明で確認できます。

URI の起動

Uri プロパティは、ハイパーリンクの NavigateUri プロパティと類似しています。ユーザーがクリックすると、既定のブラウザーまたは Uri 値で指定された特定のプロトコルに登録されているアプリで URI が起動されます。

ここでは、組み込まれている 2 種類のリンクコンテンツの具体的な動作について説明します。

場所

Places ピッカーは、https://maps.windows.com/ の Uri ルートを使用して ContentLinkInfo を作成します。このリンクは、次の 3 つの方法で開くことができます。

LinkContentKind = "Places" の場合は、ポップアップにカード情報が開きます。ポップアップは、コンテンツリンクピッカーのポップアップに類似しています。これは Windows の一部であり、アプリとは別のプロセスで実行されます。
LinkContentKind が "Places" でない場合は、指定した場所に Maps アプリを開こうとします。たとえば、これは、ContentLinkChanged イベントハンドラーで LinkContentKind を変更した場合に発生する可能性があります。
Maps アプリで URI を開くことができない場合、マップは既定のブラウザーで開かれます。これは通常、ユーザーの [Web サイト用アプリ] 設定で、マップ アプリで URI を開くことができない場合に発生します。

ユーザー

People ピッカーは、ms-people プロトコルを使用する URI を持つ ContentLinkInfo を作成します。

LinkContentKind = "People" の場合は、ポップアップにカード情報が開きます。ポップアップは、コンテンツリンクピッカーのポップアップに類似しています。これは Windows の一部であり、アプリとは別のプロセスで実行されます。
LinkContentKind が "People" でない場合は、People アプリが開きます。たとえば、これは、ContentLinkChanged イベントハンドラーで LinkContentKind を変更した場合に発生する可能性があります。

ヒント

アプリから他のアプリや Web サイトを開く方法の詳細については、「URI を使ったアプリの起動」の下にあるトピックを参照してください。

呼び出された

ユーザーがコンテンツリンクを呼び出すと、Uri を起動する既定の動作が発生する前に ContentLinkInvoked イベントが発生します。このイベントを処理して、既定の動作をオーバーライドまたは取り消すことができます。

この例では、Place コンテンツリンクの既定の起動動作をオーバーライドする方法を示します。場所情報カード、マップアプリ、または既定の Web ブラウザーでマップを開くのではなく、イベントを Handled としてマークし、アプリ内 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

ContentLinkChanged イベントを使用すると、コンテンツリンクが追加、変更、または削除されたときに通知を受け取ることができます。これにより、テキストからコンテンツリンクを抽出し、アプリ内の他の場所で使用できます。これについては、後の「例」セクションで説明します。

ContentLinkChangedEventArgs のプロパティ:

ChangedKind - この ContentLinkChangeKind 列挙型は ContentLink 内のアクションです。たとえば、ContentLink が挿入、削除、または編集された場合です。
Info - アクションのターゲットである ContentLinkInfo。

このイベントは、ContentLinkInfo アクションごとに発生します。たとえば、ユーザーが複数のコンテンツリンクを一度にコピーして RichEditBox に貼り付けると、追加された項目ごとにこのイベントが発生します。または、ユーザーが複数のコンテンツリンクを同時に選択して削除すると、削除されたアイテムごとにこのイベントが発生します。

このイベントは、TextChanging イベントの後、および TextChanged イベントの前に RichEditBox で発生します。

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 コントロールでコンテンツリンクを使用するには、(Windows.UI.Xaml.Documents 名前空間の) ContentLink テキスト要素を使用します。

テキストブロック内の ContentLink の一般的なソースは次のとおりです。

RichTextBlock コントロールから抽出したピッカーによって作成されたコンテンツリンク。
コードで作成する場所のコンテンツリンク。

その他の状況では、通常、Hyperlink テキスト要素が適しています。

ContentLink の外観

コンテンツリンクの外観は、前景、背景、カーソルによって決まります。テキストブロックでは、Foreground (TextElement から) プロパティと Background プロパティを設定して、既定の色を変更できます。

既定では、ユーザーがコンテンツリンクの上にマウスポインターを置くと、ハンドカーソルが表示されます。 RichEditBlock とは異なり、テキストブロックコントロールはリンクの種類に基づいてカーソルを自動的に変更しません。 Cursor プロパティを設定すると、リンクの種類やその他の要因に基づいてカーソルを変更できます。

TextBlock で使用される ContentLink の例を次に示します。 ContentLinkInfo はコードで作成され、XAML で作成された ContentLink テキスト要素の Info プロパティに割り当てられます。

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

ヒント

テキストコントロールで ContentLink を XAML のその他のテキスト要素と一緒に使用する場合、スパンコンテナーにコンテンツを配置してスパンに xml:space="preserve" 属性を適用すると、ContentLink とその他の要素間に空白を保持します。

例

この例では、ユーザーはユーザーを入力したり、コンテンツリンクを RickTextBlock に配置したりできます。 ContentLinkChanged イベントを処理してコンテンツリンクを抽出し、ユーザーリストまたは場所リストで最新の状態に保ちます。

リストの項目テンプレートでは、ContentLink テキスト要素と共に TextBlock を使用してコンテンツリンク情報を表示します。 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);
    }
}

次の方法で共有

テキスト制御のコンテンツリンク

リッチエディットコントロールとテキストブロックコントロールのコンテンツリンク

RichEditBox でコンテンツリンクを有効にする

コンテンツリンクプロバイダー

コンテンツリンクの色

ContentLinkInfo オブジェクト

リンクコンテンツの種類

URI の起動

場所

ユーザー

呼び出された

ContentLinkChanged

RichEditBox のコンテンツリンクを列挙する

ContentLink テキスト要素

ContentLink の外観

例

その他のリソース

次の方法で共有

テキスト制御のコンテンツ リンク

リッチ エディット コントロールとテキスト ブロック コントロールのコンテンツ リンク

RichEditBox でコンテンツ リンクを有効にする

コンテンツ リンク プロバイダー

コンテンツ リンクの色

ContentLinkInfo オブジェクト

リンク コンテンツの種類

URI の起動

場所

ユーザー

呼び出された

ContentLinkChanged

RichEditBox のコンテンツ リンクを列挙する

ContentLink テキスト要素

ContentLink の外観

例

その他のリソース

テキスト制御のコンテンツリンク

リッチエディットコントロールとテキストブロックコントロールのコンテンツリンク

RichEditBox でコンテンツリンクを有効にする

コンテンツリンクプロバイダー

コンテンツリンクの色

リンクコンテンツの種類

RichEditBox のコンテンツリンクを列挙する