# @gravity-ui/components 中文文档

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

版本：5\.0\.0
npm 元数据更新时间：2026-10-23T16:02:47.363Z
中文译文更新时间：2026-11-16T23:42:23.764Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.8 MB，1509 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@gravity-ui/uikit ^8\.0\.0
- 首次发布：2023-03-15T14:59:32.374Z
- 最新版本发布：2026-10-23T16:02:47.077Z
- 近 30 天下载量：58376（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：127（近 12 个月 15 个）

## 中文简介

一组复杂的反应组件建在顶部 [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit)部分内容 [重力UI( 重力UI)](https://gravity-ui.com/) 设计系统.

## 安装

```sh
npm install @gravity-ui/components
```

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

## README

# @ gravity-ui/ 组件 [![npm package](https://img.shields.io/npm/v/@gravity-ui/components)](https://www.npmjs.com/package/@gravity-ui/components) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/components/.github/workflows/ci.yml?label=CI&logo=github)](https://github.com/gravity-ui/components/actions/workflows/ci.yml?query=branch:main) [![storybook](https://img.shields.io/badge/Storybook-deployed-ff4685)](https://preview.gravity-ui.com/components/)

一组复杂的反应组件建在顶部 [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit)部分内容 [重力UI( 重力UI)](https://gravity-ui.com/) 设计系统.

## 安装

```shell
npm install @gravity-ui/components
```

## 使用量

`@gravity-ui/uikit` 需要8和18/19反应。 安装当前 UIKit 8 预放 `npm install @gravity-ui/uikit@beta`。 。 。 .

`@gravity-ui/uikit` 是一个对等依赖: 安装它, 在应用程序入口处导入它的样式, 然后将应用程序包入 `Provider`。该软件包中的组件不设此设置就变成无样式.

```tsx
import {Provider, TextInput} from '@gravity-ui/uikit';
import {FormRow} from '@gravity-ui/components';
import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

export function App() {
  return (
    <Provider theme="light">
      <FormRow label="Name" fieldId="name">
        <TextInput id="name" name="name" />
      </FormRow>
    </Provider>
  );
}
```

### 迁移到 UIKit 8

-   替换应用程序级别 `ThemeProvider` 与 `Provider`。 。 。 .
-   使用 `onOpenChange` 改为 `onClose` 内 `ConfirmDialog` 财务报告和审定财务报表 `ChangelogDialog`。 。 。 . `ConfirmDialog` 接受新的对话框道具,包括 `maxWidth` 财务报告和审定财务报表 `fullWidth` 改为 `size`。 。 。 .
-   删除 `disableHeightTransition` 从 `ChangelogDialog` 和 cookie 同意弹出设置; UIKit 不再动画内容高度 .
-   `Stories` 财务报告和审定财务报表 `StoriesGroup` 保留 `onClose`,带有可选事件/理由和UIKit 8 理由(`escape-key`, (中文(简体) ), `outside-press`, (中文(简体) ), `click`) (中文(简体) ).
-   将本地 HTML 属性直接传递到按钮/ 链接道具, 包括 `StoreBadge`,改为 `extraProps`。在自定义故事动作中使用 UIKit 8 按钮视图.

见 [UIKit 8 迁移指南](https://github.com/gravity-ui/uikit/blob/next/docs/migration-to-v8.md) 用于基本的 API 变化。 这个软件包使用新的列表,菜单,以及没有后遗症切入点的波波弗API.

### 确认对话框

```tsx
import {ConfirmDialog} from '@gravity-ui/components';

<ConfirmDialog
  open={open}
  title="Delete the project?"
  message="This cannot be undone."
  textButtonApply="Delete"
  textButtonCancel="Cancel"
  onClickButtonApply={handleDelete}
  onClickButtonCancel={() => setOpen(false)}
  onOpenChange={setOpen}
/>;
```

### 更多实例

每个组件在源头旁边有一个有道具和实例的README——见: `src/components/<Component>/README.md`。现场演示: [故事书](https://preview.gravity-ui.com/components/)。 。 。 .

## 发展

```shell
git clone git@github.com:gravity-ui/components.git
cd components
npm ci
npm run start   # launches Storybook at http://localhost:7009
```

其他有用的命令 :

```shell
npm test              # run unit tests
npm run lint          # lint JS and SCSS
npm run typecheck     # TypeScript type-check
```

## 捐款

欢迎捐款! 请阅读 [捐款额](https://npmcn.com/package/%40gravity-ui/components/CONTRIBUTING.md) 在提交拉动请求之前.

## 许可证

根据麻省理工学院的许可证分发。 见 [自由主义](https://npmcn.com/package/%40gravity-ui/components/LICENSE) 详细情况.

## 对于人工智能特工

Gravity UI的复合组件层——现成形式行、确认对话框、通知、故事、画廊和类似产品级部件组装自 `@gravity-ui/uikit` 原始人,所以你不会用手重建他们.

### 何时使用

-   窗体布局 : `FormRow` (label + field + discription)代替手制标签/输入包装.
-   确认流量 : `ConfirmDialog` 而不是编译 `Dialog` 还有两个按钮.
-   产品部件 : `Notifications`, (中文(简体) ), `Stories` 编号 : `StoriesGroup`, (中文(简体) ), `ChangelogDialog`, (中文(简体) ), `OnboardingMenu`, (中文(简体) ), `PromoSheet`, (中文(简体) ), `CookieConsent`, (中文(简体) ), `Reactions`, (中文(简体) ), `SharePopover`, (中文(简体) ), `StoreBadge`。 。 。 .
-   数据助手 : `InfiniteScroll`, (中文(简体) ), `ItemSelector`, (中文(简体) ), `DelayedTextInput`, (中文(简体) ), `TokenizedInput`, (中文(简体) ), `Gallery`。 。 。 .

### 不使用时

-   基本控制、覆盖、布局和主题——使用 [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit) 直接;这个包只在其上方添加复合材料.
-   数据网格——使用 [`@gravity-ui/table`](https://github.com/gravity-ui/table); 这里没有桌子.
-   取日期者和日历——使用 [`@gravity-ui/date-components`](https://github.com/gravity-ui/date-components)。 。 。 .
-   应用程序导航弹壳(页眉、页脚)——使用 [`@gravity-ui/navigation`](https://github.com/gravity-ui/navigation)。 。 。 .
-   Schema 驱动的表格——使用 [`@gravity-ui/dynamic-forms`](https://github.com/gravity-ui/dynamic-forms)· ; `FormRow` 只是一个布局行.

### 常见陷阱

-   **没有 wiikit 的设置,什么也没有风格.** 安装 `@gravity-ui/uikit`导入 `@gravity-ui/uikit/styles/styles.css` (单位:千美元) `fonts.css`一次,然后将应用程序包入 `Provider` ——这个包船没有自己的全球风格.
-   **`FormRow` 不提供输入.** 通过控件为 `children` 并将其与 `fieldId` 匹配控件 `id`; 数据 `label` 道具是标签文本,不是 `<label>` 键.
-   **`ConfirmDialog` 没有 `onConfirm` 编号 : `onCancel`。 。 。 .** 处理者是 `onClickButtonApply` 财务报告和审定财务报表 `onClickButtonCancel`,以及 `textButtonApply` 编号 : `textButtonCancel` 需要这样做.
-   **迷幻进口.** 从软件包根导出所有 : `import {FormRow} from '@gravity-ui/components'`没有子路径导入像 `@gravity-ui/components/FormRow`。 。 。 .

## AI代理的文件

安装版本的可代理读取文档位于 `node_modules/@gravity-ui/components/build/docs/INDEX.md`。 。 。 .

## 常见问题

### @gravity-ui/components 是什么？

一组复杂的反应组件建在顶部 @gravity-ui/uikit部分内容 重力UI\( 重力UI\) 设计系统\.

### 如何安装 @gravity-ui/components？

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

### @gravity-ui/components 支持 TypeScript 吗？

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

### @gravity-ui/components 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gravity-ui/components 可以商用吗？

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

### @gravity-ui/components 的下载量有多少？

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

### @gravity-ui/components 还在维护吗？

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

