sap-sac-custom-widget

SAP Analytics Cloud カスタムウィジェット開発

関連スキル

• sap-sac-scripting：カスタムウィジェットが SAC のスクリプト、ウィジェット、ストーリー／アプリケーション API と連携する場合に使用します
• sap-sac-planning：ウィジェットが計画ワークフローや計画テーブルとのやり取りに参加する場合に使用します
• sapui5：Web コンポーネント／UI5 フロントエンドの実装パターンとブラウザー側の品質に使用します
• sap-dependency-security：ウィジェットプロジェクトにサードパーティ製のチャート作成ライブラリやビルド依存関係を追加する場合に使用します

目次

• 概要
• AI 支援による生成
• ウィジェットの検出とエビデンスの取り込み
• ローカルカスタムウィジェットビルダー
• SAP サンプルウィジェットから学ぶ
• ブラウザー設計ランタイム
• CSS とスタイルの準拠
• SAC へのインポートとパッケージ化
• 本番環境監査から学ぶ
• プロパティのライフサイクル
• 検証と成果物の管理
• プラグインコンポーネント
• クイックスタート
• コミュニティサンプルウィジェット
• 主要な概念
• よくあるエラーと解決策
• 同梱リソース

概要

このスキルを使うと、SAP Analytics Cloud（SAC）向けのカスタムウィジェットを開発できます。カスタムウィジェットは、カスタムビジュアライゼーション、インタラクティブ要素、特化した機能を追加して、SAC のストーリーやアプリケーションを拡張する Web コンポーネントです。

このスキルを使用する場面

次の場合にこのスキルを使用します：

• 標準の SAC では利用できないカスタムビジュアライゼーションを作成する
• プロンプトに基づくウィジェットのアイデア、ブランドに合わせたウィジェットパッケージ、または複合ウィジェット向けのデザインを生成する
• サードパーティ製のチャート作成ライブラリ（ECharts、D3.js、Chart.js）を統合する
• SAC アプリケーション向けのインタラクティブな入力コンポーネントを作成する
• 特化したデータ表示や KPI ウィジェットを実装する
• カスタム機能を追加して Analytics Designer アプリケーションを拡張する
• カスタムウィジェットの読み込みやデータバインディングの問題をトラブルシューティングする

要件：

• Optimized Story Experience または Analytics Designer を備えた SAC テナント
• JavaScript／Web コンポーネントの知識
• 外部ホスティング（GitHub Pages、AWS S3、Azure）または SAC ホスト型リソース（QRC Q2 2023+）

---

AI 支援による生成

プロンプトに基づいてウィジェットを作成する場合は、まずウィジェットの役割とデータソースのモードを分類してから、選択した完全なパッケージを生成する前に、役割を考慮した候補を 2～3 個提示します。AI 生成コードを SAC 互換に保ち、データバインディングを使用する場合はその順序を維持し、インポート前に検証して修正してください。出力の仕様、RAG コンテキストのパターン、ブランドスタイル、複合ウィジェットの注意点については、references/ai-assisted-composite-generation.md を参照してください。

---

ウィジェットの検出とエビデンスの取り込み

テーブル、チャート、KPI、メニュー、サイドバー、フィルター、ハイブリッドコントロールを生成する前に、ウィジェットの役割とデータソースのモードの両方を選択してください。SAC にバインドするウィジェットでは、ディメンション、メジャー／キー数値、日付、バージョン、フィルター、フィード順序を確認します。純粋な UI コントロールでは、それらの代わりに、インタラクション、ナビゲーション、状態、メソッド／イベント、アクセシビリティ、レスポンシブレイアウトの要件を収集します。ユーザーが提示したスクリーンショット、PDF、画像、ブランドガイド、サニタイズ済みデータはエビデンスとして受け入れますが、コードを生成する前に技術 ID、フィードのマッピング、アセットの権利、ライセンスを確認してください。ウィジェット概要、エビデンスの適用範囲、ホスト型ツールの安全対策については、references/widget-discovery-intake.md を参照してください。

---

ローカルのカスタムウィジェットビルダー

エンタープライズ環境や制限の厳しいローカル環境向けには、インストール不要の標準スキャフォールドビルダーとして templates/local-builder/ を提供してください。静的な HTML／CSS／バニラ JavaScript として動作し、パブリック CDN や外部パッケージを使用せず、SAC アップロード用アーティファクトを 2 つに分けてダウンロードします。1 つは widget.json、もう 1 つはルート直下のコンポーネント JavaScript ファイルのみを含む Resource-ZIP です。file:// の直接利用がブロックされる場合は、Node の server.mjs をフォールバックとして使用してください。機密情報を含まないデスクトッププロトタイプで、ユーザーがパブリックウェブの利用を明示的に許可している場合は、カスタムウィジェットビルダー またはライブデモを任意で提案できます。ただし、テナントの素材を送信したり、ローカルで検証せずにエクスポートを信頼したりしないでください。ビルダーの境界、エクスポートのルール、ホスト型ツールの安全対策、検証チェックについては、references/local-builder-workflow.md を参照してください。

---

SAP サンプルウィジェットから得られる知見

チャート、KPI、階層、入力ユーティリティ、Widget Add-On、またはビルドベースのウィジェットを生成する前に、references/sap-sample-widget-lessons.md を参照してください。この資料では、すべての SAP サンプルフォルダーを監査し、データバインディングを優先するスキャフォールド、ルート相対の Resource-ZIP URL、スタイリングとビルダーパネルの分離、サポートフラグ、カスタム types、スクリプトのメソッド／イベント、アドオンの extensions[]、ビルドベースのアプリに関する注意点について、再利用可能な知見をまとめています。構造とリスクの確認にのみ活用し、SAP のサンプルコードやアセットを生成パッケージにコピーしないでください。

---

ブラウザのデザインランタイム

生成するウィジェットパッケージには、ビルド不要でファイルを起点とするブラウザプレビュー用スキャフォールドとして templates/design-runtime/ を含めてください。生成後にこれを使用して、SAP の外部でカスタムウィジェットの基本機能をモックし、プロパティ、デザイントークン、サンプルデータ、ビューポートを調整し、複数のウィジェットを比較し、エージェントの反復用ペイロードをエクスポートします。ランタイムの境界と設定／エクスポートの仕様については、references/browser-design-runtime.md を参照してください。スキャフォールドの生成／エクスポートには templates/local-builder/ を、プレビューと反復には templates/design-runtime/ を使用してください。

---

CSS とスタイリングの準拠

カスタムウィジェットのスタイルは、Web Component／Shadow DOM の境界内で設定してください。ウィジェットの内部のスタイリングに、SAC の最適化されたストーリーテーマ CSS、SAP シェルのセレクター、グローバルなストーリー CSS を使用しないでください。生成パッケージでは、CSS／HTML を別ファイルに分割する前にホスティングモードを確認してください。SAC の ZIP アップロードパッケージでサポートされるのは、コンポーネント JavaScript と PNG／JPG アイコンのみです。SAP Help に基づく許可／制限対象のスタイリングルールについては、references/css-and-styling-compliance.md を参照してください。

---

SAC のインポートとパッケージング

widget.json を生成する前に、配布方法を決めてください。SAC Resource-ZIP のアップロードと外部 HTTPS ホスティングでは、URL のルールが異なります。SAC Resource-ZIP でアップロードする場合は、widget.json を別途用意し、最初にアップロードしてから、widget.js、builder.js、styling.js などのルート直下のコンポーネント JavaScript ファイルを含む Resource-ZIP をアップロードしてください。この Resource-ZIP には、widget.json、サブフォルダー、テスト、README ファイル、CSS、HTML を含めないでください。

Resource-ZIP のマニフェストでは、"/widget.js" のようなルート相対のコンポーネント URL を使用してください。外部ホスティングでは、HTTPS の完全な URL を使用します。"widget.js" のようなローカルプレビュー用のパスは、対象の SAC フローでその解決方法が明示的に説明されている場合を除き、プレビュー専用の設定にとどめてください。単純に設定できる色は、"#f4f7fa" のような 16 進数のデフォルト値を持つ string プロパティとしてモデル化してください。Color 型は、対象の SAC テナントと対象パネルのフローで正確に受け入れられることを確認してから使用してください。ブラウザーでのプレビューや Node のテストは有用ですが、SAC にインポートできる証明にはなりません。ビルダー／スタイリングパネルを持つウィジェットでは、テキスト編集時にフォーカスと折りたたみ状態を維持し、コンポーネントの JS を自己完結させ、ソースのみのプレビューではなく、最終的な outputs/ の成果物を検証してください。ウィジェットが完成したら、最終的なチャットの回答で、完成した両方のアップロード用成果物、つまり widget.json マニフェストと Resource-ZIP をダウンロードできるようにしてください。アップロード手順、ZIP の内容確認、最終成果物のテスト、ビルダー／ツリーのルール、最終的なダウンロードの引き渡し、SAC エラーの切り分けについては、references/sac-import-packaging-lessons.md を参照してください。

---

本番監査から得られた教訓

ローカルテストに合格しているのに SAC でウィジェットが拒否された場合は、references/production-widget-lessons.md を参照してください。このドキュメントでは、バンドル内の生の制御文字、Analytics Designer のメソッド本体の制限、必須の整合性状態、クライアント側のみのマニフェスト検証、アイコンとフォントの分離、ユーザーと言語の境界、ブックマークのリスク、不透明なエラーの二分探索、動作の事前確認ガード、ブラウザープレビューの限界を取り上げています。証拠のラベルも指針の一部として扱ってください。テナントでの観察結果、SAP が文書化した動作、未確認の仮説を、同等のものとして示してはなりません。

プロパティのライフサイクル

SAC のプロパティは、外部から届く状態ストリームとして扱ってください。SAC はプロパティを 1 つずつ渡したり、ウィジェットが書き込んだ値を反映したり、その表現を変更したりする場合があります。更新をマージし、1 つの読み取り経路で正規化してから、マージ後の状態を基にレンダリングしてください。プロパティの順序を前提にしたり、空の初回レンダリングでビルダーの初期化フラグを消費したりしないでください。マニフェストのメソッド本体は Analytics Designer のスクリプトです。宣言済みのプロパティを読み書きできますが、非公開のコンポーネントメソッドは呼び出せません。

ビルダーとスタイリングのパネルは、状態を保持するエディターです。テキストの編集対象を絞り、フォーカス、キャレット、選択範囲、検索状態、折りたたみ状態が維持されるようにしてください。2 つのエディターが同じドキュメントを共有する場合は、不明な設定キーを保持し、1 回のユーザー操作につき、プロパティのディスパッチと取り消し操作をそれぞれ 1 回にしてください。構造化されたインポートまたはエクスポートでは、安定した ID を保持し、ネストされたテンプレートをディープコピーし、ユーザーが作成した名前には null プロトタイプのマップを使用して、すべての言語スロットをテストしてください。references/property-lifecycle.md を参照してください。

検証と成果物の取り扱い

ソースヘルパーやブラウザープレビューだけでなく、ビルド済みのコンポーネントファイルと最終的な Resource-ZIP を検証してください。すべての出力を最初に生成して検証し、その後で書き出してください。最終バンドルを単独でテストし、SRI のバイト列が完全に一致することを確認し、生の制御文字がないかスキャンしてください。また、DOM エミュレーションでは再現できないレイアウト、フォーカス、フォント、ポインター、ライフサイクルの動作には、実際のブラウザーを使用してください。references/verification-and-artifacts.md を参照してください。

---

プラグインコンポーネント

このプラグインは、包括的なウィジェット開発を支援するため、特化型エージェント、コマンド、検証フックを提供します。

エージェント

エージェント	色	目的	トリガーの例
widget-architect	青	ウィジェットの構造、メタデータ、統合パターンを設計します	「カスタムウィジェットを設計」「ウィジェットのアーキテクチャを計画」
widget-debugger	黄	読み込み、データバインディング、CORS、実行時の問題をトラブルシューティングします	「ウィジェットが読み込まれない」「CORS エラー」「データがバインドされない」
widget-api-assistant	緑	JavaScript ウィジェットのコード、ライフサイクル関数、API 統合を作成します	「ウィジェットのコードを作成」「ライフサイクル関数を実装」

コマンド

コマンド	使用方法	説明
/widget-validate	/widget-validate [file]	widget.json スキーマと widget.js の構造を検証します
/widget-generate	/widget-generate	JSON、JS、ローカルビルダー、ブラウザーデザインランタイムを含むウィジェットのひな形を対話形式で生成します
/widget-lint	/widget-lint [file]	パフォーマンス、セキュリティ、ベストプラクティスを分析します

検証フック

Write/Edit 操作時に自動で実行される品質チェック：

• widget.json：必須フィールド、タグの命名、プロパティの型、データバインディング設定
• widget.js：ライフサイクル関数、Shadow DOM、propertiesChanged のディスパッチ
• パフォーマンス：リサイズのデバウンス、チャートの破棄、XSS の防止
• コンテキストのリマインダー：テンプレートの提案、コマンドの推奨

テンプレート

templates/ ディレクトリにある、そのまま使えるひな形：

• basic-widget.js - すべてのライフサイクル関数を備えた最小限の Web コンポーネント
• data-bound-chart.js - データバインディングに対応した ECharts ウィジェット
• styling-panel.js - 実行時カスタマイズパネル
• builder-panel.js - デザイン時設定パネル
• local-builder/ - 静的なローカルひな形ビルダーと SAC アーティファクトエクスポーター
• design-runtime/ - ブラウザーでのプレビューとデザイン反復用ランタイム
• widget.json-minimal - 最小限のメタデータ
• widget.json-complete - すべてのオプションを含む、機能が充実したメタデータ

---

クイックスタート

最小限のカスタムウィジェットの構成

カスタムウィジェットには、次の 2 つのファイルが必要です。

1. widget.json（メタデータ）

{
  "id": "com.company.mywidget",
  "version": "1.0.0",
  "name": "My Custom Widget",
  "description": "A simple custom widget",
  "vendor": "Company Name",
  "license": "MIT",
  "icon": "",
  "webcomponents": [
    {
      "kind": "main",
      "tag": "my-custom-widget",
      "url": "https://your-host.com/widget.js",
      "integrity": "",
      "ignoreIntegrity": true
    }
  ],
  "properties": {
    "title": {
      "type": "string",
      "default": "My Widget"
    }
  },
  "methods": {},
  "events": {}
}

2. widget.js（Web コンポーネント）

(function() {
  const template = document.createElement("template");
  template.innerHTML = `
    <style>
      :host {
        display: block;
        width: 100%;
        height: 100%;
      }
      .container {
        padding: 16px;
        font-family: Arial, sans-serif;
      }
    </style>
    <div class="container">
      <h3 id="title">My Widget</h3>
      <div id="content"></div>
    </div>
  `;

  class MyCustomWidget extends HTMLElement {
    constructor() {
      super();
      this._shadowRoot = this.attachShadow({ mode: "open" });
      this._shadowRoot.appendChild(template.content.cloneNode(true));
      this._props = {};
    }

    connectedCallback() {
      // Called when element is added to DOM
    }

    onCustomWidgetBeforeUpdate(changedProperties) {
      // Called BEFORE properties are updated
      this._props = { ...this._props, ...changedProperties };
    }

    onCustomWidgetAfterUpdate(changedProperties) {
      // Called AFTER properties are updated - render here
      if (changedProperties.title !== undefined) {
        this._shadowRoot.getElementById("title").textContent = changedProperties.title;
      }
    }

    onCustomWidgetResize() {
      // Called when widget is resized
    }

    onCustomWidgetDestroy() {
      // Cleanup when widget is removed
    }

    // Property getter/setter (required for SAC framework)
    get title() {
      return this._props.title;
    }
    set title(value) {
      this._props.title = value;
      this.dispatchEvent(new CustomEvent("propertiesChanged", {
        detail: { properties: { title: value } }
      }));
    }
  }

  customElements.define("my-custom-widget", MyCustomWidget);
})();

⚠️ 本番環境での注意：上記の ignoreIntegrity: true 設定は開発時のみ使用します。本番環境にデプロイする場合は、SHA256 インテグリティハッシュを生成して、ignoreIntegrity: false に設定してください。

---

コミュニティのサンプルウィジェット

SAP は、17 個のカスタムウィジェットのサンプルフォルダーを含むコミュニティサンプルリポジトリを提供しています。

リポジトリ：SAP-samples/SAC_Custom_Widgets

カテゴリ	ウィジェット
チャート	ファネル、パレート、サンキー、サンバースト、ツリー、ライン、UI5 ガント
KPI/ゲージ	KPI リング、ゲージグレード、ハーフドーナツ、ネストパイ、カスタムパイ
ユーティリティ	ファイルアップロード、ワードクラウド、バーグラデーション、ウィジェットアドオンのサンプル

要件：ほとんどのサンプルは、データバインディングと最適化ビュー モード（OVM）、または最適化された統合ストーリーエクスペリエンスを前提としています。

注：本番環境で使用する前にサードパーティライブラリのライセンスを確認し、サンプルを移動する際はホストされているコンポーネントのパスを調整してください。また、SAC へのライブインポートと実行時の検証は、テナントごとに異なるものとして扱ってください。サンプルごとの監査と作成時の知見については、references/sap-sample-widget-lessons.md を参照してください。

---

主要な概念

ライフサイクル関数

SAC フレームワークによって呼び出される必須の関数：

• onCustomWidgetBeforeUpdate(changedProperties) - 更新前のフック
• onCustomWidgetAfterUpdate(changedProperties) - 更新後（ここでレンダリングします）
• onCustomWidgetResize() - リサイズイベントを処理します
• onCustomWidgetDestroy() - リソースをクリーンアップします

データバインディング

SAC モデルのデータを受け取るには、widget.json で設定します：

{
  "dataBindings": {
    "myDataBinding": {
      "feeds": [
        {
          "id": "dimensions",
          "description": "Dimensions",
          "type": "dimension"
        },
        {
          "id": "measures",
          "description": "Measures",
          "type": "mainStructureMember"
        }
      ]
    }
  }
}

JavaScript でデータにアクセスします：

// Get data binding
const dataBinding = this.dataBindings.getDataBinding("myDataBinding");

// Access result set
const data = this.myDataBinding.data;
const metadata = this.myDataBinding.metadata;

// Iterate over rows
for (let i = 0; i < this.myDataBinding.data.length; i++) {
  const row = this.myDataBinding.data[i];
  const dimensionValue = row.dimensions_0 ? row.dimensions_0.label : "";
  const measureValue = row.measures_0 ? row.measures_0.raw : 0;
}

ホスティングオプション

1. SAC ホスト（推奨、QRC Q2 2023 以降）

• ファイルを SAC > Files > Public Files に直接アップロードします
• Resource-ZIP のアップロードフローでは、まず widget.json をアップロードし、SAC で Resource File ボタンが有効になったら、別途 Resource-ZIP をアップロードします
• Resource-ZIP のアップロードフローでは、"/widget.js" のようなルート相対 URL を使用します。本番用マニフェストでは、ローカルの Windows バックスラッシュや、ローカルプレビュー用のパスをそのまま使用しないでください
• "integrity": "" と "ignoreIntegrity": true を設定します

2. GitHub Pages

• ウィジェットのファイルを含むリポジトリを作成します
• Settings で GitHub Pages を有効にします
• 次の URL を使用します：https://username.github.io/repo/widget.js

3. 外部 Web サーバー

• AWS S3、Azure Blob、または任意の HTTPS サーバーを使用します
• CORS ヘッダー Access-Control-Allow-Origin: * を含める必要があります

セキュリティ：整合性ハッシュ

本番環境では、Windows／macOS／Linux 用の Node.js を使って SHA256 整合性値を生成します：

# Generate integrity hash for widget.js
node -e "const fs=require('node:fs');const crypto=require('node:crypto');const file=process.argv[1]||'widget.js';console.log('sha256-'+crypto.createHash('sha256').update(fs.readFileSync(file)).digest('base64'));" widget.js

# Update JSON
"integrity": "sha256-abc123...",
"ignoreIntegrity": false

macOS／Linux または Git Bash では、OpenSSL も使用できます。マニフェストに追加する前に、出力の先頭に sha256- を付けてください：

openssl dgst -sha256 -binary widget.js | openssl base64 -A

---

よくあるエラーと解決策

エラー	原因	解決策
"The system couldn't load the custom widget"	URL の誤りまたはホスティングの問題	URL にアクセスできることを確認し、CORS を確認してください
"Integrity check failed"	ハッシュの不一致	JS の変更後にハッシュを再生成してください
ウィジェットが表示されない	connectedCallback の render が不足しています	onCustomWidgetAfterUpdate で render を呼び出してください
プロパティが更新されない	propertiesChanged の dispatch が不足しています	propertiesChanged とともに dispatchEvent を使用してください
データが表示されない	データバインディングの設定に誤りがあります	JSON の feeds が使用方法と一致していることを確認してください
CUSTOM_WIDGET_SERVICE_EXCEPTION または不透明な HTTP 500	生の制御文字または曖昧なコードポイント、形式不正のメソッド本文、マニフェストと ZIP の組み合わせ、または別のアップロード制約	ソースとバンドルで制御コードポイント、BOM、ゼロ幅文字、行区切り文字を検索し、変数を 1 つずつ変更した JSON と ZIP のプローブを使用してください
メソッド本文が不明な関数または型のエラーで拒否される	本文が宣言済みプロパティを使わず、コンポーネントの内部を呼び出しています	状態をプロパティとして宣言し、本文でそのプロパティを読み書きするようにしてください
integrity がないためマニフェストが拒否される	webcomponents[] に必須フィールドがありません	integrity を追加し、開発時は "" と ignoreIntegrity: true、または実際の sha256-... ダイジェストと false のいずれかを使用してください
アイコンが空白で表示される	アイコン名がバンドルされていないか、推測したものです	コミット済みのアイコンマップを生成して検索してください。ウィジェット内で IconPool に依存しないでください
ウィジェットのフォントが正しくない	フォームコントロールが UA フォントを使用しているか、パネルの CSS が SAC を上書きしています	コントロールでフォントを継承し、デザイン時のパネルでカスタムフォントスタックを避けてください
個人情報または言語の値が空、または正しくない	ウィジェットがユーザーまたは SAC のロケールコンテキストを検出しようとしました	ストーリースクリプトから宣言済みプロパティを通じて渡してください
"Color" is not a valid type またはデフォルト値に Color が必要とされる	テナント／インポートの処理で単純な色プロパティが拒否されました	設定可能な単純な色には、string と 16 進数のデフォルト値を使用してください
メインコンポーネントを読み込めなかった	リソース URL、ZIP の内容、または JS 構文に問題があります	ルート相対の webcomponents[].url、Resource-ZIP のルート内容を確認し、その後 node --check を実行してください
Resource File のアップロードが無効になっている	widget.json の検証がまだ完了していません	先に widget.json をアップロードして検証し、その後 Resource-ZIP をアップロードしてください
Resource-ZIP のインポートまたは後続の読み込みが失敗する	ZIP にマニフェスト、フォルダー、CSS／HTML、または無関係なファイルが含まれています	ルート階層にある JS コンポーネントファイルのみと、任意の PNG／JPG アイコンだけを残してください
ビルダーの入力でフォーカスまたは折りたたみ状態が失われる	テキスト編集によって全体が再レンダリングされます	フィールド／行／JSON のテキストを直接更新し、構造変更の場合に限って全体をレンダリングしてください
プレビューは動作するが、SAC コンポーネントは単独で失敗する	プレビューが、バンドルされた JS に存在しない共有ソースヘルパーに依存しています	プレビュー専用のヘルパースクリプトなしで、最終的な widget.js、builder.js、styling.js をテストしてください
重複したメニュー項目が競合する	サブツリーの複製時に書き換えられたのはルート ID のみです	子孫の ID も書き換え、ツリー全体で一意性をテストしてください
パネルに表示された値がランタイムで無視される	プロパティは保存またはエクスポートされていますが、ランタイムでは読み取られていません	マニフェストの各プロパティに対し、ランタイムでの使用確認と動作テストを追加してください
有効なゼロ値がデフォルト値になる	数値変換で `Number(value)
ビルダーで入力済みテキストまたは検索状態が失われる	更新のたびにパネルが再構築されます	フィールドをその場で更新し、構造的な再レンダリングが必要な場合はフォーカス、選択範囲、キャレットを復元してください
名前変更または複製後に古い状態が残る	ID が位置ベースであるか、浅いコピーによってネストされたデータが別名参照されています	安定した ID を維持し、テンプレートをディープコピーして、参照を保持するすべての箇所を列挙してください
DOM テストには合格するが、SAC でレイアウトが失敗する	テスト環境にレイアウトまたはフォントメトリクスがありません	実際のブラウザーでジオメトリとフォント依存の動作を確認してください
ユーザーが入力した名前の大文字と小文字によって動作が一貫しない	複数の箇所でメンバーシップ確認に完全一致比較を使用しています	照合ルールを一元化し、大文字と小文字だけを変えた名前変更をテストしてください

---

デバッグ

ブラウザーの開発者ツール

1. Chrome DevTools を開きます（F12）
2. Sources タブ：widget.js を見つけ、ブレークポイントを設定します
3. Console タブ：console.log の出力を確認します
4. Network タブ：ファイルが読み込まれているか確認します（ステータス 200）

デバッグパターン

onCustomWidgetAfterUpdate(changedProperties) {
  console.log("Widget updated:", changedProperties);
  console.log("Current props:", this._props);
  console.log("Data binding:", this.myDataBinding && this.myDataBinding.data);
  this._render();
}

---

ウィジェットアドオン（QRC Q4 2023 以降）

ウィジェットアドオンを使用すると、ゼロから構築せずに、組み込みの SAC ウィジェットを拡張できます。

ユースケース：

• チャートのツールチップをカスタマイズする
• プロット領域に視覚要素を追加する
• 組み込みのスタイルを上書きする

対応チャート：棒／縦棒、積み上げ棒／縦棒、折れ線、積み上げ面、数値ポイント

主な違い：

• main と builder コンポーネントのみ（styling はありません）
• 拡張対象（tooltip、plotArea、numericPoint）を指定する必要があります
• SAC はメソッドを介してチャートのコンテキストデータを提供します

実装の全容については、references/widget-addon-guide.md を参照してください。

---

同梱リソース

テンプレート（すぐに使えるコード）

• templates/basic-widget.js - 最小構成の Web コンポーネントのひな形（約 60 行）
• templates/data-bound-chart.js - SAC データバインディングを使用する ECharts ウィジェット（約 120 行）
• templates/styling-panel.js - 実行時のカスタマイズ用スタイリングパネル（約 150 行）
• templates/builder-panel.js - デザイン時の設定用ビルダーパネル
• templates/local-builder/ - メタデータ、フィード、プロパティ、メソッド、イベント、および SAC の 2 ファイルエクスポートに対応する、インストール不要のローカルビルダー
• templates/design-runtime/ - ビルド不要のブラウザープレビュー、デザイントークンのコントロール、シナリオ切り替え、およびエージェントの反復作業用エクスポート
• templates/widget.json-minimal - 最小限のメタデータ（約 25 行）
• templates/widget.json-complete - フル機能のメタデータ（約 100 行）

リファレンスドキュメント

1. references/json-schema-reference.md - JSON スキーマの完全なドキュメント
2. references/widget-templates.md - 追加のウィジェットテンプレートパターン（6 種類のテンプレート）
3. references/echarts-integration.md - ECharts ライブラリの統合ガイド
4. references/widget-addon-guide.md - ウィジェットアドオンの開発（QRC Q4 2023 以降）
5. references/best-practices-guide.md - パフォーマンス、セキュリティ、開発のガイドライン
6. references/advanced-topics.md - カスタム型、スクリプト API 型、インストール
7. references/integration-and-migration.md - スクリプトの統合、コンテンツの移送
8. references/script-api-reference.md - DataSource、Selection、MemberInfo API
9. references/ai-assisted-composite-generation.md - プロンプト主導の生成、RAG、ブランドスタイル、検証、およびコンポジット対応の出力に関するガイダンス
10. references/local-builder-workflow.md - エンタープライズ向けの安全なローカルビルダーのワークフロー、エクスポート仕様、検証チェックリスト
11. references/sap-sample-widget-lessons.md - SAP サンプルウィジェットの監査マトリックス、再利用可能な生成の知見、アドオン／ビルド方式の振り分けに関する注意点
12. references/browser-design-runtime.md - SAP 以外のブラウザープレビューランタイム、サイドカー設定、エージェントの反復作業用エクスポート
13. references/css-and-styling-compliance.md - 生成ウィジェット向けの、SAP Help に基づく CSS、テーマ、Shadow DOM、パッケージングのガイダンス
14. references/sac-import-packaging-lessons.md - SAC でホストされる Resource-ZIP のアップロード手順、URL ルール、ZIP の衛生管理、ビルダー／ツリーの状態ルール、コンポーネントの自己完結性チェック、最終成果物のテスト、SAC エラーのトリアージ
15. references/widget-discovery-intake.md - ウィジェットの役割／データソースの選択、添付ファイルの受付、Widget Brief、ホスト型ツールの安全対策
16. references/production-widget-lessons.md - テナントで確認されたアップロード失敗、スクリプトメソッドの制限、整合性、分離、二分探索、事前チェックのガード
17. references/property-lifecycle.md - SAC プロパティの正規化、スクリプトメソッドの境界、状態を持つエディター、永続化、構造化データのルール
18. references/verification-and-artifacts.md - ビルド済みバンドルの検証、テストの見落とし、変更の証拠、アップロードのトリアージ、決定論的な成果物チェック

公式ドキュメントへのリンク

主な参考資料（スキルの更新用）：

• カスタムウィジェット開発者ガイド
• 開発者ガイド PDF
• ウィジェット API PDF（2025）

サンプルウィジェット：

• SAP サンプルリポジトリ
• SAP カスタムウィジェット GitHub

---

バージョン履歴

未リリース

• 統合されたカスタムウィジェットの知見に基づき、プロパティのライフサイクルと成果物の検証に関するガイダンスを追加しました。正規の型変換、状態を保持するパネル編集、実行時の使用チェック、実ブラウザーでの境界条件、決定論的な最終パッケージチェックが含まれます
• ホスティングモードの URL 検証、危険な Unicode／制御コードポイントのスキャン、宣言されたロケールの処理、ツールが見つからない場合の検証結果を明確にしました
• 本番環境の監査で得た知見を追加しました。制御文字によるアップロード失敗、プロパティのみを扱う Analytics Designer メソッド本体、必須の整合性状態、不透明なエラーの二分探索、分離されたアイコン／フォント、ブックマークのリスク、動作の事前チェックが含まれます
• マニフェストのメソッド本体から Web コンポーネントの内部を呼び出さないよう、JSON メソッドのガイダンスを修正しました
• ローカルウィジェットのメタデータ、プロパティ／フィードの設定、SAC の 2 ファイル成果物のエクスポートに対応する、エンタープライズ環境で安全に使える templates/local-builder/ スキャフォールドを追加しました
• ビルダーパネル生成用の、バンドルされた自己完結型テンプレートとして templates/builder-panel.js を追加しました
• ローカルビルダーの検証範囲を追加しました。last_verified は更新していません。SAC へのライブアップロード／実行時検証は引き続き保留中です
• SAP のサンプルウィジェットから得た知見とローカルビルダーのパターンに関するヒントを追加しました。データバインドされたチャート、KPI／ゲージウィジェット、フロー／階層ウィジェット、入力ユーティリティ、Widget Add-ons、ビルドベースのアプリが含まれます。上流のサンプルコードはコピーしていません

v2.3.2（2026-07-06）

• Configurable Menu Navigation プロジェクトから、SAC Resource-ZIP のインポートに関する知見を追加しました
• widget.json と Resource-ZIP を個別にアップロードするフロー、SAC がホストするルート相対 URL、Resource-ZIP のコンテンツ管理、シンプルな色プロパティの移植性を明確にしました
• Resource-ZIP のコンポーネント URL を単独で指定する場合と、リスクのある Color プロパティの使用に関するフックの警告を追加しました
• Configurable Menu Navigation の知見を拡充しました。ビルダーのフォーカス／折りたたみ状態、ツリー内の重複 ID の書き換え、自己完結型のコンポーネント JS、プレビューの整合性、古いパネルのクリーンアップ、レイアウト／スタイルプロパティの同期、安全な出力のクリーンアップ、成果物の命名が含まれます
• 最後のチャットでの引き継ぎ時に、widget.json マニフェストと Resource-ZIP の両方を、個別にダウンロード可能な成果物として提示するよう必須にしました

v2.1.0（2026-06-12）

• SAC Q2 2026（バージョン 2026.8）に更新しました
• QRC1／QRC2 2026 ではカスタムウィジェットのフレームワークに変更はありません。ライフサイクル関数と JSON スキーマも変更されていません
• これまで記載されていなかったルートレベルのプロパティを文書化しました：eula、imports、supportsMobile、supportsExport、supportsLinkedAnalysisFilterOnSelection、supportsViewportLoading、supportsBookmark、types
• ES モジュールの読み込みに使用する Web コンポーネントの type プロパティを文書化しました
• プロパティごとの includeInBookmarks フラグと、boolean[]／integer[] 型を文書化しました
• 高度なトピックに serializeCustomWidgetToImage() と customWidgetRenderComplete を追加しました
• 確認済み：4 つのライフサイクル関数、フィード型、テンプレートに変更はありません

v2.0.0（2025-12-27）

• 専門エージェントを 3 つ追加しました：widget-architect、widget-debugger、widget-api-assistant
• スラッシュコマンドを 3 つ追加しました：/widget-validate、/widget-generate、/widget-lint
• Write/Edit 時に品質チェックを自動実行する検証フックを追加しました
• ドキュメント監査済みのテンプレートを templates/ ディレクトリに 5 つ追加しました
• 包括的なプラグインパターンに合わせて、プラグインの構成を強化しました
• 最終検証日を更新しました v1.2.0（2025-11-26）
• SAC のバージョン参照を 2025.21 に更新
• SKILL.md の長さを 563 行から約 200 行に最適化
• 8 つすべてのリファレンスファイルに目次を追加
• 段階的開示アーキテクチャを改善

v1.1.0（2025-11-22）

• Widget Add-On 機能のドキュメントを追加（QRC Q4 2023 以降）
• ベストプラクティスガイドを追加（パフォーマンス、セキュリティ、開発）
• 高度なトピックを追加（カスタム型、スクリプト API 型、インストール）
• キーワードを追加して説明を強化
• エラー防止の対象範囲を 25 以上に拡大

v1.0.0（2025-11-22）

• 初回リリース
• JSON メタデータの完全なリファレンス
• ライフサイクル関数のドキュメント
• データバインディングガイド
• スタイリングパネルの実装
• ホスティングオプション（SAC ホスト、GitHub、外部）
• セキュリティ（整合性ハッシュ、CORS）
• よくあるエラーとデバッグ

---

SAC バージョン：2026.8