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

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

# 工具

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

可用的主要工具有：

<x-cards data-columns="2">
  <x-card data-title="圖示元件" data-icon="lucide:image" data-href="/components/utilities/icon">
    一個多功能的元件，可用於顯示來自各種來源的圖示，包括 Iconify、圖片 URL 或字母頭像。
  </x-card>
  <x-card data-title="OverridableThemeProvider" data-icon="lucide:palette">
    一個主題提供者，允許開發人員提供自己的主題物件來覆寫預設的 Blocklet UI 主題。
  </x-card>
  <x-card data-title="withHideWhenEmbed HOC" data-icon="lucide:eye-off">
    一個高階元件，可根據條件渲染元件，當應用程式處於嵌入模式時將其隱藏。
  </x-card>
  <x-card data-title="JavaScript 輔助函式" data-icon="lucide:function-square">
    一套獨立的函式，用於遞迴陣列操作、URL 驗證和路徑匹配等任務。
  </x-card>
</x-cards>

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

## OverridableThemeProvider

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

### 使用方法

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

```javascript Theme Provider Example icon=logos:javascript
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 封裝您希望有條件地隱藏的元件。

```javascript HOC Example icon=logos:javascript
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` 元件的全面指南，請參閱下一節。
- **[圖示](./components-utilities-icon.md)**