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 的文件。