wix-cli-dashboard-page

Wix ダッシュボードページビルダー

Wix CLI アプリケーション向けの、機能が充実したダッシュボードページ拡張機能を作成します。ダッシュボードページは Wix サイトオーナーのダッシュボードに表示され、サイト管理者がデータの管理、設定の構成、管理タスクの実行を行えるようにします。

---

クイックスタートチェックリスト

ダッシュボードページを作成する際は、次の手順を順番に実行してください。

1. ページフォルダーを作成します：src/extensions/dashboard/pages/<page-name>/
2. WixDesignSystemProvider でラップした WDS コンポーネントを使って page.tsx を作成します
3. extensions.dashboardPage() と一意の UUID を使って extensions.ts を作成します
4. 新しい拡張機能をインポートして使用するように src/extensions.ts を更新します

機能

データ操作（Wix Data SDK）

詳細なドキュメントについては、Wix Data リファレンスを参照してください。

概要：

• 読み取り：items.query('Collection').filter/sort.limit.find() → { items, totalCount, hasNext }
• 書き込み：items.insert | update | remove。コレクションの権限で操作が許可されていることを確認してください

クエリメソッド： eq、ne、gt、ge、lt、le、between、contains、startsWith、endsWith、hasSome、hasAll、isEmpty、isNotEmpty、and、or、not、ascending、descending、limit、skip、include

ダッシュボード API

すべてのメソッド、ページ ID、使用例を含む詳細なドキュメントについては、ダッシュボード API リファレンスを参照してください。

主なメソッド：

• dashboard.navigate() - ダッシュボードページ間を移動します
• dashboard.observeState() - コンテキストに応じた状態と環境情報を受け取ります
• dashboard.showToast() - トースト通知を表示します
• dashboard.openModal() - ダッシュボードのモーダル拡張機能を開きます（wix-cli-dashboard-modalを参照）
• dashboard.navigateBack() - 前のページに戻ります
• dashboard.getPageUrl() - ダッシュボードページの完全な URL を取得します
• dashboard.openMediaManager() - Wix Media Manager を開きます
• dashboard.onBeforeUnload() - beforeunload ハンドラーを登録します
• dashboard.addSitePlugin() - スロットにサイトプラグインを追加します
• dashboard.setPageTitle() - ブラウザーのタブにページタイトルを設定します
• dashboard.onLayerStateChange() - フォアグラウンドとバックグラウンドの状態変更を処理します

重要：ダッシュボードページでのモーダルの使用

ダッシュボードページからポップアップフォーム、確認画面、詳細ビュー、またはダイアログオーバーレイを表示する場合は、通常の React モーダルや WDS の Modal コンポーネントではなく、必ずダッシュボードモーダルを使用してください。

• 編集フォーム、削除確認、詳細ビュー、設定ダイアログなど、あらゆるポップアップコンテンツにはダッシュボードモーダルを使用してください
• WDS の Modal コンポーネントや、独自の React モーダル実装は使用しないでください
• 実装ガイドの詳細については、wix-cli-dashboard-modalを参照してください

ダッシュボードモーダルは dashboard.openModal() で開きます。ダッシュボードのライフサイクル、状態管理、ナビゲーションと適切に連携します。

Ecom ナビゲーション： Ecom 専用のナビゲーションヘルパーについては、Ecom ナビゲーションリファレンスを参照してください。

埋め込みスクリプト設定 API

埋め込みスクリプトを設定するダッシュボードページを作成する場合は、実装ガイドの詳細について動的パラメーターリファレンスを参照してください。

主なポイント：

• @wix/app-management の embeddedScripts を使用します
• パラメーターは文字列として返されるため、読み込み時に型を変換してください
• すべてのパラメーターは文字列として保存する必要があります（ブール値や数値は文字列に変換してください）
• 動的パラメーターがある場合は、withProviders ラッパーを使用してください

ファイルとコードの構成

ダッシュボードページは src/extensions/dashboard/pages の下にあります。各ページには専用のフォルダーがあります。

ファイル構成：

• src/extensions/dashboard/pages/<page>/page.tsx — ページコンポーネント

主なメタデータフィールド：

• id（string、GUID）：ページの登録に使用する一意のページ ID
• title（string）：ブラウザーのタブと、任意のサイドバーラベルに使用されます
• additionalRoutes（string[]、任意）：このページにつながる追加ルート
• sidebar.disabled（boolean、任意）：サイドバーでページを非表示にします（デフォルトは false）
• sidebar.priority（number、任意）：サイドバーの表示順。数値が小さいほど優先度が高くなります
• sidebar.whenActive.selectedPageId（string、任意）：このページがアクティブなときに、選択状態で表示するページ
• sidebar.whenActive.hideSidebar（boolean、任意）：このページがアクティブなときにサイドバーを非表示にします

WDS プロバイダーの使用方法

WDS コンポーネントとテーマを有効にするには、ダッシュボードのページコンポーネントを WixDesignSystemProvider でラップします。また、WDS コンポーネントを正しく表示するため、グローバル CSS スタイルもインポートする必要があります。

import { WixDesignSystemProvider } from "@wix/design-system";
import '@wix/design-system/styles.global.css';

export default function () {
  return (
    <WixDesignSystemProvider>
      <Page>
        <Page.Header
          title="My Page"
          subtitle="This is a subtitle for your page"
        />
        <Page.Content>
          <EmptyState title="My Page" subtitle="Hello World!" theme="page" />
        </Page.Content>
      </Page>
    </WixDesignSystemProvider>
  );
}

注： 動的パラメーターを使用する場合は、代わりに withProviders ラッパーを使用してください。詳しくは、動的パラメーターを参照してください。

厳守すべき制約

• 新しい型、モジュール、関数、プロパティ、イベント、インポートを創作したり、あると仮定したりしないでください。
• 提供されたリファレンスに明示されているエンティティ、またはこのプロジェクトですでに使用されている標準ライブラリのみを使用してください。
• 不足しているものがある場合は、明示的に指摘し、最小限の TODO または明確に示したプレースホルダーを用意してください。独自に作成しないでください。
• 生成するコードでコンポーネントを使用する前に、必ず利用可能であることを確認してください。
• リストにないコンポーネントが必要な場合は、基本的な HTML 要素を使用するか、シンプルなカスタムコンポーネントを作成してください。
• WDS の Modal コンポーネントや独自の React モーダル実装は使用しないでください。ポップアップダイアログ、フォーム、オーバーレイには、必ずダッシュボードモーダルを使用してください（wix-cli-dashboard-modalを参照）。

例

データ管理テーブル

リクエスト：「ブログ投稿を管理するダッシュボードページを作成してください」

出力： 投稿を表示するテーブル、検索ツールバー、追加／編集／削除アクション、空の状態を備えたページ。

設定フォーム

リクエスト：「通知設定用の設定ページを作成してください」

出力： フォームフィールド、トースト通知で確認を表示する保存ボタン、未保存の変更に関する警告を備えたページ。

注文管理

リクエスト：「顧客の注文を管理する管理パネルを作成してください」

出力： 注文テーブル、ステータスバッジ、フィルター、詳細表示用のダッシュボードモーダル（wix-cli-dashboard-modalを使用）、ステータス更新アクションを備えたページ。

埋め込みスクリプトの設定

リクエスト：「クーポンポップアップの埋め込みスクリプト用の設定ページを作成してください」

出力： ポップアップの見出し、クーポンコード、カートの最低金額、有効化切り替え用のフォームフィールドを備えたページ。embeddedScripts API を使ってパラメーターを読み込み／保存します。

// Key pattern for embedded script configuration pages
import { embeddedScripts } from "@wix/app-management";

// Load on mount
useEffect(() => {
  const load = async () => {
    const script = await embeddedScripts.getEmbeddedScript();
    const data = script.parameters || {};
    setOptions({
      headline: data.headline || "Default",
      enabled: data.enabled === "true",
      threshold: Number(data.threshold) || 0,
    });
  };
  load();
}, []);

// Save handler
const handleSave = async () => {
  await embeddedScripts.embedScript({
    parameters: {
      headline: options.headline,
      enabled: String(options.enabled),
      threshold: String(options.threshold),
    },
  });
  dashboard.showToast({ message: "Saved!", type: "success" });
};

拡張機能の登録

拡張機能の登録は必須で、2 つの手順が必要です。

ステップ 1：ページ固有の拡張ファイルを作成する

各ダッシュボードページのフォルダーに extensions.ts ファイルが必要です。

ファイル： src/extensions/dashboard/pages/<page-name>/extensions.ts

import { extensions } from "@wix/astro/builders";

export const dashboardpageMyPage = extensions.dashboardPage({
  id: "{{GENERATE_UUID}}",
  title: "My Page",
  routePath: "my-page",
  component: "./extensions/dashboard/pages/my-page/page.tsx",
});

重要：UUID の生成

id は一意で静的な UUID v4 文字列である必要があります。拡張ごとに新しい UUID を生成してください。randomUUID() を使用したり、例の UUID をコピーしたりしないでください。{{GENERATE_UUID}} を、"a1b2c3d4-e5f6-7890-abcd-ef1234567890" のように新しく生成した UUID に置き換えてください。

プロパティ	型	説明
id	string	一意で静的な UUID v4（上記の注意に従って新しく生成してください）
title	string	ダッシュボードのサイドバーに表示するタイトル
routePath	string	URL パスセグメント。小文字、数字、ハイフン、スラッシュのみ使用できます。スラッシュで始めてはいけません。
component	string	ページコンポーネント（.tsx）への相対パス

ステップ 2：メインの拡張ファイルに登録する

重要： ページ固有の拡張ファイルを作成した後、wix-cli-extension-registration を読み、「App Registration」セクションに従って src/extensions.ts を更新する必要があります。

ステップ 2 を完了しないと、ダッシュボードページは Wix ダッシュボードに表示されません。

よくある間違い - しないでください

他の拡張タイプとの API の混同：

誤り（埋め込みスクリプト API）	正しい（ダッシュボードページ API）
name: "..."	title: "..."
source: "..."	component: "..."
route: "..."	routePath: "..."

埋め込みスクリプトや他の拡張の登録からフィールド名をコピーしないでください。ダッシュボードページでは title、routePath、component を使用します。

コード品質要件

TypeScript 品質ガイドライン

• 生成されたコードは、strict、noImplicitAny、strictNullChecks、exactOptionalPropertyTypes、noUncheckedIndexedAccess の厳格な設定で、TypeScript エラーなしにコンパイルできる必要があります。
• アサーションよりも型の絞り込みと網羅的なロジックを優先してください。非 null アサーション（!）や安全でないキャスト（as any）は避けてください。
• オプショナル値、参照、配列インデックスによる取得結果は undefined の可能性があるものとして扱い、明示的に処理してください。
• ユニオン型には網羅的なチェック（例：never チェックを含む switch）を使用し、すべてのケースで値を返してください（暗黙的に undefined を返さないでください）。
• // @ts-ignore や // @ts-expect-error は使用しないでください。代わりに型を修正するか、ガードを追加してください。

基本原則

• 新しい型、モジュール、関数、props、イベント、インポートを作り出したり、あるものと仮定したりしないでください。
• コード内でモック、プレースホルダー、TODO を絶対に使用しないでください。
• 常に完全で本番環境に対応できる機能を実装してください。
• Wix ダッシュボードページのパターンとベストプラクティスに正確に従ってください。
• あらゆるエッジケースとエラー状況を適切に処理してください。

コード品質基準

• 適切な型付けを行った TypeScript を優先してください。
• 一貫した命名規則を使用してください。
• 適切な箇所にエラー処理を含めてください。
• 複雑なロジックや自明でないロジックにはドキュメントを追加してください。
• 非同期処理には async/await を優先してください。
• 効果がある場合は、コードを簡潔にするために分割代入を検討してください。
• 適切に構造化されたレスポンスオブジェクトを返してください。

エラー処理

• ダッシュボードページでは必ず適切なエラー処理を実装してください。
• データが無効な場合は、適切なエラーレスポンスを返してください。
• デバッグに役立つよう、console.error を使用してエラーを適切に記録してください。
• ネットワークタイムアウトや外部サービスの障害を処理してください。

出力の制約

トークン制限： 最大出力は約10,000トークンです。この制限を十分に下回るように、回答を計画してください。

• 大きなファイル（300行超）を作成する場合は、インポートを使用して複数の小さなファイルに分割してください。
• 大きなセクション（100行超）を編集する場合は、複数の小さな編集操作に分けてください。
• 回答前に出力を数えてください。長すぎると思われる場合は、範囲を絞り、優先順位を付けてください。

簡潔さのルール： 品質と正確性を保ちながら、出力トークンを最小限に抑えてください。

• 明示的に依頼されていない限り、README.md、ドキュメントファイル、Markdown ファイルを追加しないでください。
• コードに過剰なコメントを追加しないでください。明確さのために本当に必要な場合にのみコメントを追加してください。
• 変更されていないファイルや既存のコードを重複して再出力しないでください。
• 「// TODO: implement」のようなプレースホルダーコードを生成しないでください。動作する実装を提供してください。
• タスクに直接必要なファイルのみを出力してください。

モジュール化されたコードの方針： 大規模なコードを生成する場合は、インポートを使って複数の小さなファイルに分割してください。

• ユーティリティ／ヘルパーを別ファイルに切り出す
• 型／インターフェースを専用の型ファイルに分ける
• 各コンポーネント／関数の役割を絞る（最大約50～100行）

API 仕様のサポート

API 仕様が提供されている場合は、そのエンドポイントに API コールを実行できます。ダッシュボードページで API 仕様を使用する方法については、API Spec Reference を参照してください。

---

レイアウトのガイドライン

レイアウトは、ユーザーがダッシュボードのコンテンツをどのように操作するかを決定します。ダッシュボードページの構造、階層、リズムを定め、全体の一貫性とユーザー体験を形作ります。コンテンツを整理する際に、意識的かつ熟慮した選択をすることで、ユーザーはよりスムーズに画面内を移動でき、タスクの完了にかかる時間やストレスを減らせます。

デザイン原則

ユーザー体験を最適化したダッシュボードページを作成するには、次のデザイン原則に従ってください。

1. 一貫性： 繰り返し使われるレイアウトやコンテンツのパターンを維持し、直感的で読みやすいページにします。
2. 包括性： さまざまな画面サイズに適切に対応するレイアウトとコンテンツを作成します。
3. バランス： サイズと余白を意図的に調整し、領域やコンテンツ要素の優先度を明確にします。
4. 関連性： 関連する領域やコンテンツ要素の間隔を最小限に抑え、一体感と操作性を高めます。

---

画面サイズ

ダッシュボードページは、特定の解像度に合わせて作るのではなく、さまざまな画面サイズに対応するよう設計します。ユーザーがページの目的をすぐに理解できるよう、主要なコンテンツはページの上部に配置してください。

注： ページ上部の600ピクセル以内に表示されたコンテンツは、大多数のユーザーの画面に表示されます。

---

基本単位

基本単位は、すべての要素や寸法に乗算して使用する間隔を定めます。この方法により、デザイン要素の間隔やサイズに一貫性を持たせられます。

注： デザインシステムは6pxを単位としています。

レイアウトグリッド、スペーシングトークン、およびほぼすべての視覚要素とサイズは、6の倍数（6、12、18、24など）に従います。ただし、一部例外があります。

トークン	サイズ	用途
SP1	6px	コンポーネント間のスペーシング
SP2	12px	コンポーネント間のスペーシング
SP3	18px	コンポーネント間のスペーシング
SP4	24px	コンポーネント間のスペーシング、レイアウトのスペーシング
SP5	30px	レイアウトのスペーシング
SP6	36px	レイアウトのスペーシング
SP7	42px	レイアウトのスペーシング
SP8	48px	レイアウトのスペーシング
SP10	54px	レイアウトのスペーシング
SP11	60px	レイアウトのスペーシング

---

レイアウト構造

アプリに最適なレイアウトを設計するには、次の内容を理解してください。

1. アプリの基本的なフレーム（アプリケーションフレーム）
2. グリッドレイアウト内での各セグメントの配置と整列（グリッドレイアウト）
3. グリッドに表示するコンテンツ（一般的なレイアウト）

アプリケーションフレーム

ダッシュボードのアプリケーションフレームは、ほとんどの Wix アプリケーション設定で使用されています。ダッシュボードページは、次の4つの領域で構成されます。

領域	用途
1. グローバルナビゲーション（トップバー）	ページ上部にある全般的なナビゲーションで、ユーザーは異なる環境間を移動できます。ページ幅全体に広がるコンテナーで、高さは48pxに固定されています。
2. サイドバーナビゲーション	環境内のローカルナビゲーションです。幅228pxに固定されたコンテナーです。
3. コンテンツ領域	画面サイズに応じて幅が変化するページコンテンツ領域です。
4. サイドパネル（任意）	ページのコンテンツに関連する追加のアクションやコンテンツを表示する任意のパネルです。幅は420pxに固定されています。メインコンテンツ領域に重ねるか、右側からメインコンテンツを押し出すことができます。

サイドパネルのガイドライン：

• データフィルターなど、補足的なアクションや設定を表示する場合は、サイドパネルをメインコンテンツに重ねます
• 続行するためにユーザーが全体のコンテキストを確認する必要がある場合は、サイドパネルでメインコンテンツを押し出します

---

グリッドレイアウト

このシステムでは、最大幅が固定されたフルードグリッドレイアウトを使用します。画面幅に応じてコンテンツを拡大・縮小する列で構成されています。

グリッドは、次の3つの要素で構成されます。

• 列 - デザインシステムでは12列のグリッドを使用します。列幅はフルードで、ページ幅に応じて変わります。
• ガター - 列間の間隔です。ガター幅は24pxに固定されています。
• マージン - デフォルトでは、ページのコンテンツ領域の左右に48px、下部に48pxのマージンがあります。

グリッドの仕様：

• コンテンツ領域の最小幅：864ピクセル（グリッドの各列の幅は50px）
• コンテンツ領域の最大幅：1248px（各列の幅は82px）
• 幅の広い画面では、コンテンツ幅を1248pxに保ち、コンテンツを中央に配置するために左右のマージンを広げます
• カード間には、縦横ともに24pxの間隔を設けます

---

一般的なレイアウト

ページレイアウトは、目的に応じて次の種類に分けられます。

1. フォームレイアウト

フォームは、ユーザーがデータを入力したり、既存のデータを編集したりするページです。次の2種類があります。

• 2/3レイアウト（任意のサイドバー付き、8/4列分割） - 主要コンテンツと副次コンテンツを同時に表示する柔軟なレイアウトです
• 全幅（12列） - 複雑な構造を持つ高度なプロダクト要件に対応します

どちらのフォームページレイアウトでも、ヘッダーとフッターの領域に必須の保存アクションとキャンセルアクションを含めます。

2/3レイアウトのベストプラクティス：

• 主要コンテンツと副次コンテンツを同時に表示する場合に使用します
• フォームをスキャンしやすく、理解しやすい状態に保ちます
• 横にコンテンツのライブプレビューを表示します（ウィジェットは固定表示できます）
• すばやく読めるように、テキスト行と入力フィールドの幅を狭く保つため、フォームには8列を使用します
• アクションを関連するタイトルの近くに配置します（例：設定の近くにトグルスイッチを配置する）

全幅レイアウトのベストプラクティス：

• テーブルなど、複雑な構造を含むフォームで使用します
• データ列が多いリスト項目で使用します

レイアウトの組み合わせ：

• 画面の端から端まで広がる入力欄は避け、入力欄の幅をカードの2/3にするか、2列に配置します
• コンテンツのプレビューには右側の余白を使用します
• 列数が多いテーブルや、セクションを区切るディバイダーには全幅を使用します

注： 1行あたり平均10語を収められる幅があれば、列の内容は読みやすくなります。

2. 表示レイアウト

表示ページでは、ユーザーからの入力を受け付けずにデータやコンテンツを表示します。データのフィルタリングなど、簡単な操作を含めることができます。

リスト（テーブル）：

• テーブルでは大規模なデータセットを表示し、ユーザーがすばやく概要を把握できるようにします
• テーブルには12カラムのレイアウトを使用します
• ユーザーがデータセットを操作したり、それに対するアクションを実行したりできます

リスト（グリッド）のオプション：

• 2カラム（6/6の分割）- 説明が長い項目向け
• 3カラム（4/4/4の分割）- 複数のデータ型を含むビジュアル要素向け
• 4カラム（3/3/3/3の分割）- ユーザー作成のギャラリーやコレクション向け。4/4/4よりも、スクロールせずに見える範囲に最大50％多くのコンテンツを表示できます
• カスタム - 異なる種類のコンテンツが混在する場合向け

グリッドの選択時に考慮する点：

• 表示する項目の合計数
• 各リスト項目に表示するコンテンツ
• リスト項目が表すオブジェクト（該当する場合は、物理的な形状に合わせます）

ダッシュボード： コンビネーショングリッドを使用して、特定のトピックに関するさまざまな種類のデータを表示します。

カラム幅の推奨：

• 3または4カラム - リスト項目、プレビュー、マーケティング、統計、チャート向け
• 12カラム（全幅） - テーブルやマーケティングコンテンツ向け
• 8カラム - リスト、データ列が少ないテーブル、セットアップウィザード、チャート向け
• 6カラム - リスト、データ列が少ないテーブル、統計向け

空の状態：

• ページの空の状態には全幅レイアウトを使用します
• 機能や製品にまだデータがない、すべてのデータが消去されている、またはまだセットアップされていないことを示します
• ページにデータを入力するために何をすればよいかを示す、明確なCTAを含めます
• タブ、統計ウィジェット、マーケティングカードなど、ほかのレイアウト要素と組み合わせることができます

3. マーケティングレイアウト

マーケティングページでは、サイトの所有者がまだ知らない新製品を紹介します。<MarketingPageLayout/>コンポーネントを使い、2カラムに分けて構成します。

1. プロモーションメッセージ
2. 製品と機能のビジュアル表現

フッター領域には、機能やお客様の声のリストを任意で表示できます。

4. ウィザードレイアウト

ウィザードページでは、製品や機能のセットアップをユーザーに案内します。複雑なフォームを複数のステップに分けることで、より簡単に完了できるようにします。

開始ポイント：

• マーケティングページ
• マーケティングカード
• ページの主要なアクション
• 空の状態

注： ウィザードには最終的な遷移先が必要です。すべてのステップを完了した後、ユーザーはダッシュボード、詳細ページ、その他の関連する場所に移動する必要があります。

---

関連するWDSコンポーネント

• <Page /> - メインページのラッパー
• <Layout /> - グリッドレイアウトのコンテナ
• <MarketingPageLayout /> - マーケティングページのラッパー
• <Card /> - カード間に24pxの間隔を設けるコンテンツコンテナ