deneb-visuals

Power BI の Deneb ビジュアル（PBIR）

すべてのレポート変更には pbir を使用してください。 診断目的に限り、PBIR メタデータを読み取ります。pbir が利用できない場合や、必要な操作が用意されていない場合は、そこで停止して不足している機能を報告してください。レポートの JSON を直接編集してはいけません。

Deneb は、Vega と Vega-Lite の宣言型ビジュアライゼーション仕様をレポート内に直接記述できる、Power BI 認定のカスタムビジュアルです。このスキルを使用して仕様を作成してください。

プロバイダーポリシー

特定の Vega 専用機能（シグナル、イベントストリーム、カスタム投影、力学系／ボロノイレイアウト）が必要な場合を除き、新しい Deneb ビジュアルには Vega-Lite を優先してください。Vega-Lite は簡潔で保守しやすく、ほとんどのグラフ形式に対応します。高度な Vega 機能については、references/vega-patterns.md と Vega のドキュメントを参照してください。

ビジュアルの識別情報

• visualType: deneb7E15AEF80B9E4D4F8E12924291ECE89A
• バンドルされたランタイム: Vega 6.2.0 / Vega-Lite 6.4.1（Deneb 1.8 以降。v6.json スキーマ URL を使用してください）
• データロール: 単一の dataset ロール（すべてのフィールドを 1 つの「Values」ウェルに配置）
• 既定の行数制限: 10,000 行（dataLimit.override で上書き可能）
• プロバイダー: vegaLite（既定）または vega（Vega 固有の機能が必要な場合）
• レンダリングモード: svg（既定。テキストが鮮明）または canvas（大規模なデータセットに適しています）

カスタムビジュアルの登録（必須）

動作する Deneb ビジュアルを pbir cp でコピーすると、その登録情報も引き継がれます。新しいビジュアルを作成する場合は、pbir get で publicCustomVisuals を調べ、既存の ID を保持したうえで、pbir set --json を使用してリスト全体を更新してください。report.json を直接編集してはいけません。

ワークフロー：Deneb ビジュアルの作成

手順 1：ビジュアルを追加する

pbir を使用してビジュアルとバインディングを作成します。

pbir add visual deneb7E15AEF80B9E4D4F8E12924291ECE89A \
  "Report.Report/Page.Page" --name RevenueByCategoryDeneb
pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --add "dataset:Sales.Category" --type Column
pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --add "dataset:Sales.Revenue" --type Measure

すべてのフィールドを単一の dataset ロールにバインドします。列には Table.Column、メジャーには Table.Measure を使用してください。バインディング内のフィールド名は、Vega／Vega-Lite 仕様で使用するフィールド名と一致している必要があります。

手順 2：仕様を記述する

Vega-Lite（または Vega）の JSON 仕様ファイルを作成します。主な違いは次のとおりです。

• Vega-Lite: "data": {"name": "dataset"}（オブジェクト）
• Vega: "data": [{"name": "dataset"}]（配列）

{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {"name": "dataset"},
  "mark": {"type": "bar", "tooltip": true},
  "encoding": {
    "y": {"field": "Category", "type": "nominal"},
    "x": {"field": "Value", "type": "quantitative"}
  }
}

完全な仕様ファイル（Vega と Vega-Lite）は examples/spec/ を、完全な PBIR visual.json ファイルは examples/visual/ を参照してください。仕様内のフィールド名は、フィールドバインディングの nativeQueryRef（表示名）と一致している必要があります。

手順 3：仕様を挿入する

pbir visuals deneb "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --spec-file chart.vl.json --provider vegaLite

CLI が PBIR のエンコードを処理します。仕様ファイルには通常の Vega または Vega-Lite の JSON を記述してください。

手順 3b：レビューする

仕様をユーザーに提示する前に、deneb-reviewer エージェントを呼び出し、構文の検証とデザインに関するフィードバックを行わせてください。

手順 4：検証する

pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" --show
pbir validate "Report.Report" --all

仕様の作成ルール

データバインディング

• Vega: "data": [{"name": "dataset"}]（配列形式）
• Vega-Lite: "data": {"name": "dataset"}（オブジェクト形式）
• フィールドでは表示名を参照します。特殊文字（., [, ], \, "）は _ に置き換えられます
• スペースは置き換えられません。フィールド名のスペースはそのまま維持されます（例："Order Lines"）

式内のフィールド名のエスケープ（重要）

エスケープ方法は、仕様が単独のファイルか、PBIR visual.json に挿入されているかによって異なります。

単独の仕様ファイル（examples/spec/ 内）では、JSON エスケープを使用した二重引用符を使います。

{"calculate": "datum[\"Order Lines\"] - datum[\"Order Lines (PY)\"]", "as": "diff"}

PBIR visual.json 内（examples/visual/ 内）では、仕様全体が単一引用符で囲まれた 1 つの DAX リテラル文字列になります。スペースを含むフィールド名では、単一引用符を 2 つ重ねて（''）使用します。

datum[''Order Lines''] - datum[''Order Lines (PY)'']

フィールド名のエスケープに使用しない単一引用符（たとえば、datum.Series == 'Actuals' のようなフィルター式内の文字列リテラル）は、外側の単一引用符の囲みと競合しないため、そのまま使用できます。

レスポンシブなサイズ設定（Vega）

コンテナのサイズに合わせて調整するには、Deneb の組み込みシグナルを使用します。

"width": {"signal": "pbiContainerWidth - 25"},
"height": {"signal": "pbiContainerHeight - 27"}

オフセットはパディングを考慮しています。テキストマークを絶対位置に配置する場合は、固定のピクセル値ではなく {"signal": "width"} を使用してください。

Config（Spec とは別）

一貫したスタイルを適用するため、必ず config ファイルを指定してください。references/vega-patterns.md の Standard Config セクションを参照してください。主な設定：autosize: fit、view.stroke: transparent、font: Segoe UI。

テーマとの統合

ハードコードされた16進数値ではなく、Power BI のテーマカラーを使用してください。

関数／スキーム	目的	Vega での使用方法
pbiColor(index)	インデックス（0ベース）でテーマカラーを指定	{"signal": "pbiColor(0)"}
pbiColor(0, -0.3)	テーマカラーを30%暗くする	シェード：-1（暗）～1（明）
pbiColor("negative")	感情を表すカラー	"min"、"middle"、"max"、"negative"、"positive"
pbiColor("bad")	感情を表すカラーの別名	"bad" = "negative"、"good" = "positive"、"neutral" = "middle"
pbiColorNominal	カテゴリ別パレット（識別しやすい色）	"range": {"scheme": "pbiColorNominal"}
pbiColorOrdinal	順序付きカテゴリ別パレット	"range": {"scheme": "pbiColorOrdinal"}
pbiColorLinear	連続グラデーション	"range": {"scheme": "pbiColorLinear"}
pbiColorDivergent	発散グラデーション	"range": {"scheme": "pbiColorDivergent"}

インタラクティブ機能

visual.json の vega オブジェクトでインタラクティブ機能を有効にします。

機能	プロパティ	デフォルト	備考
ツールチップ	enableTooltips	true	encode で "tooltip": {"signal": "datum"} を使用
コンテキストメニュー	enableContextMenu	true	右クリックでドリルスルー
クロスフィルター	enableSelection	false	__selected__ の処理が必要
クロスハイライト	enableHighlight	false	<field>__highlight フィールドを作成

クロスフィルター

enableSelection が true の場合、encode ブロックで __selected__（"on"、"off"、"neutral"）を処理します。選択モード：simple（自動で解決し、最大250個のデータポイントに対応）または advanced（Vega 専用。ブラシ／投げ縄／領域選択に必要で、options.limit を使って最大2500個に対応し、pbiCrossFilterApply および pbiCrossFilterClear シグナルを公開します）。シンプルなパターンについては references/vega-patterns.md を、高度なシグナル API については references/advanced-patterns.md を参照してください。

クロスハイライト

レイヤー化されたマークを使用します。背景の不透明度を下げ、前景には <field>__highlight の値を表示します。詳細は references/vega-patterns.md を参照してください。

特殊なランタイムフィールド

Deneb は各データセットの行にランタイムフィールドを挿入します。表全体については references/capabilities.md を参照してください。

主なフィールド：__row__（0ベースの行インデックス。削除された __identity__ の代わり）、__selected__（選択状態）、<field>__highlight + <field>__highlightStatus + <field>__highlightComparator（クロスハイライト）、<field>__formatted（書式設定済みの値文字列）、<field>__format（Power BI の書式文字列）。

1.9 での破壊的変更： __identity__ と __key__ は削除されました。datum.__identity__ はすべて datum.__row__ に置き換えてください。

ベストプラクティス

1. 新しいビジュアルには、Vega 固有の機能（シグナル、イベント、力学レイアウト）が必要な場合を除き、Vega-Lite を使用してください
2. Power BI のサイズ変更に対応するため、config では必ず autosize: fit を使用してください
3. レスポンシブな Vega spec には pbiContainerWidth／pbiContainerHeight シグナルを使用してください
4. 16進数値ではなく、テーマカラー（pbiColor、pbiColorNominal）を使用してください
5. 状態をすっきり管理するため、encode ブロックに enter／update／hover を使用してください（Vega のみ）
6. マークに "tooltip": {"signal": "datum"} を指定して、ツールチップを有効にしてください
7. パフォーマンス -- まず DAX で集計し、多数のマークには renderMode: canvas を優先してから、dataLimit.override を引き上げてください。調整手順の全体については references/advanced-patterns.md を参照してください
8. フィールド名をテストしてください -- nativeQueryRef が spec のフィールド参照と一致していることを確認してください
9. 外部データは避けてください -- AppSource 認定では外部 URL の読み込みが禁止されています
10. エスケープ方法はコンテキストによって異なります -- 単独の spec では二重引用符を、PBIR visual.json では二重の単一引用符を使用してください（前述のエスケープ規則を参照）

Deneb を使用する場面

Deneb は、インタラクティブ機能（クロスフィルター、ツールチップ、ホバー効果）が必要で、標準の Power BI ビジュアルでは実現できない高度なカスタムビジュアルに最適です。次のような場合に Deneb を使用します。

• 標準では利用できないカスタムチャートタイプ（ブレットチャート、ビースウォーム、サンキーダイアグラムなど）
• ビジュアルエンコーディング、アニメーション、インタラクティブ機能を細かく制御する必要がある場合
• ベクターベースのレンダリング（どのサイズでも鮮明）

インタラクティブ機能が不要な、テーブルやカード内のシンプルなインライングラフィック（スパークライン、データバー、進捗バー）には、代わりに SVG メジャーを使用します。インタラクティブ機能よりも分析の厳密さが重視される統計ビジュアライゼーション（分布分析、回帰、相関）には、代わりに Python/R を使用します。

参考資料

• references/community-examples.md -- チャートタイプ別に整理された 170 件以上のコミュニティテンプレート。作者のクレジットと直接リンクを含みます
• references/vega-patterns.md -- Vega チャートパターン（棒、折れ線、散布図、ドーナツ、積み上げ、ヒートマップ、面、ロリポップ、ブレット、KPI カード）、標準設定、変換とスケールのリファレンス
• references/vega-lite-patterns.md -- Vega-Lite チャートパターン（既存の Vega-Lite ビジュアルの編集専用）
• references/pbir-structure.md -- PBIR JSON 構造（リテラルエンコーディング、クエリ状態、インタラクティブ機能の例）
• references/capabilities.md -- Deneb オブジェクトのプロパティとテンプレート形式（usermeta スキーマ）の完全なリファレンス
• references/advanced-patterns.md -- 高度なクロスフィルターシグナル（Vega pbiCrossFilterApply/pbiCrossFilterClear）、パフォーマンスエンジニアリングのレバーの適用順序、ターミナルからコミュニティテンプレートを往復させる方法
• examples/visual/bullet-chart.json -- PBIR visual.json：条件付きインジケーターとクロスフィルターを備えたファセット付きブレットチャート（Vega-Lite）
• examples/visual/kpi-card.json -- PBIR visual.json：レイヤー化されたテキストと条件付きの変化率の色分けを備えた KPI カード（Vega-Lite）
• examples/visual/trend-line.json -- PBIR visual.json：fold 変換と色／凡例のマッピングを使用した 2 系列の折れ線チャート（Vega-Lite）
• examples/visual/ytd-comparison.json -- PBIR visual.json：破線、終点ラベル、数値書式、順位に基づくフィルタリングを使用した YTD と目標の比較（Vega-Lite）
• examples/spec/vega/ -- 単独で使用できる Vega 仕様ファイル（棒グラフ、折れ線グラフ）。エスケープ処理後に visual.json に挿入できます
• examples/spec/vega-lite/ -- 単独で使用できる Vega-Lite 仕様ファイル（ブレットチャート、KPI カード）。エスケープ処理後に挿入できます
• examples/standard-config.json -- すべての Deneb 仕様に共通する標準設定

ドキュメントの取得

最新の Power BI カスタムビジュアルのドキュメントを取得するには、https://learn.microsoft.com を検索し、該当するページを取得します。ユーザーのリクエストに基づいて検索し、作業に進む前に十分な情報を得られるよう、必要に応じて複数回検索してください。注：Vega/Vega-Lite のドキュメントは MS Learn ではなく vega.github.io にあります。これらには WebFetch を使用してください。

関連スキル

• pbir-format（pbip プラグイン）-- PBIR JSON 形式のリファレンス
• pbi-report-design -- レイアウトとデザインのベストプラクティス
• r-visuals -- R スクリプトビジュアル（ggplot2）
• python-visuals -- Python スクリプトビジュアル（matplotlib）
• svg-visuals -- DAX メジャーによる SVG（軽量なインライングラフィック）