coze-common/virtual-list 虚拟列表组件指南Coze Studio 长列表渲染性能优化实战【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studiocoze-common/virtual-list是 Coze Studio 前端 monorepo 中负责虚拟列表Virtual List能力统一出口的组件包它将react-window的FixedSizeList/VariableSizeList与react-virtualized-auto-sizer的AutoSizer集中再导出为全仓库的 Bots 相关长列表场景提供一致、高性能的滚动渲染方案。阅读本文后你将掌握该包的安装接入方式、导出 API 的底层原理以及它在 PDF 文档预览、表格虚拟化等真实业务中的落地方案可以直接复用到自己的长列表开发中。一、包概览与定位该包的官方描述为 Virtual list components for Bots位于 Coze Studio monorepo 的组件层是一个纯依赖转发re-export型封装包核心目标有两个统一依赖入口把虚拟滚动所需的第三方能力收敛到单一包名coze-common/virtual-list下业务侧无需直接面对底层库的版本差异集中管理升级后续如需替换或升级底层虚拟滚动实现只需改动这一个包所有消费方同步受益。从包结构看frontend/packages/components/virtual-list该包只包含一个src/index.ts作为全部导出源配合package.json、tsconfig.json、eslint.config.js、vitest.config.ts等工程化配置是典型的 monorepo 轻量组件包形态。二、安装与接入在 Coze Studio 的 rush.json monorepo 体系中包与包之间通过 workspace 协议互相引用。在任意需要虚拟列表的业务包中向package.json的dependencies添加{ dependencies: { coze-common/virtual-list: workspace:* } }然后执行依赖安装命令rush updaterush update会依据 frontend/config/rush 下的配置生成并更新各子包的依赖锁定文件。安装完成后即可在 TypeScript 代码中直接引入。注意workspace:*语法仅在 Coze Studio 的 Rush monorepo 环境中生效若要在独立项目中使用需要改为发布到 npm 后的具体版本号。三、统一导出封装源码解析该包的全部逻辑集中在 frontend/packages/components/virtual-list/src/index.ts文件头注释点明了设计意图Centralized management of virtual list dependencies used in coze集中管理 Coze 中使用的虚拟列表依赖。export { FixedSizeList, VariableSizeList, type FixedSizeListProps, type VariableSizeListProps, } from react-window; export { default as AutoSizer } from react-virtualized-auto-sizer;对应地frontend/packages/components/virtual-list/package.json 中声明的运行时依赖正是这两个底层库react-window^1.8.10—— 提供核心虚拟列表组件react-virtualized-auto-sizer^1.0.7—— 提供自适应容器尺寸测量能力开发期还依赖types/react-window^1.8.8与types/react-virtualized-auto-sizer^1.0.4提供类型声明并通过coze-arch/eslint-config、coze-arch/ts-config、coze-arch/vitest-config三个 workspace 内的工程化配置包统一代码风格、TypeScript 编译与测试基建。四、API 参考导出的四个核心成员4.1FixedSizeList与FixedSizeListProps适用于所有列表项高度固定的场景如等高的日志行、图片列表。固定高度让库可以借助简单的数学计算在 O(1) 时间内完成可见区域定位滚动性能最优。核心属性以react-window类型定义为准属性说明height/width列表可视区域的像素尺寸由容器决定itemCount列表项总数itemSize每一项的固定像素高度onScroll滚动回调入参包含scrollOffset等滚动信息ref可通过scrollToItem(index, align)编程式滚动到指定项4.2VariableSizeList与VariableSizeListProps适用于列表项高度不固定如文本长度多变的聊天消息、动态内容卡片的场景。相比固定高度版本它需要通过itemSize回调或动态测量机制获取每一项的实际高度代价是额外的测量开销因此应仅在确实需要时使用。4.3AutoSizer来自react-virtualized-auto-sizer的默认导出以render props模式工作——自动测量父容器尺寸并把{ height, width }注入到子渲染函数中从而解决虚拟列表必须先知道可视区尺寸、而尺寸又要等挂载后才能确定的经典鸡生蛋问题AutoSizer {({ height, width }) ( FixedSizeList height{height ?? 0} width{width ?? 0} ... / )} /AutoSizer五、实战案例一PDF 多页文档的虚拟滚动预览知识库场景下Coze Studio 需要在线预览动辄上百页的 PDF 文档。如果一次性渲染全部Page组件页面 DOM 数量会随页数线性增长导致首屏卡顿。解决方案位于 frontend/packages/data/knowledge/common/components/src/doc-preview/use-preview-pdf/index.tsx1按需导入统一出口import { FixedSizeList as List, AutoSizer } from coze-common/virtual-list;2用AutoSizer测量可视区用FixedSizeList渲染页itemCount取 PDF 总页数numPagesitemSize由页面实际高度pageHeight计算得出Math.floor((pageHeight ?? 500) 20)每页通过 render props 拿到index与style后渲染react-pdf的Page pageNumber{index 1} /。因为只渲染可视区附近的页面超大 PDF 也能保持流畅滚动。3通过onScroll同步当前页通过scrollToItem实现翻页const handleScroll ({ scrollOffset }: { scrollOffset: number }) { setCurrentPage(Math.floor(scrollOffset / itemSize)); }; const onNext () { if (currentPage numPages - 1) { listRef.current?.scrollToItem(currentPage 1, start); } };这里ref{listRef}配合scrollToItem(nextPage, start)实现了下一页 / 上一页按钮与虚拟列表滚动位置的联动是虚拟列表编程式滚动能力的典型用法。六、实战案例二大数据量表格的容器自适应另一个消费方是 frontend/packages/components/table-view 表格组件它在知识库数据表格中引入了AutoSizer见 frontend/packages/components/table-view/src/components/table-view/index.tsximport { AutoSizer } from coze-common/virtual-list;该组件通过isVirtualized开关控制是否启用虚拟滚动默认关闭启用时用AutoSizer感知表格容器的实时宽高变化再把尺寸交给底层coze-arch/bot-semi的虚拟化表格能力。这展示了AutoSizer在容器尺寸动态变化场景下的价值无论窗口缩放还是侧栏收起导致宽度变化表格都能自动重排而无需手工监听resize。七、工程化与开发约定该包遵循 Coze Studio monorepo 的统一工程规范frontend/packages/components/virtual-list/package.json构建与测试build与test脚本当前为exit 0空实现因为包是纯 re-export 转发层实际校验由消费方与类型检查承担vitest~3.0.5已作为 devDependency 引入供后续补充单元测试使用代码质量lint脚本执行eslint ./规则来自coze-arch/eslint-config类型体系TypeScript 配置继承coze-arch/ts-config保证与全仓库的编译目标、模块策略一致License与仓库一致采用 Apache-2.0文件头统一携带 Copyright 声明。八、总结coze-common/virtual-list用极简的 re-export 设计把react-window的固定/动态尺寸列表与AutoSizer容器自适应能力整合为一个统一入口并在 PDF 预览、表格等真实业务中得到验证。对开发者而言它的价值不仅是省去重复安装依赖更在于确立了长列表必须虚拟化的团队规范凡是通过该包引入列表渲染的组件都天然获得只渲染可视区域的性能保障。对于自己的项目你也可以借鉴这种依赖集中转发的封装模式把第三方 UI 能力收敛到单一包名下降低升级与替换成本。【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考