@blocklet/ui-react/docs/components-layout-footer.zh-TW.md

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

# Footer

`Footer` 元件為您的應用程式提供一個標準化、回應式的頁尾。它會透過讀取您的 blocklet 的元資料，自動填入其內容——包括品牌、導覽連結、社群媒體圖示和版權資訊。這種資料驅動的方法確保了一致性並簡化了設定。

該元件被設計為回應式，能適應不同螢幕尺寸的版面配置。它還包含內建邏輯，可在應用程式以嵌入模式執行時自動隱藏，確保在整合中擁有乾淨的使用者介面。

## 基本用法

若要為您的應用程式新增頁尾，只需匯入並渲染 `Footer` 元件即可。基本使用時無需任何 props，因為它會自動從全域 `window.blocklet` 物件中取得資料。

```jsx 使用範例 icon=logos:react
import React from 'react';
import { Footer } from '@blocklet/ui-react';

export default function App() {
  return (
    <div style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}>
      <main style={{ flex: 1 }}>
        {/* 您的應用程式內容放在這裡 */}
      </main>
      <Footer />
    </div>
  );
}
```

## Props

`Footer` 元件可透過以下 props 進行客製化。

<x-field-group>
  <x-field data-name="meta" data-type="object" data-required="false">
    <x-field-desc markdown>
      包含 blocklet 元資料的物件。使用此 prop 可覆寫預設的 `window.blocklet` 設定，或在全域物件不可用的環境中提供資料。其結構應與 blocklet 元資料格式相符。
    </x-field-desc>
  </x-field>
  <x-field data-name="theme" data-type="object" data-required="false">
    <x-field-desc markdown>
      用於客製化頁尾外觀的主題物件。此物件會與應用程式的預設主題進行深度合併，讓您可以覆寫特定的樣式，如顏色、字體和間距。
    </x-field-desc>
  </x-field>
</x-field-group>

## 元資料設定

`Footer` 的內容主要透過 blocklet 的元資料檔案 (`blocklet.yml`) 進行設定。該元件會從此檔案中讀取特定欄位來渲染其不同區塊。

以下是一個 `blocklet.yml` 設定範例，它會填入頁尾的所有區塊。

```yaml blocklet.yml
name: my-app
title: My App
description: A detailed description of my application that appears in the footer.
copyright: 'My Company Inc.'

# 導覽連結被組織成群組
navigation:
  # 主要頁尾導覽，支援兩層分組
  footer:
    - title: 'Products'
      items:
        - title: 'Product A'
          link: '/products/a'
        - title: 'Product B'
          link: '/products/b'
    - title: 'Resources'
      items:
        - title: 'Documentation'
          link: '/docs'
        - title: 'Blog'
          link: '/blog'

  # 社群媒體連結
  social:
    - title: 'twitter' # 圖示是從標題推斷出來的（例如 'twitter', 'github'）
      link: 'https://twitter.com/your-handle'
    - title: 'github'
      icon: 'mdi:github' # 您也可以指定一個 Iconify 圖示名稱
      link: 'https://github.com/your-org'

  # 底部連結，通常用於法律和隱私資訊
  bottom:
    - title: 'Privacy Policy'
      link: '/privacy'
    - title: 'Terms of Service'
      link: '/terms'
```

### 資料結構

您元資料中的 `navigation` 物件定義了顯示在頁尾中的連結。它被組織成三個不同的區塊：`footer`、`social` 和 `bottom`。

<x-field-group>
  <x-field data-name="navigation" data-type="object">
    <x-field-desc markdown>
      包含應用程式的所有導覽結構。
    </x-field-desc>
    <x-field data-name="footer" data-type="array">
      <x-field-desc markdown>
        主要頁尾導覽區域的連結群組陣列。支援兩層的層級結構。
      </x-field-desc>
      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="導覽群組的標題（例如，「Products」）。"></x-field>
      <x-field data-name="[].link" data-type="string" data-required="false" data-desc="群組標題本身的可選連結。"></x-field>
      <x-field data-name="[].items" data-type="array" data-required="false" data-desc="子導覽連結的陣列。">
        <x-field data-name="[].title" data-type="string" data-required="true" data-desc="連結的顯示文字。"></x-field>
        <x-field data-name="[].link" data-type="string" data-required="true" data-desc="導覽連結的 URL。"></x-field>
      </x-field>
    </x-field>
    <x-field data-name="social" data-type="array">
      <x-field-desc markdown>
        指向社群媒體個人資料的連結陣列。
      </x-field-desc>
      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="社群媒體平台的名稱，用於推斷圖示（例如，「twitter」）。"></x-field>
      <x-field data-name="[].icon" data-type="string" data-required="false" data-desc="使用 Iconify 字串明確指定一個圖示（例如，`mdi:github`）。這會覆寫推斷出的圖示。"></x-field>
      <x-field data-name="[].link" data-type="string" data-required="true" data-desc="指向社群媒體個人資料的 URL。"></x-field>
    </x-field>
    <x-field data-name="bottom" data-type="array">
      <x-field-desc markdown>
        顯示在頁尾最底部的連結陣列，通常用於法律聲明。
      </x-field-desc>
      <x-field data-name="[].title" data-type="string" data-required="true" data-desc="連結的顯示文字（例如，「Privacy Policy」）。"></x-field>
      <x-field data-name="[].link" data-type="string" data-required="true" data-desc="連結的 URL。"></x-field>
    </x-field>
  </x-field>
</x-field-group>

## 版面配置

`Footer` 元件會根據提供的資料智慧地選擇最合適的版面配置。這確保了在不同使用情境下都能有乾淨且功能齊全的呈現。

- **標準版面配置**：當您的元資料中定義了 `footer` 導覽連結或 `social` 社群媒體連結時，此版面配置會自動啟用。它採用多區塊設計，優雅地組織品牌資訊、社群圖示和導覽欄。在行動裝置上，導覽群組會變成可折疊的手風琴式選單，以提供更好的使用者體驗。

- **簡潔版面配置**：如果沒有提供 `footer` 或 `social` 連結，元件會退回使用簡化的單行版面配置。這對於只需要版權聲明和一些基本連結（如「服務條款」或「隱私權政策」）的應用程式來說非常理想。

## 主題化

您可以透過傳遞一個 `theme` 物件來客製化頁尾的外觀。此物件會與現有主題進行深度合併，從而實現針對性的覆寫。

```jsx 客製化主題範例 icon=logos:react
import { Footer } from '@blocklet/ui-react';

const customTheme = {
  palette: {
    background: {
      default: '#2c3e50', // 頁尾使用較暗的背景
    },
    text: {
      primary: '#ecf0f1',
      secondary: '#bdc3c7',
    },
    divider: '#34495e',
  },
};

// ... 在您元件的 render 方法中
<Footer theme={customTheme} bordered />;
```

## 嵌入模式下的行為

`Footer` 元件被一個高階元件 (`withHideWhenEmbed`) 包裹，當應用程式在嵌入式情境中渲染時，它會自動隱藏頁尾。此行為由一個 session storage 金鑰 `EMBED_MODE_KEY` 控制。如果此金鑰被設定為 `1`，頁尾將不會被渲染。這對於防止您的 blocklet 顯示在另一個應用程式內部時出現多餘的頁尾很有用。

---

關於 header 元件的資訊（該元件也透過 blocklet 元資料進行設定），請參閱 [Header 文件](./components-layout-header.md)。