# @gears-frontx/ui-kit 中文文档

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

版本：0\.5\.1
npm 元数据更新时间：2026-11-11T18:41:22.528Z
中文译文更新时间：2026-11-16T01:33:47.704Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：3.2 MB，1237 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：14 个
- peer 依赖：react ^19\.0\.0，exceljs ^4\.4\.0，react-dom ^19\.0\.0
- 首次发布：2026-08-07T04:51:53.603Z
- 最新版本发布：2026-11-11T18:41:22.278Z
- 近 30 天下载量：2732（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

FrontX 模板的标准反应组件基础 - Base UI行为, CSS 模块在语义符号上的造型, CVA 变体

## 安装

```sh
npm install @gears-frontx/ui-kit
```

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

## README

# @gears-frontx/ ii- kit (英语)

FrontX模板的标准反应组件基础. 模板构建 从中筛选并通过依赖性凸出接收修正和设计更新; 模板可以混入其他组件,其他公司可以插入自己的组件 装入自己的模板.

-   **堆叠 :** 反应19 + 碱UI + CSS 模块 + CVA
-   **自足风格 :** 编译的包装船 CSS——消费者不需要 CSS 框架、预处理器或构建插件
-   **自定义 :** 通过 CSS 可变符号进行基本品牌; 深度变化=分叉

## 使用量

```ts
// once, in the consumer entry module
import '@gears-frontx/ui-kit/theme.css'; // design tokens (CSS variables)

// two optional global stylesheets, each imported only if you need it:
import '@gears-frontx/ui-kit/utilities.css'; // shimmer, scroll-fade-x, no-scrollbar, sr-only
import '@gears-frontx/ui-kit/typeset.css'; // prose styling for rendered markdown/HTML
```

`utilities.css` 不是每个组件的可选性 : **附录** 取决于 上面写着.. `AttachmentTitle` 添加 `shimmer` 上传时,和 `AttachmentGroup` 滚动其行 `scroll-fade-x` 财务报告和审定财务报表 `no-scrollbar` —— 说 财务报告和审定财务报表 **标记** 配对 `shimmer` 它的流出文本效果。 这些 类是简单的全球CSS,没有组件块可以拉入,所以 如果没有此导入, 它们就成为惰性部件, 部件就直接渲染而无需 影响。 一起导入一次 `theme.css` 如果你使用两个 组件,或想要您自己加价的公用事业.

`typeset.css` 向下显示的样式块或应用程序不显示的 HTML 作者本身 — 聊天信息、 文档、 CMS 内容: 将其包入 `<div class="typeset">`。见 [类型.md](https://npmcn.com/package/%40gears-frontx/ui-kit/src/styles/typeset.md) 联 合 国 预设和节奏变量.

```tsx
import { Button } from '@gears-frontx/ui-kit';

<Button variant="outline" size="sm">
  Save
</Button>;
```

每个部件都装上自己的CSS块,通过进口自动拉入 组件 —— 没有合并样式表可以单独导入。 导入 从软件包根 (`@gears-frontx/ui-kit`)或来自某个组件本身 子路径( n)`@gears-frontx/ui-kit/button`)——双树相摇 _联合来文_ 联 合 国 您不导入的组件, 在每个捆绑器测试( Vite, webpack, 兴起。 对于CSS来说, 哪个摇动是依赖捆绑的: Vite 和 webpack 将未导入组件的 CSS 以任意方式丢弃; 仅安装 通过建造船只将根入捆绑 每个组件的CSS 不管用什么 因为Esbuild收集 CSS 从整个可达到的模块图中取出,而不是同时浏览 未使用的联署材料对联署材料的穿插方式具有约束力。 如果您的建筑直接使用 Esbuild (不是像Vite那样通过一个包起来的框架) 更喜欢子路径 导入您想要的 CSS .

在RSC框架内(Next.js App路由器是主要案例),大多数工具包 由没有工具包侧客户端的服务器组件直接制成 他们只把UI基地的原始人编为JSX, 而Base UI本身的Dist已经 携带 `'use client'` 在调用钩的模块上(交互式原始) 如Select 或 Dialog 仍然飞船 Base UI 的客户端捆绑; 只有套件 环绕它不需要自己的指令). 剩下的直接叫钩子 他们自己造出一面旗帜,然后用自己的块来装上.

装有: `'use client'` 警告, 附件、徽章、面包屑、泡泡、扣子组、卡片、木马、图, CodeBlock, Combobox, 命令, 上下文Menu, DataGrid, DataTable, Data Drawer, Dropdown Menu, 空出, 标题, 输入Otp, 项, 链接, 标记, 页面标题, 侧边栏、状态点、表格、文本、土司、可视隐藏.

其他一切——包括诸如"按钮","checkbox"等交互式原始人, 对话框、 选择、 切换、 无线电组和 Tabs —— 保留服务器可响应; 每个 一个人的客户交互 来自一个基础UI原始 它制造一个 儿童,根据需要确定自己的客户边界。 名单是 在每次测试运行时对照源检查(`src/client-boundaries.test.ts`, (中文(简体) ), 所以它不能悄悄地掉到密码后面.

主题文件画出页面( 背景、 文本、 以及 UA 所拥有表面等) )以及定义符号,所以暗模式在 框中完全没有属性: `prefers-color-scheme` 默认. 作为明确的控制,设置 `data-theme="dark"` 或者说 `data-theme="light"` 打开 `<html>` - 或任何内树上,然后涂上自己的地表 独立于周围的页面.

文本生成于 `--font-sans` (首先,然后是系统倒置),与 `--font-mono` (JetBrains Mono) 为类似代码的文本保留;主题.css集 页面字体本身。 包船没有字体文件——装入Inter/JetBrains 您的应用程序中的 Mono , 用于精确的 Studio 外观( 后退可以辨认) 没有他们。 类型大小来自 Studio 斜坡标志 (单位:千美元)`--text-<role>-size|line-height|weight|tracking`,角色 `display|heading-1|heading-2|body|label|meta|mono`)——自己使用 页面文本.

要重命名, 将 CSS 变量从 `theme.css` 在自己的风格.

## 发展

```bash
npm run build --workspace=@gears-frontx/ui-kit   # vite: dist/index.js + dist/<component>.{js,d.ts} + theme.css, ESM only
npm run test:unit --workspace=@gears-frontx/ui-kit
./packages/ui-kit/scripts/verify-consumer.sh     # pack-install + tree-shaking acceptance check
```

要检查浏览器中未释放的更改, 请将包装的柏油球安装到 在“测试和接受”下描述的抓取页 [设计说明.md](https://npmcn.com/package/%40gears-frontx/ui-kit/design-notes.md)。 。 。 .

见 [设计说明.md](https://npmcn.com/package/%40gears-frontx/ui-kit/design-notes.md) 设计及其历史。 包裹 出版刊物 `alpha` 通过标准版本加码工作流程的频道,同时 其成熟程度:19个组件组是活的,其余的MVP组件在下方 同样的释放前线。 稳定( A)`latest`释放在全MVP上方 成套组件和在495号上批准软件包的架构所有权, 追踪和版本政策——所需的CDSL文物也必须取而代之 临时 `artifacts.toml` 在稳定版本可能被剪切之前忽略.

## 常见问题

### @gears-frontx/ui-kit 是什么？

FrontX 模板的标准反应组件基础 - Base UI行为, CSS 模块在语义符号上的造型, CVA 变体

### 如何安装 @gears-frontx/ui-kit？

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

### @gears-frontx/ui-kit 支持 TypeScript 吗？

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

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

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

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

@gears-frontx/ui-kit 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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

