Next.js 13引入了App Router等新特性，布局组件的使用方式和之前版本有较大区别，在集成react-window实现全高滚动条时，需要先理清全局布局的层级结构，再针对性调整滚动容器的高度计算逻辑，避免出现滚动区域无法占满剩余高度或者布局错位的问题。
前置准备
首先需要在Next.js 13项目中安装react-window依赖，执行以下命令完成安装：
npm install react-window
假设我们的全局布局结构采用Next.js 13的App Router默认结构，根布局文件为app/layout.js，页面组件放在app/page.js中，全局布局包含顶部导航栏和下方内容区域，全高滚动条需要占满内容区域的剩余高度。
全局布局结构搭建
先编写根布局组件，设置整体页面为弹性布局，让内容区域自动占满剩余高度：
// app/layout.js
import './globals.css'
export const metadata = {
title: 'Next.js 13 react-window Demo',
description: '全高滚动条集成示例',
}
export default function RootLayout({ children }) {
return (
<html lang="zh-CN">
<body className="h-screen flex flex-col">
<header className="h-16 bg-gray-100 flex items-center px-4">
顶部导航栏
</header>
<main className="flex-1 overflow-hidden">
{children}
</main>
</body>
</html>
)
}
对应的全局样式文件中需要补充基础样式，确保弹性布局生效：
/* app/globals.css */
html, body {
margin: 0;
padding: 0;
}
实现全高虚拟滚动列表
接下来在页面组件中集成react-window的FixedSizeList组件，实现全高滚动效果。首先需要计算滚动容器的高度，由于父容器main已经通过flex-1占满了除导航栏之外的剩余高度，我们可以直接通过useRef获取容器高度，或者直接使用百分比高度适配。
这里采用直接设置容器高度为100%的方式，让滚动列表占满父容器的全部高度：
// app/page.js
'use client'
import { FixedSizeList as List } from 'react-window'
import { useRef, useEffect, useState } from 'react'
// 生成测试数据
const generateItems = (count) => {
return Array.from({ length: count }, (_, index) => ({
id: index,
content: `列表项 ${index + 1}`
}))
}
const ITEM_HEIGHT = 50 // 每个列表项的高度
const items = generateItems(1000) // 生成1000条测试数据
export default function HomePage() {
const listRef = useRef(null)
const [containerHeight, setContainerHeight] = useState(0)
const containerRef = useRef(null)
useEffect(() => {
// 获取父容器的高度，作为滚动列表的高度
if (containerRef.current) {
setContainerHeight(containerRef.current.clientHeight)
}
// 监听窗口 resize 事件，动态调整高度
const handleResize = () => {
if (containerRef.current) {
setContainerHeight(containerRef.current.clientHeight)
}
}
window.addEventListener('resize', handleResize)
return () => window.removeEventListener('resize', handleResize)
}, [])
// 列表项渲染函数
const Row = ({ index, style }) => {
const item = items[index]
return (
<div style={style} className="border-b border-gray-200 flex items-center px-4">
{item.content}
</div>
)
}
return (
<div ref={containerRef} className="h-full">
{containerHeight > 0 && (
<List
ref={listRef}
height={containerHeight}
itemCount={items.length}
itemSize={ITEM_HEIGHT}
width="100%"
>
{Row}
</List>
)}
</div>
)
}
核心逻辑说明
上述实现的核心逻辑包含以下几个部分：
- 根布局使用弹性布局，让
main内容区域自动占满剩余屏幕高度，为全高滚动提供基础布局支撑。 - 页面组件中通过
useRef获取main区域的实际高度，作为react-window列表的height属性值，确保滚动区域占满整个内容区域。 - 监听窗口的
resize事件，当窗口大小变化时重新计算容器高度，保证滚动区域高度始终适配当前布局。 - react-window的
FixedSizeList组件只渲染可视区域的列表项，大幅减少DOM节点数量，提升长列表的渲染性能。
常见问题与解决方案
滚动区域高度计算错误
如果出现滚动区域高度不对的情况，首先检查父容器的高度是否正确设置，确保父容器有明确的高度值，避免react-window获取到的高度为0。可以在浏览器开发者工具中查看容器元素的实际计算高度，排查布局样式问题。
布局错位问题
如果全局布局中存在其他边距或者内边距，需要统一调整盒模型设置，建议在全局样式中添加box-sizing: border-box，避免内边距和边框影响容器高度计算：
/* app/globals.css */
html, body {
margin: 0;
padding: 0;
box-sizing: border-box;
}
* {
box-sizing: inherit;
}
服务端渲染兼容问题
由于react-window依赖浏览器DOM API，在Next.js 13中需要在组件顶部添加'use client'指令，标记为客户端组件，避免服务端渲染时出现DOM相关报错。
总结
在Next.js 13中集成react-window实现全高滚动条，核心是先搭建好弹性布局的全局结构，再准确获取滚动容器的剩余高度，将其传递给react-window的列表组件。这种方式既能利用虚拟滚动的性能优势，又能完美适配Next.js 13的全局布局体系，适合处理各种长列表场景。实际开发中可以根据需求调整列表项高度、滚动列表的宽度等参数，也可以替换为VariableSizeList实现可变高度列表的虚拟滚动。
Next.js_13react-window全高滚动条全局布局集成修改时间：2026-07-11 06:48:31