@blocklet/ui-react/docs/core-concepts.zh.md

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

# 核心概念

本文档解释了 Blocklet UI React 库的基本原则。其核心设计理念是**元数据驱动方法**，即 `Header`、`Footer` 和 `Dashboard` 等 UI 组件会根据 blocklet 的元数据自动配置和渲染。这种策略确保了一致性，减少了样板代码，并实现了能适应用户角色和语言偏好的动态 UI。

其中心思想是，单个配置文件（通常是 `blocklet.yml`）作为应用程序整体结构和外观的单一事实来源。该库读取、处理此元数据，并用其构建相应的 UI 元素。

## 元数据驱动原则

该库的运作可以看作一个简单的数据流：blocklet 元数据作为输入提供给库，库通过一个管道处理它，最终生成完全渲染的 UI 组件。这免去了开发者为每个应用程序手动构建和配置通用布局元素的需求。

<!-- DIAGRAM_IMAGE_START:flowchart:16:9:1765962229 -->
![Core Concepts](assets/diagram/core-concepts-diagram-0.zh.jpg)
<!-- DIAGRAM_IMAGE_END -->

这个自动化过程依赖于一个明确定义的元数据结构，下一节将详细介绍。

## Blocklet 元数据剖析

该库期望一个特定的对象结构，称为 `BlockletMetaProps`，其中包含渲染 UI 所需的所有信息。以下是该结构的详细分解。

<x-field-group>
  <x-field data-name="appName" data-type="string" data-required="false" data-desc="应用程序的名称，通常显示在 Header 中。"></x-field>
  <x-field data-name="appLogo" data-type="React.ReactNode" data-required="false" data-desc="用于应用程序徽标的 React 节点，也显示在 Header 中。"></x-field>
  <x-field data-name="enableConnect" data-type="boolean" data-required="false" data-desc="决定是否显示 DID Connect 按钮。"></x-field>
  <x-field data-name="enableLocale" data-type="boolean" data-required="false" data-desc="决定是否显示语言选择组件。"></x-field>
  <x-field data-name="theme" data-type="object" data-required="false">
    <x-field-desc markdown>定义应用程序布局的配色方案。</x-field-desc>
    <x-field data-name="background" data-type="string" data-required="false" data-desc="为 Header 和 Footer 等布局组件设置背景颜色。"></x-field>
  </x-field>
  <x-field data-name="navigation" data-type="array" data-required="false">
    <x-field-desc markdown>一个由导航项对象组成的数组，用于定义整个应用程序中的链接和菜单。</x-field-desc>
    <x-field data-name="title" data-type="string | object" data-required="true" data-desc="导航项的显示文本。可以是用于 i18n 的对象。"></x-field>
    <x-field data-name="link" data-type="string | object" data-required="false" data-desc="导航项的 URL。可以是用于 i18n 的对象。"></x-field>
    <x-field data-name="icon" data-type="string" data-required="false" data-desc="一个与 Iconify 兼容的字符串，用于在标题旁边显示图标。"></x-field>
    <x-field data-name="section" data-type="string | array" data-required="false" data-desc="指定该项应出现的位置，例如 'header'、'footer'、'dashboard'。"></x-field>
    <x-field data-name="role" data-type="string | array" data-required="false" data-desc="定义哪些用户角色可以看到此项，例如 'admin'、'guest'。"></x-field>
    <x-field data-name="items" data-type="array" data-required="false" data-desc="一个嵌套导航项的数组，用于创建下拉菜单或子菜单。"></x-field>
  </x-field>
</x-field-group>

### 导航配置示例

`navigation` 数组是元数据中最关键的部分。它提供了一种结构化的方式来定义所有链接、菜单及其位置。

```yaml blocklet.yml 中的导航配置 icon=mdi:code-braces
# blocklet.yml
navigation:
  - title: Features
    link: /features
  - title:
      en: About Us
      zh: 关于我们
    link:
      en: /about
      zh: /about-us
    section: footer
  - title: Admin Dashboard
    link: /admin
    section: dashboard
    role: admin
  - title: Social
    section: social
    items:
      - title: Twitter
        link: https://twitter.com/arcblock
        icon: mdi:twitter
      - title: GitHub
        link: https://github.com/arcblock
        icon: mdi:github
```

此示例说明了几个关键功能：
- 一个简单的页眉链接（“Features”）。
- 一个多语言页脚链接（“About Us”）。
- 一个仅限管理员的仪表盘链接。
- 一组用于页脚的社交媒体链接。

## 数据处理管道

在渲染之前，该库会通过一系列步骤处理原始元数据，为 UI 组件做准备。

### 1. 解析与分段

第一步是解析 `navigation` 数组，并根据其 `section` 属性对项目进行分组。通过为 `section` 值使用数组，可以将单个导航项分配到多个区域。

`parseNavigation` 工具将每个项目分类到预定义的区域中：
- `header`：用于主应用程序页眉。
- `footer`：用于页脚中的主要链接。
- `social`：用于社交媒体图标，通常在页脚中。
- `bottom`：用于页脚最底部的法律或次要链接。
- `dashboard`：用于仪表盘布局中的侧边栏导航。
- `sessionManager`：用于用户会话组件内的菜单。
- `userCenter`：用于用户个人资料区域内的选项卡或链接。

如果一个项目没有 `section` 属性，它默认被归为 `header`。

### 2. 国际化 (i18n)

该库内置了对多种语言的支持。如果导航项中的 `title` 或 `link` 属性是一个带有语言键（例如 `en`、`zh`）的对象，`getLocalizedNavigation` 函数会根据用户当前的区域设置自动选择正确的字符串。

```javascript i18n 对象示例 icon=logos:javascript
// 一个支持多语言的导航项
{
  title: {
    en: 'Home',
    zh: '首页'
  },
  link: {
    en: '/home',
    zh: '/zh/home'
  }
}
```

### 3. 基于角色的过滤

为了创建动态的用户体验，导航项可以限制于特定的用户角色。`filterNavByRole` 函数通过将每个项目的 `role` 属性与当前会话中的 `user.role` 进行比较来过滤导航列表。

- 如果一个项目没有 `role` 属性，它对所有人可见。
- 如果一个项目有 `role` 属性（例如 `['admin', 'editor']`），它仅对角色在该数组中的用户可见。
- `guest` 角色是一个特殊值，适用于未经身份验证的用户。

这种机制允许您在元数据中定义一个全面的导航结构，并让 UI 根据登录用户的权限自动适应。

## 总结

Blocklet UI React 库的核心概念是利用一个集中的元数据对象来驱动通用 UI 组件的配置和渲染。这种元数据驱动方法具有以下几个优点：

- **单一事实来源**：应用程序的结构、品牌和导航都在一个地方定义。
- **一致性**：确保应用程序不同部分具有一致的外观和感觉。
- **减少样板代码**：无需手动编码像页眉和页脚这样的通用布局元素。
- **动态 UI**：原生支持国际化和基于角色的访问控制，允许 UI 根据用户及其权限动态调整。

清楚地理解了这些原则后，您就可以有效地利用该库的组件。有关特定组件及其用法的更多信息，请参阅 [组件](./components.md) 部分。