Power BI ビジュアルのブックマーク サポートを追加するAdd bookmark support for Power BI visuals

Power BI レポートのブックマークを使用すると、レポート ページの構成済みビュー、選択の状態、およびビジュアルのフィルター処理の状態をキャプチャできます。With Power BI report bookmarks, you can capture a configured view of a report page, the selection state, and the filtering state of the visual. しかし、ブックマークをサポートし、変更に適切に対応するには、Power BI ビジュアル側からの追加のアクションが必要です。But it requires additional action from the Power BI visuals side to support the bookmark and react correctly to changes.

ブックマークの詳細については、「Power BI でブックマークを使用して分析情報を共有し、ストーリーを作成する」を参照してください。For more information about bookmarks, see Use bookmarks to share insights and build stories in Power BI.

ビジュアルでのレポート ブックマークのサポートReport bookmarks support in your visual

ご自分のビジュアルで他のビジュアルとやりとりしたり、データ ポイントを選択したり、他のビジュアルのフィルター処理を行う場合は、プロパティから状態を復元する必要があります。If your visual interacts with other visuals, selects data points, or filters other visuals, you need to restore the state from properties.

レポート ブックマーク サポートを追加するAdd report bookmarks support

  1. 必要なユーティリティである powerbi-visuals-utils-interactivityutils バージョン 3.0.0 以降をインストール (または更新) します。Install (or update) the required utility, powerbi-visuals-utils-interactivityutils version 3.0.0 or later. これには、状態の選択またはフィルターで操作するための追加のクラスが含まれています。It contains additional classes to manipulate with the state selection or filter. これは、フィルター ビジュアルと InteractivityService を使用する任意のビジュアルに必要です。It's required for filter visuals and any visual that uses InteractivityService.

  2. SelectionManager のインスタンス内で registerOnSelectCallback 使用するように、ビジュアルの API をバージョン 1.11.0 に更新します。Update the visual API to version 1.11.0 to use registerOnSelectCallback in an instance of SelectionManager. これは、InteractivityService ではなく、プレーンの SelectionManager を使用する非フィルター ビジュアルに必要です。It's required for non-filter visuals that use the plain SelectionManager rather than InteractivityService.

レポート ブックマークで Power BI ビジュアルと Power BI がやりとりする方法How Power BI visuals interact with Power BI in report bookmarks

次のシナリオについて考えてみましょう。レポート ページ上に複数のブックマークを作成し、各ブックマークでの選択状態をそれぞれ異なるものとします。Let's consider the following scenario: you want to create several bookmarks on the report page, with a different selection state in each bookmark.

まず、ご利用のビジュアル内でデータ ポイントを選択します。First, you select a data point in your visual. ビジュアルでは、ホストに選択を渡すことで、Power BI およびその他のビジュアルとやり取りします。The visual interacts with Power BI and other visuals by passing selections to the host. 次に、[ブックマーク] パネルで [追加] を選択します。Power BI によって新しいブックマークの現在の選択内容が保存されます。You then select Add in the Bookmark pane, and Power BI saves the current selections for the new bookmark.

選択内容を変更し、新しいブックマークを追加するときは、これが繰り返し行われます。It happens repeatedly as you change the selection and add new bookmarks. 複数のブックマークを作成したら、それらを切り替えることができます。After you create the bookmarks, you can switch between them.

ブックマークを選択すると、Power BI によって保存されたフィルターまたは選択状態が復元され、ビジュアルに渡されます。When you select a bookmark, Power BI restores the saved filter or selection state and passes it to the visuals. 他のビジュアルは、ブックマークに格納されている状態に応じて、強調表示されるか、フィルター処理されます。Other visuals are highlighted or filtered according to the state that's stored in the bookmark. Power BI ホストは、アクションを担当します。The Power BI host is responsible for the actions. ご利用のビジュアルでは、新しい選択状態 (レンダリングされるデータ ポイントの色を変更する場合など) を正しく反映する役割を果たします。Your visual is responsible for correctly reflecting the new selection state (for example, for changing the colors of rendered data points).

新しい選択状態は、update メソッドを介してビジュアルに伝達されます。The new selection state is communicated to the visual through the update method. options 引数には、特殊なプロパティ options.jsonFilters が含まれます。The options argument contains a special property, options.jsonFilters. その JSONFilter プロパティには Advanced Filter および Tuple Filter を含めることができます。Its JSONFilter property can contain Advanced Filter and Tuple Filter.

ビジュアルでは、フィルター値を復元することで、選択されたブックマークに対応するビジュアルの状態が表示される必要があります。The visual should restore the filter values to display the corresponding state of the visual for the selected bookmark. または、ビジュアルで選択のみが使用される場合、ISelectionManager の registerOnSelectCallback メソッドとして登録されている特殊なコールバック関数呼び出しを使用します。Or, if the visual uses selections only, you can use the special callback function call that's registered as the registerOnSelectCallback method of ISelectionManager.

選択を使用するビジュアルVisuals with Selection

ご利用のビジュアルが選択を使用して他のビジュアルとやりとりする場合は、次の 2 つの方法のいずれかでブックマークを追加できます。If your visual interacts with other visuals by using Selection, you can add bookmarks in either of two ways:

  • InteractivityService がビジュアルでまだ使用されていない場合は、FilterManager.restoreSelectionIds メソッドを使用できます。If the visual hasn't already used InteractivityService, you can use the FilterManager.restoreSelectionIds method.

  • 選択を管理するために InteractivityService がビジュアルで既に使用されている場合は、InteractivityService のインスタンス内で applySelectionFromFilter メソッドを使用する必要があります。If the visual already uses InteractivityService to manage selections, you should use the applySelectionFromFilter method in the instance of InteractivityService.

ISelectionManager.registerOnSelectCallback を使用するUse ISelectionManager.registerOnSelectCallback

ブックマークを選択すると、Power BI によって、ビジュアルの callback メソッドが対応する選択と共に呼び出されます。When you select a bookmark, Power BI calls the callback method of the visual with the corresponding selections.

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        //called when a selection was set by Power BI
    });
);

visualTransform メソッドで作成されたビジュアル内にデータ ポイントがあると仮定してみましょう。Let's assume that you have a data point in your visual that was created in the visualTransform method.

datapoints は次のようになっています。And datapoints looks like:

visualDataPoints.push({
    category: categorical.categories[0].values[i],
    color: getCategoricalObjectValue<Fill>(categorical.categories[0], i, 'colorSelector', 'fill', defaultColor).solid.color,
    selectionId: host.createSelectionIdBuilder()
        .withCategory(categorical.categories[0], i)
        .createSelectionId(),
    selected: false
});

これで、ご自分のデータ ポイントとして visualDataPoints が用意され、ids 配列が callback 関数に渡されます。You now have visualDataPoints as your data points and the ids array passed to the callback function.

この時点で、ビジュアルでは ISelectionId[] 配列と、ご利用の visualDataPoints 配列内の選択を比較し、対応するデータ ポイントを選択済みとしてマークする必要があります。At this point, the visual should compare the ISelectionId[] array with the selections in your visualDataPoints array and mark the corresponding data points as selected.

this.selectionManager.registerOnSelectCallback(
    (ids: ISelectionId[]) => {
        visualDataPoints.forEach(dataPoint => {
            ids.forEach(bookmarkSelection => {
                if (bookmarkSelection.equals(dataPoint.selectionId)) {
                    dataPoint.selected = true;
                }
            });
        });
    });
);

データ ポイントを更新したら、filter オブジェクトに格納されている現在の選択状態が反映されます。After you update the data points, they'll reflect the current selection state that's stored in the filter object. これで、データ ポイントがレンダリングされると、カスタム ビジュアルの選択状態がブックマークの状態と一致するようになります。Then, when the data points are rendered, the custom visual's selection state will match the state of the bookmark.

ビジュアルでのコントロールの選択に InteractivityService を使用するUse InteractivityService for control selections in the visual

ビジュアルで InteractivityService が使用されている場合、そのビジュアルでブックマークをサポートするための追加の操作は必要ありません。If your visual uses InteractivityService, you don't need any additional actions to support the bookmarks in your visual.

ブックマークを選択すると、ビジュアルの選択状態がユーティリティによって処理されます。When you select bookmarks, the utility handles the visual's selection state.

フィルターを使用するビジュアルVisuals with a filter

ビジュアルによって、データのフィルターが日付範囲で作成されるとします。Let's assume that the visual creates a filter of data by date range. 範囲の開始日と終了日として startDateendDate があります。You have startDate and endDate as the start and end dates of the range.

関連条件でデータをフィルター処理する場合、ビジュアルでは高度なフィルターが作成され、ホスト メソッド applyJsonFilter が呼び出されます。The visual creates an advanced filter and calls the host method applyJsonFilter to filter data by the relevant conditions.

ターゲットは、フィルター処理に使用されるテーブルです。The target is the table that's used for filtering.

import { AdvancedFilter } from "powerbi-models";

const filter: IAdvancedFilter = new AdvancedFilter(
    target,
    "And",
    {
        operator: "GreaterThanOrEqual",
        value: startDate
            ? startDate.toJSON()
            : null
    },
    {
        operator: "LessThanOrEqual",
        value: endDate
            ? endDate.toJSON()
            : null
    });

this.host.applyJsonFilter(
    filter,
    "general",
    "filter",
    (startDate && endDate)
        ? FilterAction.merge
        : FilterAction.remove
);

ブックマークをクリックするたびに、カスタム ビジュアルによって update 呼び出しが取得されます。Each time you select a bookmark, the custom visual gets an update call.

カスタム ビジュアルでは、オブジェクト内のフィルターを確認する必要があります。The custom visual should check the filter in the object:

const filter: IAdvancedFilter = FilterManager.restoreFilter(
    && options.jsonFilters
    && options.jsonFilters[0] as any
) as IAdvancedFilter;

filter オブジェクトが null でない場合、ビジュアルではオブジェクトからフィルター条件を復元する必要があります。If the filter object isn't null, the visual should restore the filter conditions from the object:

const jsonFilters: AdvancedFilter = this.options.jsonFilters as AdvancedFilter[];

if (jsonFilters
    && jsonFilters[0]
    && jsonFilters[0].conditions
    && jsonFilters[0].conditions[0]
    && jsonFilters[0].conditions[1]
) {
    const startDate: Date = new Date(`${jsonFilters[0].conditions[0].value}`);
    const endDate: Date = new Date(`${jsonFilters[0].conditions[1].value}`);

    // apply restored conditions
} else {
    // apply default settings
}

その後、ビジュアルでは、現在の条件を反映するように、内部状態を変更する必要があります。After that, the visual should change its internal state to reflect the current conditions. 内部状態には、データ ポイントと視覚エフェクト オブジェクト (線や四角形など) が含まれます。The internal state includes the data points and visualization objects (lines, rectangles, and so on).

重要

レポート ブックマークのシナリオでは、ビジュアルで applyJsonFilter を呼び出して他のビジュアルをフィルター処理する必要はありません。In the report bookmarks scenario, the visual shouldn't call applyJsonFilter to filter the other visuals. これらは、既に Power BI によってフィルター処理されています。They will already be filtered by Power BI.

タイムライン スライサー ビジュアルでは、範囲セレクターが、対応するデータ範囲に変更されます。The Timeline Slicer visual changes the range selector to the corresponding data ranges.

詳細については、タイムライン スライサー リポジトリに関するページを参照してください。For more information, see the Timeline Slicer repository.

状態をフィルター処理してビジュアル プロパティをブックマークに保存するFilter the state to save visual properties in bookmarks

filterState プロパティでは、プロパティがフィルター処理の一部と見なされます。The filterState property makes a property of a part of filtering. ビジュアルでは、さまざまな値をブックマークに格納できます。The visual can store a variety of values in bookmarks.

プロパティ値をフィルター状態として保存するには、capabilities.json ファイル内でオブジェクト プロパティを "filterState": true としてマークします。To save the property value as a filter state, mark the object property as "filterState": true in the capabilities.json file.

たとえば、タイムライン スライサーでは、Granularity プロパティの値がフィルターに格納されます。For example, the Timeline Slicer stores the Granularity property values in a filter. これにより、ブックマークを変更するときに、現在の粒度を変更できます。It allows the current granularity to change as you change the bookmarks.

詳細については、タイムライン スライサー リポジトリに関するページを参照してください。For more information, see the Timeline Slicer repository.