本文详解如何使用 Flet 的 SearchBar 组件实现实时搜索过滤，通过 ListView 动态管理 ListTile 建议项，解决直接在 controls 中硬编码导致仅显示首项的问题。
本文详解如何使用 flet 的 `searchbar` 组件实现实时搜索过滤，通过 `listview` 动态管理 `listtile` 建议项，解决直接在 `controls` 中硬编码导致仅显示首项的问题。
在 Flet 中，SearchBar 的 controls 参数并非用于直接传入多个 ListTile 实例列表，而是期望接收一个或多个容器控件（如 ListView, Column, Row），由该容器统一承载并管理可滚动、可更新的搜索建议项。若像初始代码那样直接传入 [ft.ListTile(...), ...]，Flet 会将其视为静态控件集合，在初始化后不再响应内部数据变更——这也是为何只显示第一个水果名称的根本原因。
正确的做法是：将 ListView 作为唯一 control 加入 SearchBar，再通过操作 ListView.controls 动态增删 ListTile。这样既保证了 UI 可滚动性，又支持高效局部刷新。
以下是完整、可运行的解决方案：
import flet as ft
def main(page: ft.Page):
page.title = "Fruit Search Demo"
page.padding = 20
fruits_list = [
"apple", "banana", "orange", "grape", "strawberry",
"watermelon", "kiwi", "pineapple", "mango", "pear"
]
# ✅ 创建可动态更新的 ListView 容器
suggestion_list = ft.ListView(
spacing=2,
padding=5,
height=200, # 推荐设置高度以启用滚动
auto_scroll=False,
)
def open_anchor(e):
"""点击搜索栏时展开建议视图"""
suggestion_list.controls.clear()
for fruit in fruits_list:
suggestion_list.controls.append(
ft.ListTile(
title=ft.Text(fruit.capitalize()),
on_click=lambda e: close_anchor(e),
data=fruit,
leading=ft.Icon(ft.icons.FRUIT_ORANGE_ROUNDED, size=18),
)
)
anchor.update()
def close_anchor(e):
"""选择建议项后关闭视图并填充搜索栏文本"""
if e.control.data:
anchor.value = e.control.data
page.update()
anchor.close_view()
def handle_change(e):
"""实时过滤建议列表"""
query = e.data.strip().lower()
suggestion_list.controls.clear()
if not query:
# 空查询时显示全部（或留空）
filtered = fruits_list
else:
filtered = [fruit for fruit in fruits_list if query in fruit.lower()]
# ✅ 动态添加匹配项
for fruit in filtered:
suggestion_list.controls.append(
ft.ListTile(
title=ft.Text(fruit.capitalize()),
on_click=lambda e: close_anchor(e),
data=fruit,
leading=ft.Icon(ft.icons.FRUIT_ORANGE_ROUNDED, size=18),
)
)
# ? 必须调用 update() 刷新 ListView 及其父级 SearchBar
anchor.update()
# ✅ SearchBar 的 controls 只包含一个 ListView 实例
anchor = ft.SearchBar(
view_elevation=4,
divider_color=ft.colors.BLUE_200,
bar_hint_text="Search for fruits...",
view_hint_text="Type to filter suggestions...",
on_change=handle_change,
on_tap=open_anchor,
controls=[suggestion_list], # ? 关键：仅传入容器，非 ListTile 列表
width=400,
)
page.add(
ft.Row(
[anchor],
alignment=ft.MainAxisAlignment.CENTER,
)
)
ft.app(target=main, view=ft.AppView.WEB_BROWSER)
⚠️ 关键注意事项：
- ListView 是必需中间层：SearchBar.controls 不接受扁平 ListTile 列表，必须包裹在支持动态子控件管理的容器中。
- anchor.update() 不可省略：每次修改 suggestion_list.controls 后，需显式调用 anchor.update() 触发重绘；仅 suggestion_list.update() 通常不足以刷新 SearchBar 视图。
- 大小写敏感处理：示例中统一转为小写比对（.lower()），提升用户体验。
- 空查询逻辑：建议在 query 为空时恢复全量建议，避免用户清空输入后建议区空白。
- 性能提示：对于超大列表（如 >1000 项），可考虑节流 on_change 或引入虚拟滚动（当前 Flet ListView 尚不原生支持，需手动分页）。
此方案结构清晰、符合 Flet 响应式设计范式，是构建可维护搜索交互的标准实践。
