工具 | ArcBlock

本節提供了一系列輔助元件、高階元件 (HOCs) 和工具函式的說明文件。這些工具旨在簡化常見的開發任務、管理應用程式主題以及處理複雜的資料結構。

可用的主要工具有：

圖示元件

一個多功能的元件，可用於顯示來自各種來源的圖示，包括 Iconify、圖片 URL 或字母頭像。

OverridableThemeProvider

一個主題提供者，允許開發人員提供自己的主題物件來覆寫預設的 Blocklet UI 主題。

withHideWhenEmbed HOC

一個高階元件，可根據條件渲染元件，當應用程式處於嵌入模式時將其隱藏。

JavaScript 輔助函式

一套獨立的函式，用於遞迴陣列操作、URL 驗證和路徑匹配等任務。

有關 Icon 元件的詳細指南，請參閱其專門的文件頁面。其他工具的說明文件如下。

OverridableThemeProvider

此元件是 Material-UI ThemeProvider 的一個封裝。它允許您將一致的主題應用於其子元件。預設情況下，它使用標準的 Blocklet UI 主題，但您可以透過 theme 屬性提供一個自訂的主題物件來覆寫預設樣式。

使用方法

若要應用自訂主題，請將一個主題物件傳遞給 theme 屬性。該元件會將您的覆寫與預設主題合併。

Theme Provider Example

import OverridableThemeProvider from '@blocklet/ui-react/lib/common/overridable-theme-provider';
import { Button } from '@mui/material';

const customTheme = {
  palette: {
    primary: {
      main: '#ff5722',
    },
  },
};

function App() {
  return (
    <OverridableThemeProvider theme={customTheme}>
      <Button color="primary" variant="contained">
        Custom Themed Button
      </Button>
    </OverridableThemeProvider>
  );
}

withHideWhenEmbed

withHideWhenEmbed 是一個高階元件 (HOC)，如果應用程式處於「嵌入模式」，它會防止元件被渲染。它會檢查一個 session storage 的鍵 (EMBED_MODE_KEY) 來確定當前模式。如果該值為 1，被封裝的元件將返回 null。

這對於在嵌入式情境中隱藏不需要的元素（如頁首或頁尾）非常有用。

使用方法

用 withHideWhenEmbed HOC 封裝您希望有條件地隱藏的元件。

HOC Example

import withHideWhenEmbed from '@blocklet/ui-react/lib/libs/with-hide-when-embed';

function PageHeader() {
  return (
    <header>
      <h1>My Application</h1>
    </header>
  );
}

const MaybeHiddenHeader = withHideWhenEmbed(PageHeader);

function App() {
  return (
    <div>
      <MaybeHiddenHeader />
      <main>
        {/* 主要內容放置於此 */}
      </main>
    </div>
  );
}

輔助函式

提供了一組純 JavaScript 函式，用於常見的資料操作和驗證任務。這些函式可以直接從函式庫的工具模組中匯入。

陣列操作

這些函式設計用於處理巢狀物件的陣列，例如導覽選單或檔案樹。

函式	說明
`mapRecursive(array, fn, childrenKey = 'children')`	遞迴地將一個函式應用於巢狀陣列中的每個項目。
`flatRecursive(array, childrenKey = 'children')`	將巢狀陣列扁平化為單層陣列。
`countRecursive(array, childrenKey = 'children')`	計算巢狀陣列中項目的總數。
`filterRecursive(array, predicate, childrenKey = 'children')`	根據一個斷言函式遞迴地篩選巢狀陣列，如果子項目匹配，則保留父結構。

字串與 URL 驗證

用於檢查字串格式的簡單輔助函式。

函式	說明
`isUrl(str)`	如果字串以 `http://` 或 `https://` 開頭，則返回 `true`。
`isMailProtocol(str)`	如果字串以 `mailto:` 開頭，則返回 `true`。

路由

協助客戶端路由邏輯的工具。

函式	說明
`matchPath(path)`	檢查給定路徑是否與當前的 `window.location.pathname` 匹配。
`matchPaths(paths)`	從一個路徑陣列中，找到與當前位置最佳匹配的路徑。

版面配置

函式	說明
`splitNavColumns(items, options)`	將導覽項目列表分割成指定數量的欄，對於建立大型選單很有用。

總結

本節概述了函式庫中包含的通用工具。若需更強大、更專業的功能，請繼續閱讀各個元件的詳細文件。

有關使用靈活的 Icon 元件的全面指南，請參閱下一節。

圖示