@blocklet/ui-react/docs/components-layout-header.zh-TW.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.zh-TW.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) 的文件。