メインコンテンツへスキップ

Dashboard

Dashboard コンポーネントは、blocklet アプリケーション向けに、レスポンシブなレイアウトを事前に構築して提供します。これは通常、管理インターフェースやユーザー中心のビューに使用されます。blocklet のメタデータを解釈することで、サイドバー、ヘッダー、およびメインコンテンツエリアを持つ標準的なダッシュボードを自動的に構築します。このコンポーネントにより、一般的なアプリケーション構造を構築するための定型的なコードが大幅に削減されます。

レイアウトは、ナビゲーション用の永続的なサイドバー、グローバルなアクションとユーザー情報用のヘッダー、そしてページ固有のコンテンツがレンダリングされるメインコンテンツエリアの3つの主要なセクションで構成されています。

Dashboard

基本的な使用方法

Dashboard コンポーネントを使用するには、ページのコンテンツをそれでラップするだけです。コンポーネントは自動的にコンテンツの周りにヘッダーとサイドバーをレンダリングします。

MyDashboard.jsx

javascript
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';

export default function MyDashboardPage() {
  return (
    <Dashboard>
      <h1>Welcome to the Dashboard</h1>
      <p>This is your main content area.</p>
    </Dashboard>
  );
}

Dashboard コンポーネントに渡された children は、メインコンテンツエリアに表示されます。

Props

Dashboard コンポーネントは、その動作と外観をカスタマイズするために、以下の props を受け入れます。

  • children React.ReactNode (required) — ダッシュボードレイアウトのメインコンテンツエリア内にレンダリングされるコンテンツ。
  • meta object — blocklet メタデータオブジェクト。指定された場合、デフォルトの window.blocklet メタデータとマージされ、上書きされます。これは、テストや blocklet 情報を動的に変更する場合に便利です。
  • fallbackUrl string (default: publicPath) — 現在の認証済みユーザーがその役割に基づいてどのナビゲーションリンクにもアクセスできない場合にリダイレクトする URL。この自動リダイレクトを無効にするには null に設定します。
  • invalidPathFallback function — 現在の URL パスが利用可能なナビゲーションリンクのいずれとも一致しない場合に実行されるコールバック関数。デフォルトの動作は、利用可能な最初のリンクにリダイレクトすることです。
  • headerAddons React.ReactNode | function — ヘッダーの右側のアドオンのカスタマイズを可能にします。ノードが提供された場合、すべてのデフォルトアドオンを置き換えます。関数が提供された場合、デフォルトのアドオン配列を引数として受け取り、それらを追加、削除、または並べ替えることができます。
  • sessionManagerProps object — ヘッダー内の基盤となる SessionUser コンポーネントに直接渡される Props。これにより、showRole やカスタムの onLogout ハンドラの定義など、ユーザーセッションメニューのカスタマイズが可能になります。
  • links array | function — サイドバーのナビゲーションリンクをプログラムで変更できるようにします。配列が提供された場合、そのアイテムはメタデータから生成されたリンクに追加されます。関数が提供された場合、メタデータから生成されたリンクを引数として受け取り、新しいリンクの配列を返す必要があります。
  • showDomainWarningDialog boolean (default: true) — true の場合、信頼できないドメインからアプリケーションにアクセスされた場合に警告ダイアログを表示します。

仕組み

Dashboard コンポーネントは、「設定駆動型」で設計されており、その構造とコンテンツは主に blocklet のメタデータファイル (blocklet.yml) から派生します。

メタデータからのナビゲーション

サイドバーのナビゲーションは、blocklet.yml の navigation 配列から自動的に生成されます。コンポーネントは、section プロパティに dashboard を含むナビゲーション項目を具体的に探します。

以下は、ダッシュボードナビゲーションを定義する方法の例です。

blocklet.yml

yaml
navigation:
  - title: 'Home'
    link: '/'
    section: 'dashboard'
    icon: 'mdi:home'
    role: ['owner', 'admin', 'guest']
  - title: 'Analytics'
    link: '/analytics'
    section: 'dashboard'
    icon: 'mdi:chart-bar'
    role: ['owner', 'admin']
  - title: 'Settings'
    link: '/settings'
    section: 'dashboard'
    icon: 'mdi:cog'
    role: ['owner']
    items:
      - title: 'Profile'
        link: '/settings/profile'
      - title: 'Billing'
        link: '/settings/billing'

ロールベースのアクセス制御

Dashboard コンポーネントは、ナビゲーションリンクに対してロールベースのアクセス制御 (RBAC) を強制します。各ナビゲーション項目は role プロパティを持つことができ、これはリンクを見ることが許可されているロールの配列です。

  • ナビゲーション項目に role プロパティがない場合、それは誰にでも表示されます。
  • 現在のユーザーが認証されていない場合、guest ロールを含む項目のみを見ることができます。
  • 現在のユーザーが認証されている場合、コンポーネントは彼らの user.role を各ナビゲーション項目の role 配列と比較します。一致がある場合にのみ項目が表示されます。
  • 親ナビゲーション項目は、その子の少なくとも1つが表示される場合にのみ表示されます。

上記の blocklet.yml の例を使用すると：

  • guest ロールのユーザーは「Home」リンクのみを見ることができます。
  • admin ロールのユーザーは「Home」と「Analytics」を見ることができます。
  • owner ロールのユーザーは、「Settings」の下にあるネストされた「Profile」と「Billing」リンクを含むすべてのリンクを見ることができます。

アイコン

ナビゲーション項目の icon プロパティは、Iconify ライブラリのアイコン名に対応する文字列（例：mdi:home）である必要があります。画像ファイルへの完全な URL を提供することもできます。

カスタマイズ

Dashboard はメタデータですぐに使えるように設計されていますが、より高度なカスタマイズのためのいくつかの props を提供しています。

ヘッダーアドオンのカスタマイズ

headerAddons prop を使用して、デフォルトのヘッダーアドオン（例：テーマ切り替え、ロケールセレクター、セッションマネージャー）を変更できます。関数を渡すことで、新しい要素を追加したり、既存の要素を並べ替えたりすることができます。

CustomHeader.jsx

javascript
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
import Button from '@mui/material/Button';

function MyCustomButton() {
  return <Button color="inherit" onClick={() => alert('Help!')}>Help</Button>;
}

export default function CustomDashboard() {
  return (
    <Dashboard
      headerAddons={(existingAddons) => {
        const customAddon = <MyCustomButton key="custom-help" />;
        // Add the custom button before the other addons
        return [customAddon, ...existingAddons];
      }}
    >
      <p>Dashboard with a custom header button.</p>
    </Dashboard>
  );
}

リンクのプログラムによる追加

links prop を使用すると、コードから動的にサイドバーのナビゲーションリンクを追加または変更できます。これは、アプリケーションの状態に依存するリンクに便利です。

DynamicLinks.jsx

javascript
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
import Icon from '@arcblock/ux/lib/Icon';

const useFeatureFlag = () => {
  // 実際のアプリでは、ここでフィーチャーフラグサービスをチェックします
  return true;
};

export default function DynamicDashboard() {
  const isBetaFeatureEnabled = useFeatureFlag();

  return (
    <Dashboard
      links={(existingLinks) => {
        if (isBetaFeatureEnabled) {
          const betaLink = {
            id: 'beta-feature',
            title: 'Beta Feature',
            url: '/beta',
            icon: <Icon name="mdi:test-tube" />,
            external: true, // クライアントサイドのルーティングに必要
          };
          return [...existingLinks, betaLink];
        }
        return existingLinks;
      }}
    >
      <p>This dashboard may have dynamic links.</p>
    </Dashboard>
  );
}

まとめ

Dashboard コンポーネントは、アプリケーションのレイアウトを迅速に構築するための強力なツールです。blocklet メタデータを活用することで、構造化され、ロールを認識するナビゲーションシステムをすぐに提供します。より基本的なレイアウトコンポーネントについては、Header と Footer のドキュメントを参照してください。