# @collective-intelligence/ui-react 中文文档

规范地址：https://npmcn.com/package/%40collective-intelligence/ui-react/

版本：0\.2\.2
npm 元数据更新时间：2026-11-09T00:11:13.362Z
中文译文更新时间：2026-11-10T11:14:31.731Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40collective-intelligence/ui-react
原文对照：https://npmcn.com/package/%40collective-intelligence/ui-react/?lang=original

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

- 包体积（解压后）：1.3 MB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：45 个
- peer 依赖：react \>=18 \<20，react-dom \>=18 \<20，react-hook-form ^7\.72\.1，@tanstack/react-query \>=5\.0\.0
- 首次发布：2026-10-08T14:19:29.072Z
- 最新版本发布：2026-11-09T00:11:12.992Z
- 近 30 天下载量：5645（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

公共反应原始,设计-系统组件,图标,插图,以及集体智能应用的公用事业.

## 安装

```sh
npm install @collective-intelligence/ui-react
```

也可以使用：`pnpm add @collective-intelligence/ui-react`、`yarn add @collective-intelligence/ui-react`、`bun add @collective-intelligence/ui-react`

## README

# `@collective-intelligence/ui-react`

公开的、可获取的反应原始和集体情报设计 集体情报应用系统.

该软件包保留了设计系统源结构 `src/components/`,包括: `ui`, (中文(简体) ), `ui-extensions`, (中文(简体) ), `icons`,以及 `illustrations`,加上共享的钩子,公用事业和主题符号. 这个 `/resources` 入口包含通用表格、列表、过滤器、页码、, 对话 动作原始人.

所有组件接受显示准备道具,不获取数据, 自有 认证,或依赖于私人 CI 包. 反应和反应 DOM 保留 相对依赖.

`react-hook-form` 也是对等关系, 并且被排除在浏览器之外 预备 消费者必须提供 所以公众 `Form` 供应商及其 窗体钩子具有相同的上下文.

`bun run build` 为公布的入境点制作JSX,同时 保持回放和回放 DOM 外部。 这些文物支持消费者使用 生产或开发 反应。 建成后, `bun run test test/built-runtime.test.ts` 用两种模式验证渲染.

`react-markdown` 仍然是正常运行时间的依赖,仅排除在外 从此软件包的浏览器预捆绑。 浏览器和服务器侧渲染 消费者解决自身运行时间的依赖性,只保留浏览器 DOM 代码出自服务器导入 .

已公布的入口共享运行时间块 `dist`; 分发 目录完整无损。 这使得模式焦点和指向锁定状态在 编织原始人来自 `/ui` 对话框来自 `/ui-extensions`。 。 。 . `bun run test:pack` 重建软件包并检查此交叉输入点 模式生命周期和消费者形式背景,然后验证包装的消费者.

## 受控实体列报

导入共享实体演示文稿 `@collective-intelligence/ui-react/resources`。 。 。 . Dashboard的私人CRUD包装和外部消费者使用相同的表格, 列表、过滤布局、页码和对话框执行。 数据加载, 授权, URL状态, 选择, 草稿和变异属于呼叫者 .

`ResourceTablePrimitive` 取行、列、稳 `getRowKey`,以及 `renderCell`。可选行动作、上下文菜单和细节渲染器接收 同一行 同一行吗? 动作点击不激活行;行激活支持 Enter 和空间。 被扩展和选定的状态由调用者调用控制. `ResourceListPrimitive` 接受稳定的项键和可选的容器插槽. `ResourceFiltersBar` 规定了呼叫者拥有的控制,同时 `ResourcePaginationPrimitive` 支持上个/下一个并被控制 页面。 待定的控制措施仍然失效。 过 `navigationLabel` 以本地化 导航的可访问名称(默认为 `Resource pagination`页:1 `previousLabel`, (中文(简体) ), `nextLabel`,以及 `ellipsisLabel` 用于控制.

`ResourceDialogPrimitive` 默认使用现有的焦点管理对话框; 通过 `open`, (中文(简体) ), `onOpenChange`, (中文(简体) ), `title`选择 `description`明确 自定义 `Dialog` 仍可提供插槽,重点管理由该插槽拥有 替换.

`ResourceFormPrimitive` 使显示准备好 `ResourceField` 元数据、数值、, 字段错误和回调。 内置控制覆盖文本/电子邮件、数字、, 布尔斯, enum 选项, 日期/ 日期字符串和明确无效的清除 . 数字和布尔语保留其JSON值类型. 自定义控件收到 相同值/更改、已禁用、只读、需要和错误元数据;计划 推论和登记查询与打电话者保持联络。 不支持的自定义控制 明确显示。 提交表格的代表确认和坚持 ; 演示文稿从未构建客户端或查询客户端.

`ResourceListPagePrimitive` 从呼叫者拥有的空档中选择一具尸体 `status` (单位:千美元)`pending`, (中文(简体) ), `error` 或者说 `ready`和 `totalItems`数字 : `loading` 初入涅盘时, `error`, (中文(简体) ), `nothingYet` 对于一个空列表, `noResults` 何时 `hasActiveQuery` 实值 设置, 否则 `children`选项 `toolbar` 以行和行显示 `noResults`。通过 `paging` (单位:千美元)`page`, (中文(简体) ), `totalPages`, (中文(简体) ), `onPageChange`)和可选 `pagination` 在一个页面上显示的寻呼器的标签。 当当前 页面已消失, 列表询问 `onPageChange` 最后一页. `isRefetching` 标记背景刷新方式 `aria-busy`。内容在 仅用于替换加载槽.

`ResourceAdvancedFilters` 将相撞的高级过滤区域添加到 `ResourceFiltersBar`。通过永远可见的 `primary` 控制器,用于 `advanced` 内容, 内容 `activeCount` 和本地化 `labels`可选 `activeFilters` 制造可移动芯片, `onClear` 重置每个过滤器,以及 当过滤器活动时默认打开区域或 `defaultOpen` 已经设定。 这个 调用器拥有过滤状态和 URL 同步 .

运行 `bun run build-storybook` 用于交互式 **资源/控制 实体/ 行程** 实例. `bun run test:pack` 检查这些出口 在孤立的外部消费者中包装了JavaScript和声明.

## 错误提醒

导入 `ErrorAlert` 从 `@collective-intelligence/ui-react/ui-extensions`。 。 。 . 它构成现有的破坏力 `Alert` 和 Radix 键 `Collapsible` 原始的 原始的 原始的. 传送可见消息为 `children`,可选 `title`,可选 `details` 含有触发的物体 `label` 和任意反应 `content`。 。 。 . 选择 `details` 删除披露触发器及其面板.

```tsx
import { ErrorAlert } from "@collective-intelligence/ui-react/ui-extensions"

;<ErrorAlert
  title="Connection failed"
  details={{
    label: "Technical details",
    content: (
      <pre className="whitespace-pre-wrap break-words">{diagnostics}</pre>
    )
  }}
>
  The service could not be reached. Please try again.
</ErrorAlert>
```

细节开始关闭。 使用 `defaultOpen` 最初扩大的小组, 或者说 `open` 与 `onOpenChange` 来控制它 标签、翻译、诊断 格式和错误的恢复仍由调用者负责。 使用 `className` 财务报告和审定财务报表 `classes` 用于自定义根部分和个人演示部分.

## 写土司失败

导入 `ciWriteFailedToast` 财务报告和审定财务报表 `Toaster` 从 `@collective-intelligence/ui-react/ui`。 。 。 . `ciWriteFailedToast(messages?)` 返回时 处理器 `onWriteFailed` 参考文献 `CollectiveIntelligenceProvider` (单位:千美元)`@collective-intelligence/external-apps-client-sdk-react`) (中文(简体) ). 接线员打电话来 `toast.error` 使用一个文本:

-   对a `CiError`,其英文文本 `code`。 。 。 .
-   对a `CiTransportError`,一个英文连接文本。 它没有说改变是 未保存 : 当一个写入的答案丢失时, CI 可以保存它 .

使用其他文本,例如另一种语言,通过 `messages` (单位:千美元)`CiWriteFailedMessages`) (中文(简体) ). 它的钥匙是 `CiError` 代码和 `transport`A级 键,您不会给它保留英文文本.

```tsx
import {
  Toaster,
  ciWriteFailedToast
} from "@collective-intelligence/ui-react/ui"

const onWriteFailed = ciWriteFailedToast({
  conflict: "Quelqu'un a modifié cet élément.",
  transport:
    "Pas de connexion. La modification n'est peut-être pas enregistrée."
})

;<CollectiveIntelligenceProvider client={client} onWriteFailed={onWriteFailed}>
  <App />
  <Toaster />
</CollectiveIntelligenceProvider>
```

处理者只读 `_tag` 财务报告和审定财务报表 `code` 错误 (单位:千美元)`CiWriteFailedEvent`),因此这个软件包并不依赖于客户端SDK. 这个 土司节目 `Toaster` 只有当应用程序有此软件包的一个副本时: 两份有两家烤面包店 因此,SDK的客户端 反应有 此软件包作为对等依赖.

## 卡片选项

导入 `CardOptionsBlock`, (中文(简体) ), `CheckboxCardOption` 财务报告和审定财务报表 `RadioCardOption` 从 `@collective-intelligence/ui-react/ui-extensions`。每个选项都是带有 (单位:千美元) `title`,可选 `description` 及其控制;单击 牌会更改值, 也在 a 内 `<form>`。 。 。 .

```tsx
import {
  CardOptionsBlock,
  CheckboxCardOption
} from "@collective-intelligence/ui-react/ui-extensions"

;<CardOptionsBlock>
  <CheckboxCardOption
    checked={selected}
    title="Studio: Use agent conversations"
    description="Capability to use Studio. It adds no permission that a run uses."
    wrapDescription
    onCheckedChange={setSelected}
  />
</CardOptionsBlock>
```

描述显示在一条短线上. 设定 `wrapDescription` 来展示它 满地都是线条. `CheckboxCardOption` 财务报告和审定财务报表 `RadioCardOption` 链接 说明其控制方式 `aria-describedby`与 `CardOption` (单位:千美元) 自定义 `control`,通过一个 `descriptionId` 并设置与 `aria-describedby` 由你来控制.

## 视频播放器

导入 `VideoPlayer` 以自己的归宿盟誓, `@collective-intelligence/ui-react/ui-extensions/video-player`它使一个 `<video>` 并播放稳定媒体 URL(`…/media/{ownerKind}/{ownerId}…`: 当视频的渲染准备就绪时适应性HLS,否则存储的文件. 过 `src`,当地人 `<video>` 属性( e)`controls`, (中文(简体) ), `poster`, (中文(简体) ), `autoPlay`, (中文(简体) ), `aria-label`,(......), `className` 财务报告和审定财务报表 `classes.root`说明 `<track>` 孩子们.

```tsx
import VideoPlayer from "@collective-intelligence/ui-react/ui-extensions/video-player"

;<VideoPlayer
  aria-label="Product walkthrough"
  controls
  requestHeaders={() => ({ Authorization: `Bearer ${token}` })}
  src={file.mediaUrl}
/>
```

全权证书由消费者持有:

-   与 `requestHeaders`,玩家问 `src` 与 `stream=hls`,则 调用回信头和 `credentials: "omit"`播放列表答案开始 hls.js,它只将信头添加到 URL 的源头 `src` 财务报告和审定财务报表 `/media/` 路径。 任何其他答案是存储的文件: 玩家播放 后续重定向的最终 URL .
-   无 `requestHeaders`时,玩家会问 `credentials: "include"` 财务报告和审定财务报表 `redirect: "manual"`,而hls.js只向同一API发送证书 媒体 URL. 重定向( 溪流尚未准备好) 或任何其他答案 允许 元素负载 `src` 与会话饼干.
-   在媒体主机上发送 URL 从未收到信头、 证书或 查询字符串。 没有媒体源扩展的浏览器只使用本地 HLS 与 cookie; 用信头调回它播放存储的文件 .
-   当一个片段回答 403(其交付 URL 随着其访问而过期) 窗口(Window),玩家在当前位置上重新装入一次流.

页面来源必须被 API CORS 政策允许进行认证 请求; 否则玩家会回到元素加载 `src`。 。 。 .

**例外为"不获取数据".** 玩家探测到一个 URL 消费者通过,在流和存储文件之间选择. 那个探测器 是媒体传输,而不是数据访问:它没有建立自己的URL,读取否 符号和构造不包含客户端.

hls.js (英语:`hls.js/light`)被捆绑在自己的块并被动态加载 仅导入带有媒体源扩展的浏览器上的已准备好的流 其它切入点和玩家自己的块并不包含. 它的 Apache- 2.0 通知船舶在 `THIRD-PARTY-NOTICES.md`。 。 。 . `bun run test:pack` 检查 块块和通知 在包装的文物.

## Enum 值迁移

仓库自有组成部分选项的使用 `snake_case`更新 `Card.visual` 从 `accent-gradient` 改为 `accent_gradient`· ; `InputGroupAddon.align` 从 `inline-start`, (中文(简体) ), `inline-end`, (中文(简体) ), `block-start`,或 `block-end` 改为 `inline_start`, (中文(简体) ), `inline_end`, (中文(简体) ), `block_start`,或 `block_end`; 和 : `InputGroupButton.size` 从 `icon-sm` 或者说 `icon-xs` 改为 `icon_sm` 或者说 `icon_xs`匹配 `data-align`, (中文(简体) ), `data-size`,以及 `data-visual` 值也使用这些新拼法.

本地 HTML 输入类型保留其协议拼写: 例如, `ResourceField.control` 接受 `datetime-local` 并转发到输入中.

## 常见问题

### @collective-intelligence/ui-react 是什么？

公共反应原始,设计-系统组件,图标,插图,以及集体智能应用的公用事业\.

### 如何安装 @collective-intelligence/ui-react？

在项目目录运行 npm install @collective-intelligence/ui-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18 \<20）、react-dom（\>=18 \<20）、react-hook-form（^7\.72\.1）、@tanstack/react-query（\>=5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @collective-intelligence/ui-react 支持 TypeScript 吗？

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

### @collective-intelligence/ui-react 支持 ESM 还是 CommonJS？

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

### @collective-intelligence/ui-react 可以商用吗？

@collective-intelligence/ui-react 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @collective-intelligence/ui-react 的下载量有多少？

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

### @collective-intelligence/ui-react 还在维护吗？

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