svg-visuals

DAX メジャーを使った SVG ビジュアル（PBIR）

レポートを変更する場合は、必ず pbir を使用してください。 pbir-format スキルはスキーマ情報の参照専用です。 CLI を利用できない場合や必要な操作がない場合は、作業を中止して不足点を報告してください。

SVG マークアップ文字列を返す DAX メジャーを使って、インライン SVG グラフィックを生成します。これらは、テーブル、マトリックス、カード、画像、スライサーのビジュアルに画像として表示されます。reportExtensions.json に拡張メジャーとして保存します。

仕組み

1. DAX メジャーが data:image/svg+xml;utf8, を先頭に付けた SVG 文字列を返します
2. メジャーの dataCategory を ImageUrl に設定します
3. Power BI が、対応するビジュアルで SVG を画像としてレンダリングします

対応するビジュアル

• テーブル（tableEx）：grid.imageHeight / grid.imageWidth -- references/svg-table-matrix.md
• マトリックス（pivotTable）：テーブルと同じ -- references/svg-table-matrix.md
• 画像（image）：sourceType='imageData' + sourceField -- references/svg-image-visual.md
• カード／新（cardVisual）：image オブジェクト（画像領域）または cardImage（コールアウト画像） -- references/svg-template-matrix.md、references/svg-card-slicer.md のパターン
• スライサー／新（advancedSlicerVisual）：画像の「データから選択」スロットを使い、ボタンごとに 1 つの画像を表示します -- references/svg-template-matrix.md

テンプレートから始める

DAX を手書きする前に、references/svg-template-matrix.md を確認してください。各パターン（ブレット、進捗、ピル、スパークライン、ダンベル、発散、差分、ピン、ゲージ）に適したホスト（SVG 単体は画像ビジュアルに配置し、カードには数値を配置）を対応付け、ホストごとに検証済みの PBIR 設定を示しています。また、パターンを簡潔なレポートメジャーとして書き込み、ビジュアルに設定する 1 ステップの pbir visuals svg / pbir add gauge-card コマンドも紹介しています。テンプレートで対応できない形状に限り、SVG DAX を手書きしてください。

ワークフロー：SVG メジャーの作成

ステップ 0：デザインとプレビュー

DAX を書く前に、SVG の見た目をデザインします。

1. まずモデルをクエリする -- DAX Studio または Tabular Editor CLI を使い、意図したフィルターコンテキストで実際の値を取得します。プレースホルダーではなく、実際の数値を使ってください。
2. 静的 SVG を一時ファイルに書き込む -- /tmp/mockup.svg に保存し、ブラウザーで open してレイアウト、色、比率をプレビューします。
3. DAX に変換する前にフィードバックを求める -- 静的 SVG の調整は、DAX の文字列連結を調整するよりはるかに簡単です。
4. 色には # を付けた 16 進コードを使う -- 例：fill='#2B7A78'。%23 による URL エンコードや色名は使用しないでください。常に 16 進数を使ってください。

ステップ 1：拡張メジャーを作成する

reportExtensions.json に拡張メジャーを手動で作成します（JSON 構造については、pbip プラグインの pbir-format スキルを参照してください）。

# Example using pbir_object_model (if available):
report.add_extension_measure(
    table="Orders",
    name="Sparkline SVG",
    expression='''
        VAR _Prefix = "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 30'>"
        VAR _Bar = "<rect x='0' y='0' width='50' height='30' fill='#2196F3'/>"
        VAR _Suffix = "</svg>"
        RETURN _Prefix & _Bar & _Suffix
    ''',
    data_type="Text",
    data_category="ImageUrl",
    display_folder="SVG Charts",
)
report.save()

ステップ 1b：レビューする

メジャーをユーザーに提示する前に、svg-reviewer エージェントを呼び出して、構文の検証とデザインに関するフィードバックを行います。

ステップ 2：ビジュアルにバインドする

拡張メジャーでは、SourceRef に "Schema": "extension" を使用します。

{
  "field": {
    "Measure": {
      "Expression": {
        "SourceRef": {"Schema": "extension", "Entity": "Orders"}
      },
      "Property": "Sparkline SVG"
    }
  }
}

画像ビジュアルの場合は、pbir add visual image --image を使って SVG メジャーをバインドします。詳しくは references/svg-image-visual.md を参照してください。

ステップ 3：検証する

pbir validate "Report.Report" --all で検証し、 pbir visuals bind "...Visual" --show でバインドを確認します。

カスタム DAX より UDF ライブラリを優先する

カスタム SVG メジャーを一から作成する前に、既存の UDF ライブラリが目的のチャートタイプを提供しているか確認してください。

• PowerofBI.IBCS（Andrzej Leszkiewicz）-- IBCS 準拠の棒グラフ、縦棒グラフ、ウォーターフォール、ピン、スモールマルチプル、損益チャートを提供します。AC/PY/BU/FC の比較を含むビジネスレポートに適しています。https://daxlib.org/package/PowerofBI.IBCS/ からインストールしてください。
• DaxLib.SVG（Jake Duddy）-- 汎用のスパークライン、棒グラフ、箱ひげ図、ヒートマップ、ジッター、バイオリンプロット、プログレスバー、ピルを提供します。https://daxlib.org/package/DaxLib.SVG/ からインストールしてください。ソースコードは https://github.com/daxlib/dev-daxlib-svg にあります。
• PowerBI MacGuyver Toolbox（Stepan Resl / Data Goblins）-- Tabular Editor 経由で SVG メジャーを生成する C# スクリプトです。

ライブラリがインストールされているか確認するには、PowerofBI.IBCS.、Viz.、Compound.、または Element. で始まる関数やメジャーを探してください。必要なビジュアライゼーションをカバーするライブラリ関数がない場合に限り、カスタム SVG DAX を作成してください。関数の一覧とその他のライブラリについては、references/community-examples.md を参照してください。

UDF ライブラリのインストール

UDF ライブラリはレポートではなく、セマンティックモデルにインストールします。次のいずれかのツールを使用してください。

• Tabular Editor CLI（te コマンド）-- 手順については te-docs スキルを使用してください。
• Power BI MCP server -- 利用可能な場合は、モデルを直接変更するために使用してください。
• connect-pbid スキル -- TOM/PowerShell 経由で Power BI Desktop のローカル Analysis Services インスタンスに接続します。
• tmdl スキル -- PBIP プロジェクトの TMDL ファイルを直接編集します（最終手段）。

DAX SVG の規約

メジャーの構成（VAR パターン）

すべての SVG メジャーは、厳格な VAR ベースの構成に従う必要があります。コードは明確に分けた領域に整理してください。

SVG Measure =
-- CONFIG: Input fields and visual parameters
VAR _Actual = [Sales Amount]
VAR _Target = [Sales Target]
VAR _Scope = ALLSELECTED ( 'Product'[Category] )

-- CONFIG: Colors
VAR _BarColor = "#5B8DBE"
VAR _TargetColor = "#333333"

-- NORMALIZATION: Scale values to SVG coordinate space
VAR _AxisMax = CALCULATE( MAXX( _Scope, [Sales Amount] ), REMOVEFILTERS( 'Product'[Category] ) ) * 1.1
VAR _AxisRange = 100
VAR _ActualNormalized = DIVIDE( _Actual, _AxisMax ) * _AxisRange

-- SVG ELEMENTS: One VAR per visual element
VAR _SvgPrefix = "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 25'>"
VAR _Sort = "<desc>" & FORMAT( _Actual, "000000000000" ) & "</desc>"
VAR _Bar = "<rect x='0' y='5' width='" & _ActualNormalized & "' height='15' fill='" & _BarColor & "'/>"
VAR _TargetLine = "<rect x='" & DIVIDE( _Target, _AxisMax ) * _AxisRange & "' y='2' width='2' height='21' fill='" & _TargetColor & "'/>"
VAR _SvgSuffix = "</svg>"

-- ASSEMBLY: Combine in rendering order (back to front)
VAR _SVG = _SvgPrefix & _Sort & _Bar & _TargetLine & _SvgSuffix

RETURN _SVG

主な規約：

• 最初に CONFIG セクション -- 入力メジャー、スコープ列、色、フォント設定を記述します。ユーザーが変更するのはこのセクションだけです。
• NORMALIZATION セクション -- 生の値を SVG の座標空間にスケーリングします（下記を参照）。
• SVG ELEMENTS -- <rect>、<circle>、<text>、<line> などごとに VAR を 1 つ定義します。
• ASSEMBLY -- ドキュメント内の順序に従って要素を連結します（先頭が背面レイヤー、末尾が前面レイヤー）。
• <desc> によるソートの工夫 -- FORMAT(_Actual, "000000000000") を <desc> タグに埋め込むことで、テーブルやマトリックスを SVG 列で並べ替えられるようにします。

軸の正規化（重要）

SVG の座標は固定範囲に正規化する必要があります。生のメジャー値（例：1,234,567）をピクセル座標として直接使用することはできません。標準的なパターンは次のとおりです。

-- 1. Define the SVG coordinate range
VAR _BarMin = 0       -- leftmost position (or offset for labels)
VAR _BarMax = 100     -- rightmost position

-- 2. Find the maximum value across all rows in the visual's filter context
VAR _Scope = ALLSELECTED( 'Table'[GroupColumn] )
VAR _MaxInScope = CALCULATE( MAXX( _Scope, [Measure] ), REMOVEFILTERS( 'Table'[GroupColumn] ) )
VAR _AxisMax = _MaxInScope * 1.1   -- 10% padding

-- 3. Normalize each value to the SVG range
VAR _AxisRange = _BarMax - _BarMin
VAR _Normalized = DIVIDE( _Actual, _AxisMax ) * _AxisRange

チャートがスライサーのコンテキストに応じて変化する場合は、スコープに ALLSELECTED を使用してください。すべてのフィルターコンテキストで軸を固定する場合は、ALL を使用してください。* 1.1 の余白を設けることで、棒が端に接するのを防ぎます。

HASONEVALUE ガード

テーブルやマトリックスの SVG メジャーでは、複数のカテゴリがスコープに含まれる小計行や合計行に対するガードが必要です。

IF( HASONEVALUE( 'Table'[GroupColumn] ),
    -- SVG code here
)

このガードがないと、メジャーは総計行でも評価され、意味のない集計値が生成されます。

エスケープと色の規則

• SVG 属性にはシングルクォートを使用 -- DAX のダブルクォートのエスケープを避けられます：fill='#2196F3'
• DAX のダブルクォート：DAX の規則に従い "" としてエスケープします。
• レスポンシブなスケーリングには viewBox を使用：viewBox='0 0 100 25'
• <svg> 要素には xmlns が必要です
• # のみを使った 16 進数カラー -- 例：fill='#2196F3'。URL エンコードの %23 は画像ビジュアルでエラーの原因になります。色名は使用しないでください。
• JavaScript は使用しない -- SVG は宣言的な記述のみで構成する必要があります。

SVG の座標系

• Y=0 は上端です -- チャートでは値を反転します：_Height - _Value
• 正規化した座標には、範囲が 0～100 の viewBox を使用します。
• 要素はドキュメント内の順序で描画されます（先頭が背面、末尾が前面）。

系列データへの CONCATENATEX の使用

スパークラインや複数の点を持つチャートでは、CONCATENATEX を使って座標文字列を作成します。

VAR _Points = CONCATENATEX(
    _SparklineTable,
    [X] & "," & (100 - [Y]),
    " ",
    [Date], ASC
)
-- Produces: "0,80 10,60 20,40 30,20"
-- Use in: <polyline points='...'/>

ベストプラクティス

• まず UDF ライブラリを確認します。カスタム DAX を作成する前に、DaxLib.SVG または MacGuyver Toolbox の関数を使用してください
• VAR パターンは必須です。設定値ごとに VAR を 1 つ、SVG 要素ごとに VAR を 1 つ定義し、最後に組み立てます
• すべての値を正規化します。生のメジャー値は SVG の座標範囲にスケーリングする必要があります
• HASONEVALUE ガードを使用します。テーブル／マトリックスのコンテキストでは、合計／小計の行を必ずガードしてください。階層レベルがネストされている場合は ISINSCOPE を使用します
• <desc> の並べ替えテクニックを使用します。並べ替え可能な SVG 列では、書式設定した値を <desc> に埋め込みます
• 固定の width/height ではなく、レスポンシブなスケーリングに viewBox を使用します
• パフォーマンス向上のため、座標は整数に丸めます（文字列が短くなり、FORMAT 呼び出しのコストも下がります）
• 拡張メジャーとして保存します。SVG メジャーはセマンティックモデルに含めません
• display_folder を使用して SVG メジャーを整理します（例："SVG Charts"）
• まずプレビューします。静的な SVG を /tmp/ に保存してブラウザーで開き、DAX を記述する前に調整します
• セルごとにレンダリングされる SVG 文字列には 32K 文字の上限があります（DAX 式ではありません）。診断と対処方法については references/svg-table-matrix.md を参照してください
• モデルのメジャーで事前集計します。ストレージエンジンに集計をキャッシュさせ、SVG メジャーでは数値を座標にマッピングするだけにします
• 色は 16 進数のみを使用します。# を直接指定し、%23 による URL エンコードは使用しません
• 画像ビジュアルには query ブロックは不要です。必要なのは sourceType='imageData' と sourceField を指定した objects.image だけです
• アクセシビリティ：主要データをエンコードするすべての SVG には、隣接する読み取り可能な列と動的な代替テキスト用メジャーが必要です。references/svg-accessibility.md を参照してください

reportExtensions.json の形式

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/reportExtension/1.0.0/schema.json",
  "name": "extension",
  "entities": [{
    "name": "ExistingTable",
    "measures": [{
      "name": "Sparkline SVG",
      "dataType": "Text",
      "dataCategory": "ImageUrl",
      "expression": "...",
      "displayFolder": "SVG Charts"
    }]
  }]
}

制限事項

• インタラクティブ性はありません。SVG 画像は静的で、ホバー、クリック、ツールチップには対応していません
• JavaScript は使用できません。インラインスクリプトは除去されます
• レンダリングされたセル文字列ごとに 32K 文字の上限があります（DAX 式ではありません）。30 個以上の系列ポイントに対する CONCATENATEX は簡単に上限に近づきます。個別の図形より <polyline> を優先し、整数の座標と事前集計した系列を使用してください。詳しい診断については references/svg-table-matrix.md を参照してください
• セルごとに数式エンジンのコストがかかります。表示されている各セルで文字列構築式が評価されます。SVG の組み立てを座標のマッピングだけにできるよう、集計処理はモデルのメジャーに移してください
• アクセシビリティの課題：スクリーンリーダーは SVG URI からセルごとのデータを取得できません。隣接する読み取り可能な列と動的な代替テキストで対処してください。references/svg-accessibility.md を参照してください
• クラシックカード（card）は SVG をサポートしていません。代わりに cardVisual を使用してください

SVG メジャーを使用する場面

SVG メジャーは、テーブル、マトリックス、カード、画像ビジュアルに埋め込むシンプルなインライン画像に最適です。次のような場合に SVG を使用してください。

• テーブル／マトリックスのセル内にスパークライン、データバー、進捗バー、ステータスインジケーターを表示する
• カードビジュアルに KPI のマイクロチャートを表示する
• インタラクティブ性や複雑なデータ変換を必要としない軽量なビジュアルを作成する
• 追加のカスタムビジュアル登録を行わずに使用する（ネイティブビジュアルで動作します）

複雑でインタラクティブなビジュアライゼーション（クロスフィルター、ツールチップ、ホバー状態）や、広範なデータ変換を必要とするチャートタイプには、代わりに Deneb を使用してください。統計分析のチャート（分布、回帰、相関）には、代わりに Python/R を使用してください。

参考資料

コミュニティのサンプルとライブラリ

• references/community-examples.md -- 対象のビジュアルタイプ（テーブル／マトリックス、画像、カード）ごとに整理されたコミュニティの SVG テンプレートです。DaxLib.SVG の関数、Kerry Kolosko のテンプレート、PowerBI MacGuyver Toolbox のパターンが含まれます

視覚タイプ別

• references/svg-table-matrix.md -- テーブル／マトリックスのパターン：データバー、ブレットチャート、ダンベルチャート、重ね合わせ棒グラフ、ロリポップチャート、ステータスピル、スパークライン、棒スパークライン、面スパークライン、UDF パターン、軸の正規化、並べ替えのテクニック、画像サイズの設定、セルごとのパフォーマンスに関するガイダンス
• references/svg-image-visual.md -- 画像ビジュアルのパターン：KPI ヘッダー、終点付きスパークライン、ダッシュボードタイル、sourceType バインド、動的／条件付きレイアウト、レスポンシブ幅に関するガイダンス
• references/svg-card-slicer.md -- カード／スライサーのパターン：矢印インジケーター、ミニゲージ、ミニドーナツ、プログレスバー、ナラティブ文、callout.imageFX によるカードのバインド

アクセシビリティ

• references/svg-accessibility.md -- SVG メジャーのアクセシビリティ：隣接する読み取り可能な列、動的な代替テキスト、色のみでのエンコード、コントラスト要件、監査結果の重大度に関するガイダンス

一般

• references/svg-elements.md -- SVG 要素リファレンス（rect、circle、line、polyline、text、path、gradient、group）

例

すぐに使える DAX メジャー式は examples/ にあります：

• sparkline-measure.dax -- 折れ線スパークライン（polyline + CONCATENATEX）
• progress-bar-measure.dax -- 条件付きプログレスバー
• dumbbell-chart-measure.dax -- 実績対目標のダンベルチャート
• bullet-chart-measure.dax -- 感情アクションのドット付きブレットチャート
• overlapping-bars-measure.dax -- 差異ラベル付き重ね合わせ棒グラフ
• boxplot-measure.dax -- 箱ひげ図（DaxLib.SVG に着想を得ています）
• ibcs-bar-measure.dax -- IBCS 準拠の横棒グラフ（avatorl に着想を得ています）
• jitter-plot-measure.dax -- ジッター付きドットストリップチャート（DaxLib.SVG に着想を得ています）
• overlapping-bars-with-variance-measure.dax -- 差異バー＋矢印アイコン＋％ラベル付き重ね合わせ棒グラフ（Kurt Buhler / Data Goblins）
• lollipop-conditional-measure.dax -- スケーリングされたドット＋自動書式設定ラベル付きロリポップチャート（Kurt Buhler / Data Goblins）
• waterfall-measure.dax -- 累積 OFFSET 配置＋接続線付きウォーターフォールチャート（Kurt Buhler / Data Goblins）
• status-pill-measure.dax -- カテゴリー色＋テキストラベル付きの角丸ピルバッジ（Kurt Buhler / Data Goblins）

ヘルパーライブラリ

ライブラリ	作者	主な機能
DaxLib.SVG	Jake Duddy	UDF ライブラリ：面、折れ線、箱ひげ図、ヒートマップ、ジッター、バイオリン
PBI-Core-Visuals-SVG-HTML	David Bacci	チップ、トルネード、グラデーションマトリックス、棒グラフ UDF
PowerBI MacGuyver Toolbox	Stepan Resl / Data Goblins	20 種類以上の棒グラフ、14 種類以上の折れ線グラフ、24 種類以上の KPI テンプレート
Dashboard Design UDF Library	Dashboard-Design	目標線付き棒グラフ、ピルビジュアル
Kerry Kolosko Templates	Kerry Kolosko	スパークライン、データバー、KPI カード

関連スキル

• pbi-report-design -- レイアウトとデザインのベストプラクティス
• deneb-visuals -- 複雑なインタラクティブな可視化のための Vega/Vega-Lite
• python-visuals -- 統計グラフのための matplotlib/seaborn
• r-visuals -- 統計グラフのための ggplot2
• pbir-format（pbip プラグイン）-- PBIR JSON 形式のリファレンス（拡張メジャー、ImageUrl バインド）