marketplace-build-component

Blok デザインシステムで UI を構築する

Blok デザインシステム（Sitecore の shadcn ベースのコンポーネントライブラリ）を使用して、Sitecore Marketplace アプリの UI コンポーネントを構築できるよう、ユーザーをサポートします。

主な原則

1. 常に Blok コンポーネントを使用する — Sitecore ホスト UI と一致し、ライトテーマ／ダークテーマを自動的にサポートします
2. SDK データの統合 — SDK データを取得するときは、ローディング状態（Skeleton）とエラー状態（Alert）を使用します
3. 拡張ポイントを意識する — 拡張機能の種類ごとに UI の制約が異なります（以下を参照）
4. レスポンシブ — コンポーネントは、サイズがさまざまな iframe 内にレンダリングされます

コンポーネントのインストール

Blok コンポーネントは shadcn CLI からインストールします。

# Install the Blok theme (required first)
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/blok-theme.json

# Install individual components
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/<component-name>.json

インストールコマンドを含むコンポーネントの完全なカタログについては、blok-components.md を参照してください。

拡張機能の種類別 UI パターン

コンパクトフィールド（custom-field）

• 使用できるスペースが非常に限られています（幅は約 300px、高さは可変）
• 使用するもの：Input、Select、Badge、小さなインラインコンポーネント
• 避けるもの：テーブル、大きなレイアウト、モーダル

ダッシュボードウィジェット

• 中程度のスペースです（デフォルトで約 400x300px、サイズ変更可能）
• 使用するもの：Card、Chart、Stats、コンパクトな Table
• 適した用途：概要データ、簡単なアクション

Pages のコンテキストパネル

• サイドパネルです（幅約 350px、高さは画面全体）
• 使用するもの：縦方向のレイアウト、List、Accordion、Tabs
• 適した用途：現在のページに関するコンテキスト情報やアクション

フルスクリーン

• Sitecore シェル内のビューポート全体を使用します
• 使用するもの：あらゆるコンポーネント、複雑なレイアウト、Table、Form
• 適した用途：完全な CRUD インターフェース、ダッシュボード、設定

スタンドアロン

• Sitecore シェル外の独立したページです
• 使用するもの：あらゆるコンポーネント、自由なクリエイティブ表現
• 適した用途：一般公開向けのページ、OAuth コールバック

SDK データ統合パターン

"use client";

import { useEffect, useState } from "react";
import { useMarketplaceClient, useAppContext } from "@/components/providers/marketplace";
import { Skeleton } from "@/components/ui/skeleton";
import { Alert, AlertDescription } from "@/components/ui/alert";

export function MyComponent() {
  const { client } = useMarketplaceClient();
  const appContext = useAppContext();
  const [error, setError] = useState<string | null>(null);

  const loading = !appContext;

  if (loading) return <Skeleton className="h-32 w-full" />;
  if (error) return <Alert variant="destructive"><AlertDescription>{error}</AlertDescription></Alert>;

  return <div>{/* Render data */}</div>;
}

リファレンスファイル

• Blok コンポーネント — インストールコマンドを含むコンポーネントの完全なカタログ