跳到主要内容

Header

Header 组件为 Blocklet 应用提供了一个响应式且可定制的页眉。它通过直接从 blocklet 的配置（blocklet.yml）中读取元数据，自动填充导航链接、应用 logo 和用户会话控件。该组件旨在以最少的配置创建一个功能丰富且一致的页眉。

Header 组件为 Blocklet 应用提供了一个响应式且可定制的页眉。它通过直接从 blocklet 的配置（blocklet.yml）中读取元数据，自动填充导航链接、应用 logo 和用户会话控件。该组件旨在以最少的配置创建一个功能丰富且一致的页眉。

概述

Header 组件是主要的导航和品牌元素。它构建于 @arcblock/ux 组件之上，包括 ResponsiveHeader 和 NavMenu，并与用于用户身份验证的 DID Connect 会话上下文无缝集成。

主要功能包括：

  • 自动配置：从 blocklet.yml 中填充应用 logo、标题和导航链接。
  • 响应式设计：自动适应不同的屏幕尺寸，提供移动设备友好的导航菜单。
  • 会话管理：与 DID Connect 集成，以显示用户信息、个人资料菜单以及登录/登出按钮。
  • 可定制的插件：允许注入自定义组件或修改默认元素，如主题切换器和语言选择器。
  • 组织切换：如果 blocklet 启用了组织支持，则自动包含一个组织切换器。
  • 域名警告：当管理员和用户通过临时域名访问应用时，通知他们配置自定义域名以提高安全性。

工作原理

下图说明了 Header 的数据流和组件构成。它从 blocklet.yml 文件中读取配置，进行处理，并渲染相应的 UI 元素，包括 logo、导航链接和用户会话控件。

Header

基本用法

要使用 Header，请将其导入并放置在应用的布局中。它需要 blocklet 的元数据，该元数据通常通过 window.blocklet 全局可用。

"App.js"

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;

Props

Header 组件接受多个 props 以进行自定义。

  • meta BlockletMetaProps
  • addons Function | React.ReactNode
  • sessionManagerProps SessionManagerProps (default: { "showRole": true })
  • homeLink string | Function (default: publicPath)
  • theme object
  • hideNavMenu boolean (default: false)
  • bordered boolean (default: false)
  • logo React.ReactNode
  • brand React.ReactNode
  • showDomainWarningDialog boolean (default: true)

功能

从元数据自动生成导航

Header 会根据 blocklet.yml 文件中的 navigation 数组自动生成其导航菜单。该组件解析此配置以创建主导航链接和嵌套的下拉菜单。

以下是 blocklet.yml 中 navigation 配置的示例：

"blocklet.yml"

yaml
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 prop 来自定义这些插件。

示例：追加一个自定义按钮

向 addons prop 提供一个函数。此函数接收一个包含默认插件元素的数组，允许您添加自己的元素。

"HeaderWithCustomAddon.js"

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 节点或节点数组来完全替换默认插件。

"HeaderWithReplacedAddons.js"

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 元数据，它简化了开发过程，同时通过 props 提供了广泛的自定义选项。

有关相关的布局组件，请参阅 Footer 的文档。