@gravity-ui/normalized-list

中文文档
1.0.0发布于 2026/11/05MITTypeScriptESM + CJS近 30 天下载 6197

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

中文使用文档
文档目录12 节
  1. 安装
  2. 思想
  3. 两个输入形状
  4. 软件包布局
  5. 快开始
  6. 1. 仅钩子
  7. 2. 钩上列出UI
  8. 3. UIKit 预设
  9. 自定义视图
  10. CSS 命名空间
  11. 故事书
  12. 许可证

@ gravity-ui/ 正常化的列表

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

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

安装

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 本条目不再支持.

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。 。 。 .

思想

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:

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数字 :

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

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

软件包布局

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

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

快开始

1. 仅钩子

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,它与你的设计系统相匹配——见 自定义视图。 。 。 .

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节 对于这个案子,你仍然可以通过道具来推翻.

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一样的方式
<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 共发布 3 个版本,首次发布于 2026/08/21;过去 12 个月发布了 3 个版本。

版本发布日期距今
1.0.0latest2026/11/0511 天前
0.1.12026/10/2225 天前
0.1.02026/08/212 个月前

关于 @gravity-ui/normalized-list 的常见问题

@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 和提交记录判断。