@blocklet/ui-react/docs/getting-started.zh-TW.md

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

# 入門指南

本指南提供逐步教學，引導您安裝 `@blocklet/ui-react` 函式庫並渲染您的第一個元件。目標是在最短的時間內，讓您的應用程式中能正常運作 `Header` 和 `Footer`。

## 先決條件

在繼續之前，請確保您的開發環境中已安裝以下項目：
*   一個可運作的 React 專案。
*   Node.js 和一個套件管理器（npm 或 yarn）。

## 安裝

首先，使用您偏好的套件管理器將 `@blocklet/ui-react` 套件新增至您的專案中。

使用 npm：
```bash npm
npm install @blocklet/ui-react
```

使用 yarn：
```bash yarn
yarn add @blocklet/ui-react
```

## 基本用法：Header 與 Footer

`Header` 和 `Footer` 元件的設計旨在簡化使用，無需任何初始設定即可渲染。它們會自動從 blocklet 的元資料中獲取資料。

1.  將 `Header` 和 `Footer` 元件匯入到您的主應用程式檔案中（例如 `App.js`）。
2.  將它們分別放置在應用程式佈局的頂部和底部。

```jsx App.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Footer from '@blocklet/ui-react/lib/Footer';

function App() {
  return (
    <div>
      <Header />
      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
        {/* 您的應用程式內容放在這裡 */}
        <h1>Welcome to My Blocklet</h1>
      </main>
      <Footer />
    </div>
  );
}

export default App;
```

這些元件會自動從 `window.blocklet` 元資料物件中檢索設定詳情，例如應用程式名稱、標誌和導覽連結。該物件由 Blocklet Server 環境注入。

此外，`Header` 元件會智慧地渲染額外的控制項：
*   如果 `SessionContext` 可用，將會顯示**使用者會話管理器**。
*   如果 `LocaleContext` 可用，將會顯示**語言選擇器**。

## 手動設定

在開發、測試或需要覆寫預設元資料的情況下，您可以使用 `blockletMeta` 屬性將設定物件直接傳遞給元件。

```jsx App.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';

const customBlockletMeta = {
  appName: 'My Custom App',
  appLogo: 'https://path.to/your/logo.png',
  navigation: [
    {
      title: 'Home',
      link: '/',
    },
    {
      title: 'Documentation',
      link: '/docs',
    },
  ],
};

function App() {
  return (
    <div>
      <Header blockletMeta={customBlockletMeta} />
      {/* ... rest of your app */}
    </div>
  );
}
```

這種方法讓您能透過覆寫全域 `window.blocklet` 物件提供的任何資料，來精確控制元件的外觀和行為。

## 自訂 Header

`Header` 元件在右側包含一個 `addons` 區域，您可以自訂該區域以包含您自己的元件，例如操作按鈕或自訂連結。

`addons` 屬性接受一個函式，該函式接收預設的附加元件作為參數。這讓您可以將新元件加到現有元件的前面、後面，或是完全取代它們。

```jsx CustomHeader.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button'; // 使用 Material-UI 的範例

function CustomHeader() {
  return (
    <Header
      addons={existingAddons => {
        return [
          <Button
            key="custom-action"
            variant="contained"
            color="primary"
            size="small"
            style={{ marginRight: 8 }}>
            Custom Action
          </Button>,
          ...existingAddons, // 重要：保留預設的 session/locale 附加元件
        ];
      }}
    />
  );
}
```

在此範例中，一個自訂按鈕被加到現有的附加元件前面。透過包含 `...existingAddons`，您可以確保預設的會話和地區設定控制項仍然可見。

## 總結

您已成功安裝 `@blocklet/ui-react` 函式庫，渲染了預設的 `Header` 和 `Footer` 元件，並學會了如何提供自訂設定和附加元件。

掌握了這些基礎知識後，您現在可以開始探索此函式庫中提供的所有元件了。關於佈局、使用者管理和工具程式元件的詳細文件，請前往 [元件](./components.md) 部分。