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

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

# Footer

`Footer` 组件为你的应用提供了一个标准化的、响应式的页脚。它通过读取 blocklet 的元数据来自动填充其内容——包括品牌信息、导航链接、社交媒体图标和版权信息。这种数据驱动的方法确保了一致性并简化了配置。

该组件采用响应式设计，能够适应不同屏幕尺寸的布局。它还内置了逻辑，在应用以嵌入模式运行时自动隐藏，从而确保集成时用户界面的整洁。

## 基本用法

要为你的应用添加页脚，只需导入并渲染 `Footer` 组件即可。在基本使用中，它不需要任何 props，因为它会自动从全局 `window.blocklet` 对象中获取数据。

```jsx Usage Example 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 Custom Theme Example 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`）包裹，当应用在嵌入式上下文中渲染时，该组件会自动隐藏 `Footer`。此行为由一个会话存储键 `EMBED_MODE_KEY` 控制。如果此键设置为 `1`，页脚将不会被渲染。这在你的 blocklet 显示在另一个应用内部时，有助于防止出现多余的页脚。

---

有关 `Header` 组件的信息（该组件也通过 blocklet 元数据进行配置），请参阅 [Header 文档](./components-layout-header.md)。