# WebF 无限滚动 > **注意**：WebF 开发与 Web 开发几乎相同 - 您使用相同的工具（Vite、npm、Vitest）、相同的框架（React、Vue、Svelte）和相同的部署服务（Vercel、Netlify）。此技能涵盖**滚动列表的性能优化** \ - 一种自动提供本机级性能的特定于 WebF 的模式。通过 Flutter 优化的渲染构建高性能无限滚动列表。 WebF 的“WebFListView”组件自动处理 Flutter 级别的性能优化，即使有数千个项目也能提供流畅的 60fps 滚动。 ## 为什么使用WebFListView？在浏览器中，长滚动列表可能会导致性能问题： * DOM节点累积（内存消耗） * 重新渲染影响所有项目（更新缓慢） * 虚拟化所需的路口观察者 * 无限加载的复杂状态管理 **WebF 的解决方案** ： `WebFListView` 将渲染委托给 Flutter 优化的 ListView 小部件，该小部件： * ✅ 自动虚拟化（回收）视图 * ✅ 保持 60fps 滚动数千个项目 * ✅ 提供原生拉动刷新和加载更多 * ✅ 零配置 - 优化自动发生 ## 关键结构要求 **⚠️ 重要**：为了让 Flutter 优化发挥作用，每个列表项必须是 `WebFListView` 的 **直接子项**： ### ✅ 正确：直接子项

项目 1

项目 2

项目 3

{/* 每一项都是直接子项 */} ### ❌错误：包裹在容器中

{/* 不要将项目包裹在容器 div 中 */}

项目 1

项目 2

项目 3

**为什么这很重要**：Flutter 的 ListView 需要直接子级来执行视图回收。如果项目包装在容器中，Flutter 只能看到一个子项（容器），并且无法优化单个项目。 ## 反应设置 ### 安装 npm 安装@openwebf/react-core-ui ### 基本滚动列表从'@openwebf/react-core-ui'导入{WebFListView}；函数产品列表（）{ 常量产品 = [ { id: 1, name: '产品1', 价格: 19.99 }, { id: 2, 名称: '产品2', 价格: 29.99 }, { id: 3, 名称: '产品3', 价格: 39.99 }, // ... 数百或数千个项目 ]; 返回（ {产品.map(产品=>( // ✅ 每一项都是直接子项

{产品名称}

${产品.价格}

))} ）； } ### 无限滚动并加载更多从'@openwebf/react-core-ui'导入{WebFListView，WebFListViewElement}；从 'react' 导入 { useRef, useState }; 函数InfiniteList() { const listRef = useRef(null); const [items, setItems] = useState([1, 2, 3, 4, 5]); const [页面，setPage] = useState(1); const handleLoadMore = async () => { 尝试{ // 模拟API调用等待新的 Promise(resolve => setTimeout(resolve, 1000)); // 获取下一页常量 newItems = Array.from( {长度：5}， (_, i) => items.length + i + 1 ）； setItems(上一个 => [...上一个, ...newItems]); setPage(上一页 => 上一页 + 1); // 检查是否还有更多数据 const hasMore = 页 < 10; // 示例：最多 10 页 // 通知WebFListView加载完成 listRef.current?.finishLoad(hasMore ? '成功' : 'noMore'); } 捕获（错误）{ // 通知失败 listRef.current?.finishLoad('失败'); } }; 返回（ {items.map(item => (

项目{项目}

))} ）； } ### 拉动刷新从'@openwebf/react-core-ui'导入{WebFListView，WebFListViewElement}；从 'react' 导入 { useRef, useState }; 函数可刷新列表（）{ const listRef = useRef(null); const [items, setItems] = useState([1, 2, 3, 4, 5]); const handleRefresh = async () => { 尝试{ // 模拟API调用等待新的 Promise(resolve => setTimeout(resolve, 1000)); // 获取新数据 const freshItems = [1, 2, 3, 4, 5]; 设置项目（新鲜项目）； // 通知WebFListView刷新完成 listRef.current?.finishRefresh('成功'); } 捕获（错误）{ // 通知失败 listRef.current?.finishRefresh('失败'); } }; 返回（ {items.map(item => (

项目{项目}

))} ）； } ### 组合：拉动刷新 + 无限滚动从'@openwebf/react-core-ui'导入{WebFListView，WebFListViewElement}；从 'react' 导入 { useRef, useState }; 函数 FeedList() { const listRef = useRef(null); const [帖子，setPosts] = useState([ { id: 1, title: '帖子 1', content: '内容 1' }, { id: 2, 标题: '帖子2', 内容: '内容2' }, { id: 3, title: '帖子 3', content: '内容 3' }, ]); const [页面，setPage] = useState(1); const handleRefresh = async () => { 尝试{ // 获取最新帖子 const 响应 =等待 fetch('/api/posts?page=1'); const freshPosts =等待response.json(); setPosts(freshPosts); 设置页面（1）； listRef.current?.finishRefresh('成功'); } 捕获（错误）{ listRef.current?.finishRefresh('失败'); } }; const handleLoadMore = async () => { 尝试{ const 下一页 = 页 + 1; // 获取下一页 const response = wait fetch(`/api/posts?page=${nextPage}`); const newPosts = 等待response.json(); setPosts(上一页 => [...上一页, ...newPosts]); setPage(下一页); // 检查是否存在更多数据 const hasMore = newPosts.length > 0; listRef.current?.finishLoad(hasMore ? '成功' : 'noMore'); } 捕获（错误）{ listRef.current?.finishLoad('失败'); } }; 返回（ {posts.map(帖子 => (

{帖子.标题}

{帖子内容}

))} ）； } ## Vue 设置 ### 安装 npm 安装@openwebf/vue-core-ui ### 设置全局类型在你的 `src/env.d.ts` 或 `src/main.ts` 中：导入“@openwebf/vue-core-ui”； ### 基本滚动列表 <模板>

${{ 产品.价格 }}

<脚本设置lang =“ts”> 从“vue”导入{ref}；常量产品 = ref([ { id: 1, name: '产品1', 价格: 19.99 }, { id: 2, 名称: '产品2', 价格: 29.99 }, { id: 3, 名称: '产品3', 价格: 39.99 }, ]); ### 无限滚动并加载更多 <模板>

项目 {{ 项目 }}

<脚本设置lang =“ts”> 从“vue”导入{ref}； const listRef = ref(); 常量项 = ref([1, 2, 3, 4, 5]); 常量页面 = ref(1); 异步函数handleLoadMore() { 尝试{ // 模拟API调用等待新的 Promise(resolve => setTimeout(resolve, 1000)); // 获取下一页常量 newItems = Array.from( {长度：5}， (_, i) => items.value.length + i + 1 ）； items.value.push(...newItems); 页.值++; // 检查是否还有更多数据 const hasMore = page.value < 10; // 通知WebFListView (listRef.value as any)?.finishLoad(hasMore ? 'success' : 'noMore'); } 捕获（错误）{ (listRef.value as any)?.finishLoad('fail'); } } ### 拉动刷新 <模板>

项目 {{ 项目 }}

<脚本设置lang =“ts”> 从“vue”导入{ref}； const listRef = ref(); 常量项 = ref([1, 2, 3, 4, 5]); 异步函数handleRefresh() { 尝试{ // 模拟API调用等待新的 Promise(resolve => setTimeout(resolve, 1000)); // 获取新数据 items.value = [1, 2, 3, 4, 5]; // 通知WebFListView (listRef.value as any)?.finishRefresh('成功'); } 捕获（错误）{ (listRef.value as any)?.finishRefresh('fail'); } } ## 道具和配置 ### WebFListView 道具道具|类型 |默认 |描述 ---|---|---|--- `滚动方向` | “垂直”| '水平'` | `'垂直'` |列表的滚动方向 `收缩包装` | `布尔值` | `真实` |列表是否应收缩其内容 `onRefresh` / `@refresh` | `() => 无效 |承诺` | - |下拉刷新回调 `onLoadMore` / `@loadmore` | `() => 无效 |承诺` | - |无限滚动回调（接近结束时触发） `类名` / `类` | `字符串` | - | CSS 类名 `风格` | `对象` | - |内联样式 ### 参考方法 (React) / 元素方法 (Vue) 方法|签名|描述 ---|---|--- `完成刷新` | `(结果？: '成功' | '失败' | '不再') => void` |刷新完成后调用 `完成加载` | `(结果？: '成功' | '失败' | '不再') => void` | load-more 完成后调用 `重置标题` | `() => 无效` |将刷新标头重置为初始状态 `重置页脚` | `() => 无效` |将加载更多页脚重置为初始状态 ### 结果值 * `'success'` \- 操作成功，更多数据可用 * `'fail'` \- 操作失败（显示错误状态） * `'noMore'` \- 没有更多数据要加载（隐藏页脚/显示“不再”消息） ## 常见模式 ### 模式 1：使用结果列表搜索从'@openwebf/react-core-ui'导入{WebFListView，WebFListViewElement}；从 'react' 导入 { useRef, useState }; 函数搜索结果() { const listRef = useRef(null); const [查询，setQuery] = useState(''); const [结果，setResults] = useState([]); const handleSearch = async (searchQuery: string) => { setQuery(搜索查询); // 获取搜索结果 const 响应 = 等待 fetch(`/api/search?q=${searchQuery}`); const data =等待response.json(); setResults(数据.结果); }; const handleLoadMore = async () => { 尝试{ 常量响应 = 等待获取（ `/api/search?q=${query}&offset=${results.length}` ）； const data =等待response.json(); setResults(上一个 => [...上一个, ...data.results]); listRef.current?.finishLoad( 数据.结果.长度 > 0 ? “成功”：“不再” ）； } 捕获（错误）{ listRef.current?.finishLoad('失败'); } }; 返回（

<输入类型=“文本” 占位符=“搜索...” onChange={(e) => handleSearch(e.target.value)} /> {结果.map(结果 => (

{结果.标题}

))}

）； } ### 模式 2：聊天消息（反向列表）对于新消息显示在底部的聊天式 UI：从'@openwebf/react-core-ui'导入{WebFListView，WebFListViewElement}；从 'react' 导入 { useRef, useState, useEffect }; 函数聊天消息（）{ const listRef = useRef(null); const [消息，setMessages] = useState([ { id: 1, text: '你好', 时间戳: Date.now() }, { id: 2, text: '你好！', 时间戳: Date.now() }, ]); // 滚动到顶部时加载旧消息 const handleLoadMore = async () => { 尝试{ // 在实际应用中，在第一条消息之前获取较旧的消息 constoldestId = messages[0]?.id; const response = wait fetch(`/api/messages?before=${oldestId}`); const oldMessages = 等待response.json(); // 预先添加较旧的消息 setMessages(上一条 => [...olderMessages, ...上一条]); listRef.current?.finishLoad( oldMessages.length > 0 ？ “成功”：“不再” ）； } 捕获（错误）{ listRef.current?.finishLoad('失败'); } }; 返回（ {messages.map(消息=>(

{消息.文本}

))} ）； } ### 模式 3：水平滚动画廊从'@openwebf/react-core-ui'导入{WebFListView}；函数 ImageGallery({ 图片 }) { 返回（ {images.map(图像=>( <图片键={图像.id} src={图片.url} alt={图片.标题} 风格={{ 宽度：'150px'，高度：'150px'， objectFit: '覆盖', flexShrink: 0 // 防止收缩 }} /> ))} ）； } ## 常见错误 ### 错误 1：将物品包裹在容器中 // ❌ 错误 - 项目包裹在容器 div 中

{items.map(item =>

{item}

)}

// ✅ 正确 - 项目是直接子项 {items.map(item =>

{item}

)} **为什么**：Flutter 的 ListView 需要直接子视图才能进行视图回收。 ### 错误 2：忘记调用 finishLoad/finishRefresh // ❌ 错误 - 从不调用 finishLoad const handleLoadMore = async () => { const data = 等待 fetchData(); setItems(上一个 => [...上一个, ...数据]); // finishLoad 从未被调用 - 加载指示器卡住了！ }; // ✅ 正确 - 始终调用 finishLoad const handleLoadMore = async () => { 尝试{ const data = 等待 fetchData(); setItems(上一个 => [...上一个, ...数据]); listRef.current?.finishLoad('成功'); } 捕获（错误）{ listRef.current?.finishLoad('失败'); } }; ### 错误 3：未处理“无更多数据”状态 // ❌ 错误 - 始终调用“成功”，即使没有数据 const handleLoadMore = async () => { const data = 等待 fetchData(); setItems(上一个 => [...上一个, ...数据]); listRef.current?.finishLoad('成功'); // 如果数据为空则错误！ }; // ✅ 正确 - 检查是否存在更多数据 const handleLoadMore = async () => { const data = 等待 fetchData(); setItems(上一个 => [...上一个, ...数据]); // 告诉 WebFListView 没有更多数据 listRef.current?.finishLoad(data.length > 0 ? '成功' : '不再'); }; ### 错误 4：超时问题（花费太长时间） WebFListView 的刷新/加载操作有 4 秒的超时时间。如果您的操作时间较长，它将自动失败。 // ❌ 错误 - 操作需要 10 秒（将超时） const handleRefresh = async () => { 等待新的 Promise(resolve => setTimeout(resolve, 10000)); // 10秒 listRef.current?.finishRefresh('成功'); // 为时已晚！ }; // ✅ 正确 - 4 秒内完成 const handleRefresh = async () => { 尝试{ // 使用 Promise.race 强制超时等待 Promise.race([ 获取数据(), 新的承诺（（_，拒绝）=> setTimeout(() => 拒绝(新错误('超时')), 3500) ） ]); listRef.current?.finishRefresh('成功'); } 捕获（错误）{ listRef.current?.finishRefresh('失败'); } }; ## 性能提示 ### 1\.正确使用按键始终为列表项提供唯一、稳定的键： // ✅ 好 - 来自数据的稳定 ID {items.map(item =>

{item.name}

)} // ❌ 不好 - 索引作为键（可能会导致动态列表的错误） {items.map((item, index) =>

{item.name}

)} ### 2\.避免渲染中的繁重计算 // ❌ 不好 - 每次渲染都需要大量计算 {items.map(item => (

{expenseCalculation(item)} {/* 在每次渲染时计算！ */}

))} // ✅ 好 - 记忆或预先计算常量处理项目 = useMemo( () => items.map(item => ({ ...item, 计算出：昂贵的计算(item) })), [项目] ）； {processedItems.map(项目 => (

{item.compulated}

))} ### 3\.优化物品组件 // ✅ 好 - 记忆项目组件 const ListItem = 备忘录(({ item }) => (

{项目.标题}

{项目.描述}

））；函数 MyList({ 项目 }) { 返回（ {items.map(item => ( ))} ）； } ### 4\.设置滚动的显式高度对于全屏列表，设置明确的高度： {/* 项目 */} ## 调试 ### 检查是否调用 finishLoad/finishRefresh 添加日志记录以验证回调执行： const handleLoadMore = async () => { console.log('🔄 加载更多已开始'); 尝试{ const data = 等待 fetchData(); setItems(上一个 => [...上一个, ...数据]); console.log('✅ 加载更多成品：', data.length, 'items'); listRef.current?.finishLoad(data.length > 0 ? '成功' : '不再'); } 捕获（错误）{ console.error('❌加载更多失败:', error); listRef.current?.finishLoad('失败'); } }; ### 验证直接子结构使用 React DevTools 或 Vue DevTools 检查渲染的结构。确保项目是“”的直接子项：

项目 1

项目 2

项目 3

项目 1

项目 2

## 资源 * **React 核心 UI 包** : `/Users/andycall/workspace/webf/packages/react-core-ui/README.md` * **Vue 核心 UI 包** : `/Users/andycall/workspace/webf/packages/vue-core-ui/README.md` * **完整示例** ：请参阅本技能中的“examples.md” * **npm 包**： * * ## 要点 ✅ **做**： * 使用 `WebFListView` 来显示长滚动列表 * 使每个项目成为直接子项（不包装在容器中） * 操作后始终调用 `finishLoad` / `finishRefresh` * 当没有更多数据存在时使用“noMore”结果 * 为列表项提供唯一、稳定的键 * 设置全屏列表的显式高度 ❌ **不要**： * 将项目包裹在容器div中 * 忘记调用完成方法（加载指示器卡住） * 使用索引作为动态列表的键 * 让操作超过4秒超时 * 在渲染中使用大量计算而不进行记忆 * 期望浏览器风格的虚拟化库（不需要！） ## 快速参考 # 安装包 npm install @openwebf/react-core-ui # React npm install @openwebf/vue-core-ui #Vue // React - 基本模式从'@openwebf/react-core-ui'导入{WebFListView，WebFListViewElement}； const listRef = useRef(null); { 等待刷新数据（）； listRef.current?.finishRefresh('成功'); }} onLoadMore={async() => { const hasMore = 等待 loadMore(); listRef.current?.finishLoad(hasMore ? '成功' : 'noMore'); }} > {items.map(item =>

{item.name}

)}

{产品名称}

{帖子.标题}

{{ 产品名称 }}

{项目.标题}

Webf 无限滚动

包含技能