# @genesislcap/foundation-react-utils 中文文档

规范地址：https://npmcn.com/package/%40genesislcap/foundation-react-utils/

版本：15\.96\.2
npm 元数据更新时间：2026-11-16T09:27:40.340Z
中文译文更新时间：2026-11-16T09:28:54.532Z
软件包许可：SEE LICENSE IN license\.txt

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40genesislcap/foundation-react-utils
原文对照：https://npmcn.com/package/%40genesislcap/foundation-react-utils/?lang=original
项目主页：https://github.com/genesislcap/foundation-ui#readme
源码仓库：https://github.com/genesislcap/foundation-ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：255 kB，62 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：9 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，react-router-dom ^7\.0\.0，@genesislcap/foundation-workspace ^15\.96\.2
- 首次发布：2025-11-14T17:09:36.888Z
- 最新版本发布：2026-11-16T09:27:40.122Z
- 近 30 天下载量：15005（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：974（近 12 个月 973 个）

## 中文简介

创世纪基金会

## 安装

```sh
npm install @genesislcap/foundation-react-utils
```

也可以使用：`pnpm add @genesislcap/foundation-react-utils`、`yarn add @genesislcap/foundation-react-utils`、`bun add @genesislcap/foundation-react-utils`

## README

# @ 起源cap/ foundation- react- utils

本套件的文档发布在创世纪文献网站:

**文档 : [框架整合](https://docs.genesis.global/docs/develop/client-capabilities/framework-integration/)**

## 安装

将软件包添加到您的 `package.json` 依赖性。 更改依赖关系后运行 `npm run bootstrap` (或你的项目等同). 见 [软件包.json 基础](https://learn.genesis.global/secure/web/basics/package-json-basics/) 更多信息.

```json
{
  "dependencies": {
    "@genesislcap/foundation-react-utils": "latest"
  }
}
```

## 弹性放出反应

`flexlayout-react` 是从 `./flexlayout` 此软件包版本的入口点 pins,所以应用程序既不声明也不升级自己:

```ts
import { Actions, DockLocation, Layout, Model, TabNode } from '@genesislcap/foundation-react-utils/flexlayout';
```

整个入境点再出口 `flexlayout-react` API 并安装快速设计系统 中的主题。 不需要导入样式表,并且 `flexlayout-react`是因为 不应导入自己的样式表, 它们是没有主题的上游默认 。 颜色解析 从快速设计符号, 所以使布局在一个 `<rapid-design-system-provider>`。 。 。 .

文档中采用的样式不会跨越阴影边界,所以在文档中安装的布局 影子根也需要通过的主题:

```ts
import { installRapidFlexLayoutReactStyles } from '@genesislcap/foundation-react-utils/flexlayout';

installRapidFlexLayoutReactStyles(myShadowRoot);
```

### 移动一个直接依赖弹性反射的应用程序

删除 `flexlayout-react` 从应用的 `package.json`中,放弃任何 `flexlayout-react/style/*.css` ,将剩余进口指向 `./flexlayout`保持应用层面的依赖风险 解决图书馆的第二个副本,该副本将打破 `instanceof` 检查 `flexlayout-react` 依赖内部; 当装入的版本不同于该版本时, 输入点会记录警告 生成了相应的主题.

## 错误边界

`AppErrorBoundary` 包好整个应用程序 `TileErrorBoundary` (或 `withTileErrorBoundary` HOC)包了一块单瓦,因此相撞只取代了那块平板. 两者都与 参考 ID 、 可复制的诊断和重载孩子的重试按钮.

与 `setupErrorMonitoring` 从 `@genesislcap/foundation-utils`时,发现的错误将随 他们的参考ID,范围,标题,瓦片注册和组件堆栈,没有其他 需要:

```tsx
import { AppErrorBoundary, onCaughtError } from '@genesislcap/foundation-react-utils';

createRoot(el, { onCaughtError }).render(
  <AppErrorBoundary>
    <App />
  </AppErrorBoundary>,
);
```

```tsx
import { TileErrorBoundary, withTileErrorBoundary } from '@genesislcap/foundation-react-utils';

<TileErrorBoundary title="Trade Blotter" tileRegistration="tradeBlotter">
  <TradeBlotter />
</TileErrorBoundary>;

export const TradeBlotterTile = withTileErrorBoundary(TradeBlotter, 'Trade Blotter', 'tradeBlotter');
```

自己处理错误,通过 `onError`它收到一个 `ErrorBoundaryReport` (单位:千美元)`error`, (中文(简体) ), `componentStack`, (中文(简体) ), `referenceId`, (中文(简体) ), `scope`, (中文(简体) ), `title`, (中文(简体) ), `tileRegistration`) (中文(简体) ). `withTileErrorBoundary` 取为第四辩.

过 `onCaughtError` 改为 `createRoot`。默认情况下, 重录 19 记录每个错误 `console.error` 在边界运行之前,一个控制台抓取监控工具 报告赤裸裸 先出错,然后可以放下或复制边界本身的报告. `onCaughtError` 跳过日志 并仍然记录被其他边界所捕获的错误及其组成部分 堆栈.

无 `onError`,通过命名的根基日志记录每个被捕获的错误 `ERROR_BOUNDARY_LOGGER_NAME`,并注明其范围、标题、瓦片登记和 引用 ID 并给出其组件堆栈。 全球日志报告员`addGlobalLogReporter` 从 `@genesislcap/foundation-logger`)接受,这就是如何 `setupErrorMonitoring` 报告 与 `onError` 设置时,边界不会记录错误,所以没有报告两次。 若为 `onError` 抛出, 边界记录原始错误和处理器错误,所以两者都不丢失.

倒背从设计系统的标志取出颜色、字体和角半径 (单位:千美元)`--neutral-layer-1`, (中文(简体) ), `--neutral-foreground-rest`, (中文(简体) ), `--accent-fill-rest`, (中文(简体) ), `--error-color`, (中文(简体) ), `--body-font`, (中文(简体) ), `--control-corner-radius` 因此它跟随应用程序的主题,包括光 和阴暗模式。 要覆盖它们,设置 `--eb-*` 自定义属性( e)`--eb-bg`, (中文(简体) ), `--eb-surface`, (中文(简体) ), `--eb-text`, (中文(简体) ), `--eb-text-muted`, (中文(简体) ), `--eb-border`, (中文(简体) ), `--eb-accent`, (中文(简体) ), `--eb-error`, (中文(简体) ), `--eb-font`和其他事项) 在一个祖先。 没有设计系统,它会使用自己的灯光调色板. 过去20份报告也得到保存 打开 `window.__GENESIS_ERROR_BOUNDARY_REPORTS__` 用于诸如创世纪创建预览等dev工具.

## 基础工作空间

工作空间( 保存/ 负荷布局、 网格列状态和过滤器) 通过元素在 React 中工作 包装 `@genesislcap/foundation-workspace/react` 已经是船了,加上一个钩子 过滤状态. `@genesislcap/foundation-workspace` 是可选的对等依赖: 添加到您的应用程序中 要使用的依赖性 `@genesislcap/foundation-react-utils/workspace`。 。 。 .

```tsx
import { registerFactory } from '@genesislcap/foundation-layout';
import { reactFactory } from '@genesislcap/foundation-react-utils';
import { useWorkspaceFilter } from '@genesislcap/foundation-react-utils/workspace';
import { GridRegister, LayoutWrapper, WorkspaceManager } from '@genesislcap/foundation-workspace/react';

const PositionsPanel = () => {
  const [search, setSearch] = useState('');
  useWorkspaceFilter('positions-search', search, setSearch);
  return (
    <GridRegister gridKey="positions">
      <RapidGridPro persistColumnStateKey="positions">…</RapidGridPro>
    </GridRegister>
  );
};

registerFactory('positions', reactFactory(PositionsPanel));

<LayoutWrapper layoutKey="my-layout">
  <rapid-layout auto-save-key="my-layout">
    <rapid-layout-region>
      <rapid-layout-item registration="positions" title="Positions" />
    </rapid-layout-region>
  </rapid-layout>
</LayoutWrapper>

<WorkspaceManager />
```

-   登记册 `workspaceComponents` 从 `@genesislcap/foundation-workspace` 你的设计系统.
-   通过渲染布局 `registerFactory` + 键 `reactFactory`,而不是作为JSX儿童 `rapid-layout-item`。装入已保存的布局会重建窗格,克隆的 DOM 将丢失 React-set 属性,例如 `gridOptions`。 。 。 .
-   `useWorkspaceFilter` 还在挂载上应用当前工作空间所保存的值, 所以过滤器 在布局负载重重现的窗格内,仍然可以取出其保存的值.

### 弹性反射布局

`LayoutWrapper` 仅覆盖 `rapid-layout`对于弹性反射布局,请按 `Model` 内 状态并注册到 `useWorkspaceFlexLayout`; 装入工作空间将新模型交给您 :

```tsx
import { Layout, Model } from '@genesislcap/foundation-react-utils/flexlayout';
import { useWorkspaceFlexLayout } from '@genesislcap/foundation-react-utils/workspace';

const [model, setModel] = useState(() => Model.fromJson(defaultLayout));
useWorkspaceFlexLayout('home-layout', model, setModel);

return <Layout model={model} factory={factory} />;
```

由装入的布局挂载和卸载打开或关闭的标签, 所以 `GridRegister` 财务报告和审定财务报表 `useWorkspaceFilter` 在他们内部,在他们注册时,取出工作空间的状态.

## 许可证

注:该项目提供前端依赖性,并使用下一节所列许可部件;因此,开发期间需要对这些部件发放许可证。 联系人 [创世纪全球](https://genesis.global/contact-us/) 更多细节.

### 许可组件

创世纪低码平台

## 常见问题

### @genesislcap/foundation-react-utils 是什么？

创世纪基金会

### 如何安装 @genesislcap/foundation-react-utils？

在项目目录运行 npm install @genesislcap/foundation-react-utils，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @genesislcap/foundation-react-utils 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @genesislcap/foundation-react-utils 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @genesislcap/foundation-react-utils 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @genesislcap/foundation-react-utils 可以商用吗？

@genesislcap/foundation-react-utils 使用 SEE LICENSE IN license\.txt 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @genesislcap/foundation-react-utils 的下载量有多少？

根据 npm 官方下载统计，@genesislcap/foundation-react-utils 在 2026/10/16 – 2026/11/14 这 30 天内被下载 15,005 次，日均约 500 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @genesislcap/foundation-react-utils 还在维护吗？

最新版本 15\.96\.2 发布于 2026/11/16（今天）；至今共发布 974 个版本，其中过去 12 个月发布了 973 个；首次发布于 2025/11/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

