入門指南 | ArcBlock

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

先決條件

在繼續之前，請確保您的開發環境中已安裝以下項目：

一個可運作的 React 專案。
Node.js 和一個套件管理器（npm 或 yarn）。

安裝

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

使用 npm：

npm

npm install @blocklet/ui-react

使用 yarn：

yarn

yarn add @blocklet/ui-react

基本用法：Header 與 Footer

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

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

App.js

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 屬性將設定物件直接傳遞給元件。

App.js

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

CustomHeader.js

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 元件，並學會了如何提供自訂設定和附加元件。

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