@blocklet/ui-react/docs/components-layout-header.ja.md

Some useful front-end web components that can be used in Blocklets.

# Header

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

## 概要

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

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

### 仕組み

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

<!-- DIAGRAM_IMAGE_START:architecture:16:9:1765962229 -->
![Header](assets/diagram/header-diagram-0.ja.jpg)
<!-- DIAGRAM_IMAGE_END -->

## 基本的な使用法

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

```javascript "App.js" icon=logos:javascript
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` コンポーネントは、カスタマイズのためにいくつかのプロパティを受け入れます。

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

## 機能

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

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

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

```yaml "blocklet.yml" icon=mdi:code-braces
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` プロパティに関数を指定します。この関数はデフォルトのアドオン要素の配列を受け取り、独自のアドオンを追加できます。

```javascript "HeaderWithCustomAddon.js" icon=logos:javascript
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 ノードまたはノードの配列を提供して、デフォルトのアドオンを完全に置き換えます。

```javascript "HeaderWithReplacedAddons.js" icon=logos:javascript
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](./components-layout-footer.md) のドキュメントを参照してください。