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

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

# 工具

本节提供了关于一系列辅助组件、高阶组件 (HOC) 和实用函数的文档。这些工具旨在简化常见的开发任务、管理应用程序主题和处理复杂的数据结构。

可用的主要工具有：

<x-cards data-columns="2">
  <x-card data-title="Icon 组件" 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)，如果应用程序处于“嵌入模式”，它会阻止组件渲染。它会检查一个会话存储键 (`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` 组件的全面指南，请参阅下一节。
- **[Icon](./components-utilities-icon.md)**