# @gravity-ui/normalized-list 中文文档

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

版本：1\.0\.0
npm 元数据更新时间：2026-11-05T13:39:07.250Z
中文译文更新时间：2026-11-17T05:19:13.538Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：779 kB，593 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^16\.14\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^16\.14\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，@gravity-ui/icons ^2\.16\.0，@gravity-ui/uikit ^8\.0\.0，@floating-ui/react ^0\.27\.0
- 首次发布：2026-08-21T11:13:48.154Z
- 最新版本发布：2026-11-05T13:39:06.982Z
- 近 30 天下载量：6197（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

普通平地/树木列表模型和反应列表/选择组件

## 安装

```sh
npm install @gravity-ui/normalized-list
```

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

## README

# @ gravity-ui/ 正常化的列表

软件包的核心是 **`useNormalizedList`**: 它需要将列表项目输入其中之一 a **平顶** 或者说 **树** 形状并把它们变成一个常态模型——id-keyed data,分级元,可见顺序,以及交互状态(选择,扩展,焦点).

UI 组件(`NormalizedList`, (中文(简体) ), `NormalizedSelect`,可选的 UIKit 层) **在那个模型之上** 并保持自定义 通过制作道具.

## 安装

```bash
npm install @gravity-ui/normalized-list
```

核心条目的对等依赖性(`@gravity-ui/normalized-list`: `react` 财务报告和审定财务报表 `react-dom` 带范围 `^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0`。 。 。 .

这个 `@gravity-ui/normalized-list/uikit` 需要输入 **UIKit 8 软件** (单位:千美元)`@gravity-ui/uikit@^8.0.0`和 **反应 18 或 19** (两者) `react` 财务报告和审定财务报表 `react-dom`. UIKit 7 本条目不再支持.

```bash
npm install @gravity-ui/normalized-list @gravity-ui/uikit@^8.0.0
```

UIKit 条目也需要 `@gravity-ui/icons` 财务报告和审定财务报表 `@floating-ui/react`。安装 `@gravity-ui/uikit` 通常足够(它已经取决于其他两个)。 安装 pnpm 等严格的软件包管理器 `@gravity-ui/icons` 财务报告和审定财务报表 `@floating-ui/react` 如果他们不下决心的话.

从 `@gravity-ui/uikit/unstable` (单位:千美元)`TreeSelect`, (中文(简体) ), `TreeList`, (中文(简体) ), `useList`{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢? 见 [移民.md](https://npmcn.com/package/%40gravity-ui/normalized-list/MIGRATION.md)。 。 。 .

## 思想

```text
items (flat | tree)
        │
        ▼
  useNormalizedList
        │
        ├─ structure  → itemsById, groupsState, visibleFlattenIds, …
        └─ state      → selectedById, expandedById, activeItemId, …
                │
                ▼
     NormalizedList / NormalizedSelect
     (or your own view / UIKitNormalized*)
```

钩子解决的是什么:

-   一个 API 用于 **平顶** 财务报告和审定财务报表 **树** 编写格式;
-   O(1) 恢复正常后由身份证进入;
-   选择 / 扩展 / 键盘友好 **可见** 顺序 (`visibleFlattenIds`(三);
-   UI 保持哑巴:通过 `list` 用于自定义渲染.

## 两个输入形状

有效载荷 `T` 这是你的。 名单合同只是 **节点包装**数字 :

**平板电脑** - 项目是 `T` 本身( 可选 `id` 编号 : `selected` 编号 : `disabled`:

```ts
import type {ListItemType} from '@gravity-ui/normalized-list';

const flat: ListItemType<string>[] = ['one', 'two', 'three'];

const flatObjects: ListItemType<{title: string}>[] = [
  {title: 'one'},
  {title: 'two', selected: true},
];
```

**树** - 东西有 `data: T` 和可选 `children`数字 :

```ts
const tree: ListItemType<{title: string}>[] = [
  {
    data: {title: 'Fruits'},
    children: [{data: {title: 'Apple'}}, {data: {title: 'Orange'}}],
  },
];
```

都归正了 `structure` + 键 `state`。 。 。 .

## 软件包布局

| 条目 | 导入 | 你得到的东西 |
| --- | --- | --- |
| 核心 | `@gravity-ui/normalized-list` | `useNormalizedList`, (中文(简体) ), `NormalizedList`, (中文(简体) ), `NormalizedSelect`无头建筑构件 |
| 用户界面Kit | `@gravity-ui/normalized-list/uikit` | `UIKitNormalizedList`, (中文(简体) ), `UIKitNormalizedSelect`,主题项目/控制视图 |

核心舰a **最小后退 UI** 当你忽略了制取道具。 用于生产,通过自己的渲染器或使用UIKit条目.

## 快开始

### 1\. 仅钩子

```tsx
import {useNormalizedList} from '@gravity-ui/normalized-list';

const list = useNormalizedList({
  items: ['one', 'two', 'three'],
  getItemId: (item) => item,
});

// list.structure.itemsById
// list.structure.visibleFlattenIds
// list.state.selectedById / setSelected / …
```

### 2\. 钩上列出UI

核心 `NormalizedList` 编号 : `NormalizedSelect` 提供 **后退视图** 用于演示和探索。 关于生产,你更喜欢自己的UI,它与你的设计系统相匹配——见 [自定义视图](https://npmcn.com/package/%40gravity-ui/normalized-list/#readme-customizable-views)。 。 。 .

```tsx
import {NormalizedList, useNormalizedList} from '@gravity-ui/normalized-list';

const items = [{data: {title: 'Parent'}, children: [{data: {title: 'Child'}}]}];

export function Example() {
  const list = useNormalizedList({items, defaultExpandedState: 'expanded'});

  return <NormalizedList list={list} multiple mapItemDataToContentProps={(item) => item} />;
}
```

### 3\. UIKit 预设

Uikit 条目是一组预设 `@gravity-ui/uikit`:列表行的命题默认值,选择控件并弹出. 它们涉及“从自己的观点”到“从“从”到“从”到“从“从”到“从”到“从“从”到“从”到“从”到“从“从”到“从”到“从”到“从”到“从”到“从”到“从”到”到”从“从“从”到”到”到”从“从“从”到”到”到“从“从”到”到“从\`从”到”到”到“从\`从\`从\`到'到'到'到'从\`从\`到'到'到'从\`从\`到'到'到'到'从\`从\`到'到'到'”的“从\`到'到'到'”的“从你自己的观点”的”差距 [第2节](https://npmcn.com/package/%40gravity-ui/normalized-list/#readme-2-list-ui-on-top-of-the-hook) 对于这个案子,你仍然可以通过道具来推翻.

```tsx
import {useNormalizedList} from '@gravity-ui/normalized-list';
import {UIKitNormalizedList} from '@gravity-ui/normalized-list/uikit';

export function Example() {
  const list = useNormalizedList({
    items: ['one', 'two', 'three'],
    getItemId: (item) => item,
  });

  return (
    <UIKitNormalizedList list={list} multiple mapItemDataToContentProps={(title) => ({title})} />
  );
}
```

`NormalizedSelect` 编号 : `UIKitNormalizedSelect` 内部使用相同的模型(项目 = 正常 = 列表在弹出中).

## 自定义视图

不重写列表逻辑 :

-   **`NormalizedList` 编号 : `NormalizedSelect`**数字 : `renderItem`, (中文(简体) ), `renderContainer`
-   **`NormalizedSelect`**页:1 `renderControl`, (中文(简体) ), `renderPopup`, (中文(简体) ), `renderError`时段 `slotBeforeListBody` 编号 : `slotAfterListBody`
-   **用户界面Kit**: 互换默认`UIKitListItemView` 内 `renderItem`, (中文(简体) ), `UIKitNormalizedSelectControl`一样的方式

```tsx
<NormalizedList
  list={list}
  mapItemDataToContentProps={(item) => item}
  renderItem={({id, props, context, renderContainerProps}) => (
    <MyRow {...props} {...renderContainerProps} isLast={context.isLastItem} />
  )}
  renderContainer={(containerProps) => <VirtualizedContainer {...containerProps} />}
/>
```

## CSS 命名空间

BEM 根和包 CSS 变量使用 `g-nl-` 前缀( 例如) `--g-nl-list-item-background-hover`) (中文(简体) ).

UIKit 条目将变量映射到 `@gravity-ui/uikit` 指针( a)`--g-color-*`, (中文(简体) ), `--g-spacing-*`(中文(简体) ).

## 故事书

实例 **常规列表** (核心)和 **已规范列表/ UIKit**医生是 `*Docs.md` 每个故事本条目旁边.

## 许可证

麻省理工学院

## 常见问题

### @gravity-ui/normalized-list 是什么？

普通平地/树木列表模型和反应列表/选择组件

### 如何安装 @gravity-ui/normalized-list？

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

### @gravity-ui/normalized-list 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

