# @faybl/react-utils 中文文档

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

版本：2\.5\.2
npm 元数据更新时间：2026-11-13T08:36:37.695Z
中文译文更新时间：2026-11-14T12:06:13.868Z
软件包许可：TBD

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

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

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

- 包体积（解压后）：63.2 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：2 个
- peer 依赖：react ^19\.2\.0，@faybl/client ^4\.1\.0，@mui/material ^9\.0\.0，@mui/icons-material ^9\.0\.0
- 首次发布：2026-10-22T03:31:08.469Z
- 最新版本发布：2026-11-13T08:36:37.504Z
- 近 30 天下载量：3143（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

Faybl 网络应用程序的反应钩和组件

## 安装

```sh
npm install @faybl/react-utils
```

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

## README

# @faybl/ react-utils (英语)

Faybl网络应用的回放钩和组件.

```
npm install @faybl/react-utils
```

每个钩子,但 `useSession` 拿着 `@faybl/client` 客户端为 `client` 财务报告和审定财务报表 除非它有一个; `useSession` 读它从 `SessionProvider`。 。 。 . `useConnection` 财务报告和审定财务报表 `SessionProvider` 需要客户端 4.1 或稍后。 丢弃列表 或 ids 按其内容来比较, 因此具有相同 ids 的新数组不 重新订阅.

```js
import {
  useChannelsLatest,
  useChannelsSeries,
  useConnection,
  usePresence,
  useSession,
} from '@faybl/react-utils';

const presenceById = usePresence({ client, identityIds });
const latest = useChannelsLatest({ client, rids, commitMs: 1000, onError });
const series = useChannelsSeries({ client, rids, windowSeconds: 3600 });
const connected = useConnection({ client });
const { expired, cause, user, signIn, signOut } = useSession();
```

| 钩子 | 回返 |
| --- | --- |
| `usePresence` | `{ [identityId]: { ts, connected } }`现场直播 |
| `useChannelsLatest` | `{ [rid]: { ts, pl } }`,最后存储点,然后活 |
| `useChannelsSeries` | `{ [rid]: points }`,最后一个 `windowSeconds`最老的先活下来 |
| `useConnection` | mQTT 连接是否打开 |
| `useSession` | 会议闭幕 [过期会话](https://npmcn.com/package/%40faybl/react-utils/#readme-an-expired-session) |
| `useDeploymentInfo` | 租户的网络应用程序,看 [部署信息](https://npmcn.com/package/%40faybl/react-utils/#readme-deployment-info) |

`connected` 财务报告和审定财务报表 `expired` 为: `undefined` 直到客户报告为止.

二道钩取出两个选择:

-   `commitMs` 收集活点,每多毫秒一次. 没有它,每一点都会随着它到达.
-   `onError(error, rid)` 当一个历史读取失败时,它被称为历史。 钩子报告 没有他们自己.

## 过期会话

`SessionProvider` 跟踪客户端后面的会话,并在 它不见了。 当客户端存在后, 将其绕入应用程序 :

```jsx
<SessionProvider client={client}>
  <App />
</SessionProvider>
```

它有两种方法,每个都有自己的道具:

| Prop | 何时 | 默认 |
| --- | --- | --- |
| `expiredOnReturn` | 用户返回标签; 然后发送请求以检查 | `reload` |
| `expiredOnRequest` | 当用户在页面上工作时拒绝请求 | `dialog` |

每一个都要 `reload`, (中文(简体) ), `dialog` 或者说 `none`,并导出为 `REACTION`数字 :

-   `reload` 重新装入页面。 虽然身份提供者还有会话 用户一次返回同一页面;否则,登录页面显示.
-   `dialog` 显示 `SessionExpiredDialog`,它保存了页面, 和无论 用户正在输入,直到用户再次选择签名.
-   `none` 没有做任何事情, 对于一个应用 显示它自己的方式通过 `useSession`。 。 。 .

在隐藏标签时发现过期值为返回, 并等待到 用户返回。 在自动重新装入后, 标签只再次重新装入 一次 `reloadCooldownMs` (违约 30 000) 已经通过; 到期前显示 对话框,所以一个与会话无关的401不能循环重新装入 . `dialogLabels` 设置对话框 `{ title, action }`,英文为 默认。 对话框从页面的 CSS 取出颜色 `color-scheme`,所以一个 深色的应用程序必须声明, MUI通过 `<CssBaseline enableColorScheme />`。 。 。 .

租户可以不经签注而跑. 给提供者部署信息 地址为 `deploymentInfoUrl`并获取用户 只有在信息上说签到的时候,没有签到的房客,也没有签到, 而用户菜单没有。 无 `deploymentInfoUrl` 登录数为 继续.

`useSession()` 返回 :

-   `authEnabled`:在租户没有签注的情况下作假,未定义,同时 已读取部署信息.
-   `expired`: 在客户端报告之前未定义, 那么是否 课会结束.
-   `cause`: 如何发现过期, `returned` 或者说 `request`,并导出为 `CAUSE`。 。 。 .
-   `user`数字 : `{ id, firstName, lastName, email }` 从 `auth.getUserInfo`,已获取 第一次组件询问并保存。 在它到达之前没有定义.
-   `userUnavailable`: 无法获取用户时为真 .
-   `signIn()`: 重新装入页面.
-   `signOut()`: 到登录代理服务器 `sign_out` 在应用程序自己的主机上 结束会话和身份提供者,然后回到 页面,该页面要求用户再次签名. `signOutUrl` 编辑 供货商把它送到别的地方.

`dialogComponent` 将对话框替换为应用程序的自有对话框, 它得到 `open`, (中文(简体) ), `onSignIn` 财务报告和审定财务报表 `labels`一个MUI的应用程序从 `@faybl/react-utils/mui`,该应用的主题为:

```jsx
import { MuiSessionExpiredDialog } from '@faybl/react-utils/mui';

<SessionProvider client={client} dialogComponent={MuiSessionExpiredDialog}>
```

处理过期本身的应用程序仍然可以使用对话框 :

```jsx
const SessionNotice = () => {
  const { expired, signIn } = useSession();
  return <SessionExpiredDialog open={expired === true} onSignIn={signIn} />;
};
```

## 顶端的栏杆

`@faybl/react-utils/mui` 拥有每家Faybl应用软件的分红, 用MUI和应用程序的主题绘制 。 他们需要 `@mui/material` 财务报告和审定财务报表 `@mui/icons-material`。 。 。 .

| 构成部分 | 显示什么 |
| --- | --- |
| `MuiUserMenu` | 用户的外观,带有显示账户和签名的菜单 |
| `MuiAppSwitcher` | 租户的网络应用程序作为链接的网格,当前一个标记 |
| `MuiConnectionStatus` | 生活或离线,从 `connected` |
| `MuiColorSchemeToggle` | 光和暗之间的开关 |
| `MuiTopBar` | 应用程序的图标、标题和内容,然后上面的四块 |

`MuiTopBar` 固定的顺序: 应用程序 `start`, (中文(简体) ), `icon`, (中文(简体) ), `title`, (中文(简体) ), `subtitle` 财务报告和审定财务报表 `children` 左侧,然后连接,颜色方案,应用程序切换器和用户 菜单。 每块有自有名的道具. 离开或 `false`,这个是 不在这里; `true`它与它的默认一样,它与一个对象 这些道具。 仅 `userMenu` 默认存在。 其他的道具都归MUI `AppBar`,所以酒吧可以是 `position="fixed"` 或拿自己的钱 `sx`。 。 。 .

```jsx
import { useConnection, useDeploymentInfo } from '@faybl/react-utils';
import { MuiTopBar, MuiUserMenu } from '@faybl/react-utils/mui';

// A customer app: title, connection and the user menu.
<MuiTopBar title="Maskin Mekano" connectionStatus={{ connected: useConnection({ client }) }} />

// An internal tool: also the other apps and the colour scheme.
const info = useDeploymentInfo({ url: `${import.meta.env.BASE_URL}faybl/deployment-info.json` });
<MuiTopBar icon="settings" title="Configuration" appSwitcher={{ apps: info?.apps }} colorSchemeToggle />

// With what the app shows now beside its name.
<MuiTopBar icon="timeline" title="Data streamer" subtitle={dashboardTitle} appSwitcher={{ apps }} />

// A bar of the app's own.
<Toolbar>…<MuiUserMenu picture="gravatar" showAccount={false} /></Toolbar>
```

`icon` 是下方列表中的名称 [部署信息](https://npmcn.com/package/%40faybl/react-utils/#readme-deployment-info),则 和应用程序的开关一样. `subtitle` 应用程序现在显示, 比如一个仪表板的名字。 当房间耗尽 字幕先缩短, 然后是标题,两个都带有椭圆;片段从不收缩. 片子保留它的位置,隐藏, 而它显示的是加载,所以 栏不会在用户或应用程序列表到达时移动.

`MuiUserMenu` 从 `useSession`,所以它需要 `SessionProvider` {\\fn华文仿宋\\fs16\\1cHD1D1D1}在它上面 显示首字母,或与 `picture="gravatar"` 用户的 地心引力,回落到初始. Gravatar是选入的,因为它发送一个 每个用户给外部服务的一散列邮件。 除了它显示的外形 名称和电子邮件,但窄屏幕除外; `showAccount={false}` 离开他们 出来. `children` 在签出前添加菜单项 。 当无法获取用户时 菜单显示一个平面的外观, 并且仍然在签名.

`MuiConnectionStatus` 仅计数 `connected === false` 作为下线,因为 `useConnection` 在第一次报告前未定义。 在狭长的屏幕上显示 独自一个图标.

`MuiColorSchemeToggle` 需要一个主题 `colorSchemes`。 。 。 .

每一块都要 `labels`,默认英语 :

| 构成部分 | `labels` |
| --- | --- |
| `MuiUserMenu` | `{ account, signOut }` |
| `MuiAppSwitcher` | `{ apps }` |
| `MuiConnectionStatus` | `{ live, offline }` |
| `MuiColorSchemeToggle` | `{ dark, light }`,以方案命名,单击开关 |

## 部署信息

每个Faybl的网络应用都服务于部署中所说的租户 `<app path>/faybl/deployment-info.json`。 。 。 . `useDeploymentInfo({ url })` 读出来 单次 `url`数字 :

```json
{
  "faybl": { "version": "1.0.0" },
  "auth": { "enabled": true },
  "apps": [
    {
      "name": "conf-ui",
      "label": "Configuration",
      "icon": "settings",
      "path": "/conf-ui/",
      "version": "1.0.3"
    }
  ]
}
```

读时未定义. 没有 `url`,或者当文件不能是时 读取,它没有应用软件,所以应用程序切换器不在那里;通过不 `url` 当地 发展。 只有这些字段被保存,一个没有 `name`, (中文(简体) ), `label` 或一个 `path` 在页面上自己主机被删除,最多50个应用程序被读取.

`icon` 这是其中之一 `apps`, (中文(简体) ), `settings`, (中文(简体) ), `chart`, (中文(简体) ), `play`, (中文(简体) ), `dashboard`, (中文(简体) ), `factory`, (中文(简体) ), `map`, (中文(简体) ), `queryStats`, (中文(简体) ), `timeline` 财务报告和审定财务报表 `science`; 任何其他变成 `apps`。 。 。 .

## 常见问题

### @faybl/react-utils 是什么？

Faybl 网络应用程序的反应钩和组件

### 如何安装 @faybl/react-utils？

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

### @faybl/react-utils 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/faybl\_\_react-utils 是否存在。

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

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

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

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

@faybl/react-utils 使用 TBD 许可。声明的许可为 TBD，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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