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

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

# 核心概念

本文件說明 Blocklet UI React 函式庫的基本原則。其核心設計理念是**元數據驅動方法**，其中 UI 元件（如 `Header`、`Footer` 和 `Dashboard`）會根據 blocklet 的元數據自動設定和渲染。此策略確保了一致性，減少了樣板程式碼，並實現了能根據使用者角色和語言偏好進行調整的動態 UI。

其中心思想是，單一設定檔（通常是 `blocklet.yml`）作為應用程式整體結構和外觀的唯一事實來源。函式庫會讀取此元數據，對其進行處理，並用它來建構適當的 UI 元素。

## 元數據驅動原則

該函式庫的運作可以視覺化為一個簡單的資料流：blocklet 元數據作為輸入提供給函式庫，函式庫接著透過一個管線對其進行處理，以產生完全渲染的 UI 元件。這免去了開發人員為每個應用程式手動建構和設定通用佈局元素的需要。

<!-- DIAGRAM_IMAGE_START:flowchart:16:9:1765962229 -->
![Core Concepts](assets/diagram/core-concepts-diagram-0.zh-TW.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
```

此範例說明了幾個關鍵功能：
- 一個簡單的 header 連結（「Features」）。
- 一個多語言的 footer 連結（「About Us」）。
- 一個僅限管理員的 dashboard 連結。
- 一組用於 footer 的社群媒體連結。

## 資料處理管線

在渲染之前，函式庫會透過一系列步驟處理原始元數據，為 UI 元件做好準備。

### 1. 解析與分區

第一步是解析 `navigation` 陣列，並根據其 `section` 屬性將項目分組。透過為 `section` 值使用陣列，可以將單個導覽項目分配到多個區塊。

`parseNavigation` 工具程式會將每個項目分類到預定義的區塊中：
- `header`：用於主應用程式的 header。
- `footer`：用於 footer 中的主要連結。
- `social`：用於社群媒體圖示，通常在 footer 中。
- `bottom`：用於 footer 最底部的法律或次要連結。
- `dashboard`：用於 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 元件的設定與渲染。這種元數據驅動的方法提供了幾個優點：

- **單一事實來源**：應用程式的結構、品牌和導覽都在一個地方定義。
- **一致性**：確保應用程式不同部分之間具有一致的外觀和風格。
- **減少樣板程式碼**：無需手動編寫像 header 和 footer 這樣的通用佈局元素。
- **動態 UI**：原生支援國際化和基於角色的存取控制，讓 UI 能夠根據使用者及其權限動態調整。

清楚了解這些原則後，您就能有效地利用該函式庫的元件。有關特定元件及其用法的更多資訊，請參閱 [元件](./components.md) 部分。