# @gener8v/ui 中文文档

规范地址：https://npmcn.com/package/%40gener8v/ui/

版本：0\.64\.0
npm 元数据更新时间：2026-11-09T17:08:03.499Z
中文译文更新时间：2026-11-16T02:57:06.128Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：992 kB，403 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-08-24T13:57:25.533Z
- 最新版本发布：2026-11-09T17:08:03.243Z
- 近 30 天下载量：4740（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：80（近 12 个月 80 个）

## 中文简介

反应GENER8V设计系统的组件——与其静态HTML相同的类名,因此标出端口或者方向.

## 安装

```sh
npm install @gener8v/ui
```

也可以使用：`pnpm add @gener8v/ui`、`yarn add @gener8v/ui`、`bun add @gener8v/ui`

## README

# @ gener8v/ ui (英语)

GENER8V设计系统的反相层.

```bash
npm i @gener8v/ui          # public on npm, MIT
```

```tsx
import '@gener8v/ui/styles.css';   // once, at the app root
import { Button, Flow, BarChart } from '@gener8v/ui';
```

## 唯一能理解的东西

**这些组件制造出与设计系统的静态HTML相同的类名.**

```html
<!-- design/components/buttons.html -->
<button type="button" class="btn btn-primary">Continue</button>
```

```tsx
<Button variant="primary">Continue</Button>
// → <button type="button" class="btn btn-primary">Continue</button>
```

这不是巧合,也不是装饰,而是整个系统的财产 被构建在周围。 HTML针对设计系统所写(包括HTML Claude生成, 因为 `design/readme.md` 教它这些课) 掉入一个没有视觉效果的 React app 重写. 这里的某个部件 永远不能悄悄地与记录的外观相去甚远 因为 `pnpm lint:parity` 如果静态 HTML 使用一个组件无法发射的类,则失败.

如果你发现自己增加了一个 `className` 没有在 `design/styles.css`停下来 无论是 该类属于系统——添加到 `packages/tokens/src/components/` 和预览 页面 —— 或者您正在本地设置一些不应该在本地化的样式 .

## 这个坐在哪里

```
packages/tokens/src/theme.mjs      the source of truth — 135 tokens
        │
        ├──▶ design/styles.css     the only stylesheet; shipped here as dist/styles.css
        │            │
        │            ├──▶ design/**.html     static pages, the visual reference
        │            └──▶ @gener8v/ui        this package — same classes
        │
        ├──▶ @gener8v/tokens       the same values as JS/JSON, for logic
        └──▶ @gener8v/tailwind-preset   the same values as Tailwind utilities
```

`@gener8v/icons` 独立 – 有18个 Phospphor glyphs, 不依赖此包.

## 这里有什么

52个家庭共出口267个. 值得我们了解的:

| 区域 | 出口 |
| --- | --- |
| 行动 | `Button` `ButtonGroup` |
| 表面 | `Card` `CardLink` `Panel` `Tag` |
| 表单 | `Field` `Input` `Textarea` `Select` `Combobox` `Checkbox` `Radio` `Switch` `Slider` `FileUpload` `TokenInput` `Quantity` `RadioCard` |
| 导航 | `Nav` `Sidebar` `Breadcrumbs` `Tabs` `Tree` `Hamburger` `Drawer` `PagerChip` `Contents` `Menu` `CommandPalette` `Kbd` `ShortcutList` `useListKeys` |
| 流动 | `Flow` `Stepper` `Progress` `Meter` `Timeline` `Feed` `Lanes` `LiveProgress` `LiveIndicator` `Pulse` `LiveMark` `LiveSection` `State` `StateArt` `useStepValidation` `ErrorSummary` |
| 反馈 | `Dialog` `Alert` `Toast` `ToastProvider`编号 :`useToast` `Tooltip` `Popover` `HoverCard` `useDelegatedHoverCard` `Callout` `ToolChip` `ConfirmCard` |
| 数据 | `Table` `usePagedTable` `TablePager` `Matrix` `Diff` `Stat` `DescriptionList` `Avatar` `BarChart` `LineChart` `Sparkline` `KnowledgeGraph` `LayeredGraph` |
| 图书馆整合( I) | `DocList` `DocPreview` `Reader` `Citation` `SourceCard` `Connection` `Credential` `KeyRow` `Rule` |

`design/components/*.html` 显示他们中的每一个人。 查看来源并复制标记.

## 本套方案所持公约

**国家住在亚细亚,不是阶级.** `NavItem` 带 `current` 发送 `aria-current="page"`· ; `Th` 带 `sort` 发送 `aria-sort`· ; `Input` 带 `invalid` 财务报告和审定财务报表 发射 `aria-invalid`。 CSS 样式属性。 没有 `.is-active`图像 而无障碍树不能飘散.

**可获取性按可能的类型实施.** 仅限图标 `Button` 需求 `aria-label` ——这是一个编译错误,没有一条,不是评论.

**行为是真实的,或者组件说它不是.** `Dialog` 财务报告和审定财务报表 `Drawer` 份额 `useModalBehavior`: 逃脱关闭,焦点移动并返回到触发, Tab 周期, 背景卷轴锁有用于筑巢的深度计数器. `Tabs`, (中文(简体) ), `Tree`, (中文(简体) ), `Menu`, (中文(简体) ), `Combobox` 财务报告和审定财务报表 `Calendar` 各自执行完整的WAI-ARIA键盘合同. 何处 有件事真的没有完成—— `Tooltip` 船体表面,但没有碰撞意识 定位——医生的评论是这样说的,而不是假装.

**原生元素无论存在在哪里.** `Slider` 实值 `<input type="range">`· ; `FileUpload` 隐藏真实文件输入 `.sr-only`永远 `display: none`,所以它会留在 选项卡顺序。 重用这些会丢失键盘行为、 值宣布和窗体 参与,并且通常至少得到其中的一个错误.

**跨越边界的日期为 `YYYY-MM-DD` 字符串**永远 `Date` 对象。 A 类 `Date` 带有时间和区;日历日期没有.

**一个蒙面的秘密不在DOM中.** `Credential` 生成一个替换字符串,并且仅 挂载一旦披露的真实值—— CSS 口罩在标记和任何 DOM快照.

## 同伴依赖关系

反应出18或19. 没有别的——没有组件库,没有图标集,没有图表库,没有 形式验证库。 这是故意的:每个消费者都会继承 选择设计系统对应用程序没有业务影响.

## 换个东西

这个包是一个来源的六个产出之一。 之前读取寄存器根 README 编辑, 运行 `pnpm check` 在调用任何已做的工作之前, 并增加该类 `packages/tokens/src/components/` 加上预览页 `design/components/` - 一个组成部分 显示设计系统不记录的类别 将失败等同门.

## 常见问题

### @gener8v/ui 是什么？

反应GENER8V设计系统的组件——与其静态HTML相同的类名,因此标出端口或者方向\.

### 如何安装 @gener8v/ui？

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

### @gener8v/ui 支持 TypeScript 吗？

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

### @gener8v/ui 支持 ESM 还是 CommonJS？

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

### @gener8v/ui 可以商用吗？

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

### @gener8v/ui 的下载量有多少？

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

### @gener8v/ui 还在维护吗？

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

