Header | ArcBlock

Header コンポーネントは、Blocklet アプリケーション向けにレスポンシブでカスタマイズ可能なヘッダーを提供します。Blocklet の設定 (blocklet.yml) から直接メタデータを読み取ることで、ナビゲーションリンク、アプリケーションのロゴ、およびユーザーセッションコントロールを自動的に設定します。このコンポーネントは、最小限の設定で一貫性のある機能豊富なヘッダーを作成するように設計されています。

概要

Header コンポーネントは、主要なナビゲーションおよびブランディング要素として機能します。これは @arcblock/ux のコンポーネント、ResponsiveHeader および NavMenu の上に構築されており、ユーザー認証のために DID Connect セッションコンテキストとシームレスに統合されます。

主な機能は次のとおりです。

自動設定: blocklet.yml からアプリのロゴ、タイトル、ナビゲーションリンクを設定します。
レスポンシブデザイン: さまざまな画面サイズに自動的に適応し、モバイルフレンドリーなナビゲーションメニューを提供します。
セッション管理: DID Connect と統合し、ユーザー情報、プロフィールメニュー、ログイン/ログアウトボタンを表示します。
カスタマイズ可能なアドオン: カスタムコンポーネントの挿入や、テーマ切り替え、ロケールセレクターなどのデフォルト要素の変更を可能にします。
組織切り替え: Blocklet が組織サポートを有効にしている場合、自動的に組織スイッチャーを含みます。
ドメイン警告: より良いセキュリティのためにカスタムドメインの設定を推奨するため、管理者が一時的なドメイン経由でアプリケーションにアクセスした場合に通知します。

仕組み

以下の図は、Header のデータフローとコンポーネント構成を示しています。blocklet.yml ファイルから設定を読み込み、それを処理して、ロゴ、ナビゲーションリンク、ユーザーセッションコントロールなど、適切な UI 要素をレンダリングします。

Header

基本的な使用法

Header を使用するには、インポートしてアプリケーションのレイアウトに配置します。Blocklet のメタデータが必要で、これは通常 window.blocklet を介してグローバルに利用可能です。

"App.js"

import Header from '@blocklet/ui-react/lib/Header';

function App() {
  // meta オブジェクトは通常 window.blocklet から取得されます
  const blockletMeta = window.blocklet || {};

  return (
    <div>
      <Header meta={blockletMeta} />
      <main>
        {/* アプリケーションのコンテンツ */}
      </main>
    </div>
  );
}

export default App;

プロパティ

Header コンポーネントは、カスタマイズのためにいくつかのプロパティを受け入れます。

meta BlockletMetaProps — Blocklet のメタデータオブジェクト、通常は window.blocklet から取得します。これには、コンポーネントがレンダリングに使用する name、logo、navigation などの情報が含まれています。
addons Function | React.ReactNode — ヘッダーの右側に追加されるカスタム要素。関数が提供された場合、組み込みのアドオンを引数として受け取り、それらを変更、並べ替え、または補足できます。ノードが提供された場合、すべての組み込みアドオンを置き換えます。
sessionManagerProps SessionManagerProps (default: { "showRole": true }) — 基盤となる SessionUser コンポーネントに直接渡されるプロパティで、ユーザーのロールの表示など、ユーザーセッション情報の表示を制御します。
homeLink string | Function (default: publicPath) — ホームリンクの URL で、通常はロゴまたはブランド名をクリックするとトリガーされます。デフォルトは Blocklet の公開パス (/) です。JSX 要素を返す関数にすることもできます。
theme object — デフォルトのテーマとマージするための Material-UI のテーマオブジェクトで、色、タイポグラフィ、その他のスタイルを詳細にカスタマイズできます。
hideNavMenu boolean (default: false) — true の場合、blocklet.yml から生成されたナビゲーションメニューは、ナビゲーションデータが存在しても非表示になります。
bordered boolean (default: false) — true の場合、視覚的な区分のためにヘッダーに下枠が適用されます。
logo React.ReactNode — Blocklet のメタデータから取得したロゴを上書きするためのカスタムロゴ要素。
brand React.ReactNode — ロゴの隣に表示するカスタムブランド要素 (例: テキストや画像)。
showDomainWarningDialog boolean (default: true) — false の場合、一時的なドメインに関する警告ダイアログは表示されません。

機能

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

Header は、blocklet.yml ファイルの navigation 配列からナビゲーションメニューを自動的に生成します。コンポーネントはこの設定を解析して、プライマリナビゲーションリンクとネストされたドロップダウンメニューを作成します。

以下は、blocklet.yml 内の navigation 設定の例です。

"blocklet.yml"

navigation:
  - title: Features
    link: /features
    icon: 'mdi:star'
  - title: Docs
    link: /docs
    icon: 'mdi:book-open'
  - title: More
    items:
      - title: About Us
        link: /about
        description: Learn more about our mission.
      - title: Community
        link: https://community.example.com
        description: Join our community forum.

parseNavigation ユーティリティはこの構造を処理し、title と description のローカライゼーションを処理し、現在の URL パスに基づいてアクティブなリンクを決定します。

セッション管理とアドオン

ヘッダーの右側には「アドオン」が含まれています。これらはセッション管理とアプリケーション設定のためのコントロールのコレクションです。デフォルトでは、これらには以下が含まれます。

組織スイッチャー: Blocklet が組織サポートを有効にしている場合に表示されます。
通知センター: Blocklet が通知ページを含んでいる場合に表示されます。
ロケールセレクター: 複数の言語が設定されている場合に表示されます。
テーマモード切り替え: ライトモードとダークモードを切り替えます。
セッションコントロール: ログインしているユーザーのアバターと、プロフィール、設定、ログアウトへのリンクを持つメニューを表示します。ゲストには、「ウォレットに接続」ボタンが表示されます。

アドオンのカスタマイズ

addons プロパティを使用してこれらのアドオンをカスタマイズできます。

例: カスタムボタンの追加

addons プロパティに関数を指定します。この関数はデフォルトのアドオン要素の配列を受け取り、独自のアドオンを追加できます。

"HeaderWithCustomAddon.js"

import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button';

function HeaderWithCustomAddon() {
  return (
    <Header
      meta={window.blocklet}
      addons={(builtInAddons) => (
        <>
          {builtInAddons}
          <Button variant="contained" color="primary" sx={{ ml: 1 }}>
            Upgrade
          </Button>
        </>
      )}
    />
  );
}

例: すべてのアドオンの置き換え

React ノードまたはノードの配列を提供して、デフォルトのアドオンを完全に置き換えます。

"HeaderWithReplacedAddons.js"

import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button';

function HeaderWithReplacedAddons() {
  return (
    <Header
      meta={window.blocklet}
      addons={[
        <Button key="feedback" variant="outlined" sx={{ ml: 1 }}>
          Feedback
        </Button>,
      ]}
    />
  );
}

埋め込みモードでの非表示

Header は withHideWhenEmbed 高階コンポーネントでラップされています。アプリケーションが埋め込みコンテキストでレンダリングされる場合 (例: sessionStorage に EMBED_MODE_KEY: 1 が含まれる iframe 内)、自動的に非表示になります。これは、Blocklet が別のアプリケーションに統合された際に、よりクリーンな UI を提供するのに役立ちます。

まとめ

Header コンポーネントは、Blocklet アプリケーション全体で一貫したブランディングとナビゲーションを確立するための強力なツールです。Blocklet のメタデータを活用することで、開発を簡素化し、プロパティを通じて広範なカスタマイズを提供します。

関連するレイアウトコンポーネントについては、Footer のドキュメントを参照してください。