# @gravity-ui/react-unipika 中文文档

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

版本：0\.8\.1
npm 元数据更新时间：2026-07-03T17:50:06.300Z
中文译文更新时间：2026-11-17T14:29:07.591Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.6 MB，301 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@bem-react/classname ^1\.6\.0，@gravity-ui/i18n ^1\.0\.0，@gravity-ui/icons ^2\.0\.0，@gravity-ui/table ^1\.10\.1，@gravity-ui/uikit ^7\.1\.1
- 首次发布：2025-05-12T11:01:36.809Z
- 最新版本发布：2026-07-03T17:50:06.138Z
- 近 30 天下载量：4894（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 11 个）

## 中文简介

该库通过使用已注册的字段类型来帮助创建与窗体的对话框. 也可以用你自己的字段类型来扩展.

## 安装

```sh
npm install @gravity-ui/react-unipika
```

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

## README

## 简短说明

目的 `@gravity-ui/react-unipika` 正在视觉 JSON 和 [亚森](https://ytsaurus.tech/docs/en/user-guide/storage/yson) 数据对象. 图书馆使用 [`@gravity-ui/unipika`](https://github.com/gravity-ui/unipika) 财务报告和审定财务报表 [`@gravity-ui/table`](https://github.com/gravity-ui/table) 内部.

### 特征

-   虚拟化
-   两种滚动模式:窗口滚动和容器滚动
-   崩溃/扩展对象/阵列
-   搜索按键/值的子串(对大小写敏感和对大小写不敏感)
-   每行生成一升
    -   长字符串被椭圆切换
        -   在对话框中可以看到全部值

## 安装

```bash
$ npm install @gravity-ui/react-unipika
```

根据您的软件包管理器, 您可能需要安装 `peerDependencies` 手动.

## 使用量

图书馆根据您的滚动需要提供两个切入点:

### 窗口滚动( 默认)

如果您希望组件与浏览器窗口滚动, 请使用此选项 :

```ts
import '@gravity-ui/uikit/styles/styles.scss';
import '@gravity-ui/unipika/styles/unipika.scss';

import {ReactUnipika} from '@gravity-ui/react-unipika/window-scroll';

function renderJson(data: any) {
  return <ReactUnipika value={data} />;
}
```

### 容器滚动

当您希望组件滚动到特定容器中时使用此选项。 您必须提供滚动容器的校对 :

```ts
import '@gravity-ui/uikit/styles/styles.scss';
import '@gravity-ui/unipika/styles/unipika.scss';

import {ReactUnipika} from '@gravity-ui/react-unipika/container-scroll';

function renderJson(data: any) {
  const scrollContainerRef = React.useRef<HTMLDivElement>(null);

  return (
    <div ref={scrollContainerRef} style={{height: '500px', overflow: 'auto'}}>
      <ReactUnipika value={data} scrollContainerRef={scrollContainerRef} />
    </div>
  );
}
```

## YSON 通知

库不支持YSON-format"as is",即无法使用/保存YSON数据. 但是它提供了使JSON对象成为YSON的方法,这种JSON对象保留了字段名,比如: `$attributes`, (中文(简体) ), `$value`。 。 。 .

更多信息见 [故事书](https://preview.yandexcloud.dev/react-unipika)。 。 。 .

## 道具

### ReactUnipika 组件道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `value` | `any` | 所需经费 | 将提供的数据 |
| `settings` | `UnipikaSettings` | 见下文 | Unipika 格式化设置 |
| `inline` | `boolean` | `false` | 内嵌模式中的渲染 |
| `children` | `React.ReactNode` | \- 说吧 | 儿童反应节点 |
| `extraTools` | `React.ReactNode` | \- 说吧 | 工具的额外反应节点 |
| `virtualized` | `boolean` | `true` | 启用虚拟化,以便用大数据改进性能 |
| `className` | `string` | \- 说吧 | 自定义 CSS 类名称 |
| `customLayout` | `(args: {toolbar: React.ReactNode; content: React.ReactNode}) => React.ReactNode` | \- 说吧 | 自定义布局的函数 |
| `toolbarStickyTop` | `number` | `0` | 粘性工具栏在像素中的最高位置 |
| `renderToolbar` | `(props: ToolbarProps) => React.ReactNode` | \- 说吧 | 自定义工具栏渲染器功能 |
| `collapseIconType` | `CollapseIconType` | \- 说吧 | 要使用的崩溃/扩展图标类型 |
| `showContainerSize` | `boolean` | \- 说吧 | 显示容器大小(对象/阵列) |
| `initiallyCollapsed` | `boolean` | \- 说吧 | 是否使树初倒塌 |
| `caseInsensitiveSearch` | `boolean` | \- 说吧 | 启用不区分大小写搜索 |
| `renderError` | `(error: unknown) => React.ReactNode` | \- 说吧 | 自定义错误渲染器功能 |
| `renderRowExtraTools` | `(params: RenderRowExtraToolsParams) => React.ReactNode` | \- 说吧 | 每个行的自定义工具 |
| `scrollContainerRef` | `React.RefObject<Element | null>` | \- 说吧 | **仅用于容器滚动**。引用滚动容器元素 |

### 统一安排

| 设置 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `asHTML` | `boolean` | `true` | 渲染为 HTML |
| `format` | `string` | `'json'` | 格式类型 ('json','yson','raw-json') |
| `compact` | `boolean` | `false` | 使用压缩渲染 |
| `escapeWhitespace` | `boolean` | `true` | 逃出空白字符 |
| `showDecoded` | `boolean` | `true` | 显示已解码的值 |
| `binaryAsHex` | `boolean` | `true` | 以十六进制显示二进制数据 |
| `nonBreakingIndent` | `boolean` | \- 说吧 | 使用非破碎空格缩进 |
| `escapeYQLStrings` | `boolean` | \- 说吧 | 逃出 YQL 字符串 |
| `decodeUTF8` | `boolean` | \- 说吧 | 解码 UTF-8 编码字符串 |
| `indent` | `number` | \- 说吧 | 缩进大小 |
| `break` | `boolean` | \- 说吧 | 添加换行符 |
| `maxListSize` | `number` | \- 说吧 | 在列表中显示的最大项目数 |
| `maxStringSize` | `number` | \- 说吧 | 切换前显示的最大字符串长度 |
| `omitStructNull` | `boolean` | \- 说吧 | 结构中的无效值 |
| `treatValAsData` | `boolean` | \- 说吧 | 将值视为数据 |

## 常见问题

### @gravity-ui/react-unipika 是什么？

该库通过使用已注册的字段类型来帮助创建与窗体的对话框\. 也可以用你自己的字段类型来扩展\.

### 如何安装 @gravity-ui/react-unipika？

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

### @gravity-ui/react-unipika 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

