# @fairshare/ui-kit 中文文档

规范地址：https://npmcn.com/package/%40fairshare/ui-kit/

版本：0\.12\.0
npm 元数据更新时间：2026-11-07T21:27:46.460Z
中文译文更新时间：2026-11-14T09:23:34.762Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：275 kB，94 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：7 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@firebase/app ^0\.16\.0，@firebase/auth ^1\.13\.0
- 首次发布：2026-09-11T13:19:32.057Z
- 最新版本发布：2026-11-07T21:27:46.347Z
- 近 30 天下载量：3431（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

一个定制的,可访问的 React UI 工具包.

## 安装

```sh
npm install @fairshare/ui-kit
```

也可以使用：`pnpm add @fairshare/ui-kit`、`yarn add @fairshare/ui-kit`、`bun add @fairshare/ui-kit`

## README

# 硅

一个定制、可访问和完全输入的React组件库。 它将核心的UI原始相配上更高级的构件,都可以通过CSS自定义属性来进行主题.

## 安装

```sh
npm install @fairshare/silicon
```

React和React DOM是同级依赖关系. 反应18和19得到支持.

图标来自Font Cousidon Pro(工具箱规范,固件规范 `IconByName` 财务报告和审定财务报表 `IconPicker`因此,安装需要 Pro npm 标志。 点 `@fortawesome` 在Font Wousne 的注册中显示范围( 此 repo ) `.npmrc` 并设定一个符号:

```sh
npm config set "//npm.fontawesome.com/:_authToken" YOUR_TOKEN
```

## 使用

在应用程序根附近导入样式表, 然后从包中导入组件 :

```tsx
import '@fairshare/silicon/styles.css'
import { Badge, Button, Card } from '@fairshare/silicon'

export function Project() {
  return (
    <Card title="Project" extra={<Badge variant="success">Active</Badge>}>
      <Button>Open</Button>
    </Card>
  )
}
```

包船作为无害环境管理,包括类型脚本申报.

## 构成部分

-   原始内容: Antonion, Avatar, Badge, Banner, Board, Breadcrumbs, Button, Card, Checkbox, Combobox, Dialog, Drawer, 可编辑文本, 字段, 过滤器, IconPicker, 输入, 标签, Menu, Meter, 数字字段, PGination, Popover, 进步, RadioGroup, Row Menu, 选择, 设置, Skeleton, 滑动器, Spinner, Switch, Table, Tabs, Tabs, Tag Input, Toast, Tooltip
-   构件: Agent status, ReceptGate, 附件,分支, ChainOfThought, Ceckpoint, CodeBlock, CommunityBadge, Connecting, Connecting, Connecting, Connecting, DiffView, 反馈按钮, InlineCitation, Message Actions, OrgSwitcher, Plan, 即时输入, 队列, simmer, Sidebar, Source, StackTrace, StattCard, 流图, SuggrectingChip, 终端, TestResults, ThinkingBlock, TokenMeter, ToolCallTimline, 树, 用户Profile, WebPreview

组件道具和辅助数据类型从同入站输出.

### 桌面窗口

`WindowManager` 提供可拖放、可调整的有界限的工作空间 `AppWindow` 表面 。 启动开发服务器并访问 `/#windows` 主题 演示(演示还带有暗模式切换).

```tsx
import { Button, WindowManager } from '@fairshare/silicon'

<WindowManager
  windows={[
    {
      id: 'notes',
      title: 'Notes',
      defaultBounds: { x: 24, y: 24, width: 440, height: 320 },
      content: <textarea aria-label="Notes" />,
    },
  ]}
  style={{ height: 600 }}
>
  {manager => <Button onClick={() => manager.open('notes')}>Open notes</Button>}
</WindowManager>
```

-   将标题栏自由拖过工作空间边缘;窗口可部分保留 关闭屏幕, 一个小标题栏抓取 保持可见的释放。 桌面剪贴板 关闭屏幕内容 。 调整任何边角大小 。 指针取消后退 手势。 双击标题栏以最大化或恢复.
-   将指针拖入工作空间左或右边缘的 24px 以预览 a half-width 版式; 预览在两个侧边外保持活性。 释放 来抓 逃避或指针取消 预览。 拖住一个被撕裂的标题栏可以恢复其浮动大小.
-   每个标题栏都有 **安排** 菜单 **左半边**, (中文(简体) ), **右半边**,以及 **恢复浮动窗口**。在标题栏聚焦的情况下, Alt + 左/右坐标 和 Alt + Down 恢复。 演示会 **并肩作战** 按钮安排两个应用程序.
-   **同步辅助** 提供空半边的其他打开或最小化窗口. 选择一个组成一对。 逃逸,解开按钮,或点击外部 拾取者离开第一个窗口被打破。 不包括关闭的窗口; 没有拾取器 当没有符合条件的窗口或水平空格不足时出现.
-   佩尔德窗口共享一个分割器. 拖放以调整两者的大小, 尊重 两个最小宽度。 聚焦并使用左/右 (10px), 家/端(限制),或 双击重置为等分之一。 越狱/点球员取消 分数拖放。 比例仅在拖曳完成时保存 .
-   `snapPair` 内 `WindowManagerState` 保留对子及其比例。 分裂者 当窗口最小化/最大化或工作空间太窄时隐藏, 然后当两者可见时返回。 浮动、关闭或去除一对 窗口溶解对子。 App 内容通过配对保留挂载.
-   自定义 shell 可以使用 `snapAssistId`, (中文(简体) ), `completeSnapAssist(id)`, (中文(简体) ), `dismissSnapAssist()`,以及 `setSplitRatio(ratio)`。 。 。 . `SnapAssist` 导出为 a 演示文稿选取器. 皮克州是短暂的,没有坚持下去.
-   使用 `manager.snap(id, 'left' | 'right')` 财务报告和审定财务报表 `manager.restore(id)` 习惯 任务栏。 Snaping 保持了正常的边框并包含在保存的布局中,通过 选项 `snap` 属性。 最大化崩溃窗口并恢复它 返回到该半个;通过排列返回到浮动边界.
-   抓取了一半的工作空间大小 。 如果工作空间窄于两次 一个窗口 `minWidth`,而一个已断开的窗口则使用全宽并 当空间可用时,返回到它的一半。 边缘抓取和菜单动作 按此大小被禁用; 程序 API 仍然可以选择快取一面.
-   标签到标题栏并使用箭头键来由 10px 移动,或 将 Shift + 箭头移动到 调整大小 。 窗口控制有可访问标签 。 聚焦内容提升了它的窗口.
-   最小化保存应用程序内容 。 关闭卸载; 重新打开使用 它保留了界限,但含有新的内容。 应用程序拥有未保存的更改处理. 设定 `closable: false` 以省去亲密动作.
-   `minWidth` 编号 : `minHeight` 默认为 240 / 160px。 工作空间界限 当取景端较小时优先。 调整工作空间的大小 普通并恢复内部的界限; 扩展后不会恢复已丢弃的几何.
-   `defaultLayout` 恢复一个 `WindowManagerState`· ; `onLayoutChange` 初次报告 状态和随后的变化。 该应用程序拥有验证和持久性. 尽可能使用独特而稳定的ID并记住窗口定义.
-   `useWindowManager` 揭露关于自定义贝壳的状态和行动; `AppWindow` 实值 也可作为定位母体内的受控组件。 供应 父的维度为 `area` 当它直接使用.

工作空间切换、生产任务栏/开始菜单和自动 存储被故意留给下一层。 视窗是非模式的,并做 而非陷阱焦点;嵌入式跨源框架拥有其内部焦点行为.

## 公平共享应用程序

`@fairshare/ui-kit/app` 是 FairShare 应用程序的客户端,其服务器 用途 [碳](https://github.com/FairShare-Software/carbon)它涵盖:

-   仅邀请登录身份平台,使用设置 `/api/config`· ;
-   aPI 客户端发送 ID 令牌, 当它被刷新一次 被抛弃,如果它再次被拒绝,就签出字来;
-   页面助手.

这需要 `@firebase/app` 财务报告和审定财务报表 `@firebase/auth`,是可选对等点 依赖性:只使用组件的应用程序不需要.

```tsx
import '@fairshare/ui-kit/styles.css'
import '@fairshare/ui-kit/app.css' // page layout: .shell, .page, .form, ...
import { start } from '@fairshare/ui-kit/app'

start({ name: 'Neon', noAccount: 'Ask an administrator to invite you.', app: (user) => <Shell user={user} /> })
```

页面使用 `api`, (中文(简体) ), `useGet`, (中文(简体) ), `ApiError`, (中文(简体) ), `Page`, (中文(简体) ), `LoadError`, (中文(简体) ), `useChange`, (中文(简体) ), `when` 财务报告和审定财务报表 `logout` 从同一条目。 保留 `/config`,401处理和 页:1 `/api` 前缀与碳同步.

## 他们

覆盖软件包的 CSS 自定义属性 :

```css
:root {
  --ui-accent: #6d4aff;
  --ui-accent-hover: #5938df;
  --ui-radius: 0.5rem;
  --ui-font: Inter, system-ui, sans-serif;
}
```

暗模式默认遵循系统偏好. 强制主题 `data-theme="dark"` 或者说 `data-theme="light"` 祖先,例如 `<html>`。 。 。 .

### 密度

对于数据重的屏幕,设置 `data-density="compact"` 打开 `<html>` (或任何祖先)将高地减半 平板和控制高度的尺度,堆放的块之间的间隙也是如此;图标到标签的间隙保持不变. 高地平面保持最小的相位,因此保持室外:Dialog和Drawer在0.75x站,Popover站和Toast在0.5rem站. 对于自定义密度, 设置 `--ui-space` 直接; `1` 是默认,并且 `0.5` 是紧凑的 :

```css
.my-grid {
  --ui-space: 0.75;
}
```

大小 : `--ui-control-h` (32 / 26px,窗体控件和默认按钮), `--ui-control-h-sm` (24) / 20px, 小内线动作; `<Button size="sm">` 财务报告和审定财务报表 `<Button size="sm" iconOnly>`),以及 `--ui-header-h` (36 / 28.px,头条的最低高度). 文本使用 `--ui-line-height` (20px)和 (中文(简体) ) `--ui-line-height-sm` (16px,用于0.75rem文本和更小的文本),所以排到整像素上,不管页面的行高.

弹出成 `<body>`,因此设定密度 `<html>` 如果菜单、选择和对话框都跟着它.

## 发展

```sh
npm install
npm test
npm run build
```

## 许可证

麻省理工学院

## 常见问题

### @fairshare/ui-kit 是什么？

一个定制的,可访问的 React UI 工具包\.

### 如何安装 @fairshare/ui-kit？

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

### @fairshare/ui-kit 支持 TypeScript 吗？

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

### @fairshare/ui-kit 支持 ESM 还是 CommonJS？

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

### @fairshare/ui-kit 需要什么版本的 Node\.js？

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

### @fairshare/ui-kit 可以商用吗？

@fairshare/ui-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fairshare/ui-kit 的下载量有多少？

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

### @fairshare/ui-kit 还在维护吗？

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