Web Components チャートのユーザー注釈レイヤー

    Ignite UI for Web Components では、ユーザー注釈機能を使用して、実行時に IgcDataChartComponent にスライス注釈、ストリップ注釈、ポイント注釈を追加できます。これにより、エンドユーザーは、スライス注釈を使用して会社の四半期レポートなどの単一の重要イベントを強調したり、ストリップ注釈を使用して期間を持つイベントを示したりするなど、プロットに詳細を追加できます。ポイント注釈またはこれら 3 つの任意の組み合わせを使用して、プロットされたシリーズ上の個々のポイントを呼び出すこともできます。

    これは、IgcToolbarComponent のデフォルトのツールと統合されています。このトピックでは、IgcToolbarComponent を使用してチャートのプロット領域にユーザー注釈を追加する方法と、これらのユーザー注釈をプログラムから追加する方法を、例と共に解説します。

    [!Note] この機能は X 軸と Y 軸をサポートするように設計されており、現在、ラジアル軸やアンギュラー軸はサポートされていません。

    Toolbar でユーザー注釈を使用する

    IgcToolbarComponent には、「Annotate Chart」 と 「Delete Note」 という 2 つのツールを含む Annotations メニュー項目が用意されています。このメニュー項目を表示するには、対象のチャートで isUserAnnotationsEnabled プロパティを true に設定する必要があります。

    開いた後に表示される 「Annotate Chart」 オプションを使用すると、IgcDataChartComponent のプロット領域に注釈を付けることができます。追加できる注釈はスライス注釈、ストリップ注釈、ポイント注釈です。X 軸または Y 軸のラベルをクリックすると、スライス注釈を追加できます。プロット領域をクリックしてドラッグすることで、ストリップ注釈を追加できます。また、チャートにプロットされたシリーズ内のポイントをクリックして、ポイント注釈を追加することもできます。

    Web Components user-annotation-create

    以前に追加した注釈を削除するには、[Delete Note] メニュー項目を選択した後、スライスまたは ストリップのユーザー注釈に対応する軸注釈、またはポイントのユーザー注釈に対応するデータ ポイントをクリックします。

    Web Components user-annotation-delete

    XamToolbar を使用してこれらのユーザー注釈を追加すると、IgcDataChartComponent は UserAnnotationInformationRequested イベントを発生させ、そこでユーザー注釈に関する追加情報を提供できます。このイベント引数には AnnotationInfo プロパティがあり、追加される注釈のさまざまな要素を構成可能な IgcUserAnnotationInformation オブジェクトを返します。

    以下の表は、IgcUserAnnotationInformation で構成可能なさまざまなプロパティの詳細を示しています。

    プロパティ タイプ 説明
    annotationData string このプロパティは、ユーザー注釈に追加情報を提供するためのものです。このプロパティは、UserAnnotationToolTipContentUpdating イベントと組み合わせて使用され、注釈のツールチップに追加情報を表示するよう設計されています。
    annotationId string この読み取り専用プロパティは、ユーザー注釈の一意の文字列 ID を返します。
    badgeColor string このプロパティは、ユーザー注釈のバッジに使用する色を取得または設定します。
    badgeImageUri string このプロパティは、ユーザー注釈のバッジに使用する画像へのパスを取得または設定します。
    dialogSuggestedXLocation double このプロパティは、ユーザー注釈が追加された位置に基づいて、ダイアログを表示する推奨 X 座標を取得します。
    dialogSuggestedYLocation double このプロパティは、ユーザー注釈が追加された位置に基づいて、ダイアログを表示する推奨 Y 座標を取得します。
    label string このプロパティは、ユーザー注釈に表示するラベルを取得または設定します。
    mainColor string このプロパティは、ユーザー注釈の背景を塗りつぶすために使用する色を取得または設定します。

    UserAnnotationInformationRequested イベントで注釈情報を更新した後、IgcDataChartComponent の finishAnnotationFlow メソッドを呼び出して注釈の作成を完了し、変更を確定する必要があります。あるいは、cancelAnnotationFlow を呼び出して注釈の annotationId を渡すことで注釈の作成をキャンセルすることもできます。注釈の annotationId は、前述のように、UserAnnotationInformationRequested イベントの引数の AnnotationInfo パラメーターから取得できます。これにより、プロット領域から注釈が削除されます。

    ユーザー注釈をプログラムで使用する

    IgcUserAnnotationLayerComponent をプログラムで使用する場合、IgcDataChartComponent に対して 2 つのメソッドを呼び出し、ユーザー注釈の追加または削除を行えるモードに切り替えることができます。これらのメソッドは startCreatingAnnotation と startDeletingAnnotation です。

    startCreatingAnnotation を呼び出した後は、X または Y 軸のラベルをクリックしてスライス注釈を追加したり、プロット領域をクリックしドラッグしてからマウスボタンを離してストリップ注釈を追加したり、チャート内のシリーズ上のデータ ポイントをクリックしてポイント注釈を追加したりできます。

    これらのユーザー注釈のいずれかを追加すると、UserAnnotationInformationRequested イベントが発生し、ユーザー注釈に関する詳細情報を提供できます。このイベント引数には AnnotationInfo プロパティがあり、追加される注釈のさまざまな要素を構成可能な IgcUserAnnotationInformation オブジェクトを返します。

    UserAnnotationInformationRequested イベントで注釈情報を更新した後、IgcDataChartComponent の finishAnnotationFlow メソッドを呼び出して注釈の作成を完了し、変更を確定する必要があります。あるいは、cancelAnnotationFlow を呼び出して注釈の annotationId を渡すことで注釈の作成をキャンセルすることもできます。注釈の annotationId は、前述のように、UserAnnotationInformationRequested イベントの引数の AnnotationInfo パラメーターから取得できます。これにより、プロット領域から注釈が削除されます。

    ユーザー注釈がチャートに追加されると、IgcSeriesComponent コレクションに IgcUserAnnotationLayerComponent として表示されます。IgcUserAnnotationLayerComponent には、プロット領域に追加された注釈の種類に応じて IgcUserSliceAnnotation、IgcUserStripAnnotation、および IgcUserPointAnnotation 要素を保存できる annotations コレクションがあります。

    UserAnnotationToolTip

    各ユーザー注釈は、マウス ホバー時にツールチップを表示し、さらに詳細な情報を提供できます。

    チャートは UserAnnotationToolTipContentUpdating イベントを公開しており、ツールチップが表示される際にその内容を更新できます。このイベント引数には Content と AnnotationInfo の 2 つのプロパティがあります。

    ツールチップは UserAnnotationInformationRequested イベントと連動する設計になっており、そのイベントで annotationData に設定した追加情報を、ツールチップ表示時にも利用できます。UserAnnotationToolTipContentUpdating イベントのイベント引数の AnnotationInfo プロパティは、そのイベントで変更できる UserAnnotationInformationRequested の AnnotationInfo プロパティと同じインスタンスになります。これにより、ユーザー注釈の作成時に提供された情報を活用し、ツールチップ内にさらに多くの情報を提供できるようになります。

    API リファレンス

    以下は上記のセクションで説明した API メンバーのリストです。

    その他のリソース

    関連するチャート機能の詳細については、次のトピックを参照してください。