Air君陈怡帆“ListItemGroup的Header怎么动态设置？”这个问题，我在技术群里见过太多次了。提问者通常已经能把分组列表跑起来，header也正常显示，但需求从“写死的标题”变成“按接口返回动态变化”时，就卡住了。最常见的操作是：把header里的文字改成变量、在刷新逻辑里改掉这个变量，然后界面纹丝不动。这篇文章就把这件事彻底讲清楚。我会以 ArkUI 的 ListItemGroup 为主线，同时对照 Flutter 的 GroupedListView，后面再补小程序里的写法。方案可以直接抄，顺带把我实际踩过的坑、排查思路也完整记录下来。
1. 动态Header的卡点：header是“待执行UI”，不是写死的那棵树
1.1 Header不是一个控件，而是一个Builder
很多开发者把ListItemGroup的header理解成“这个分组头部的控件树”，这是个很深的误解。几乎所有分组列表组件，header接收的都不是一段已经构建好的UI，而是一个builder——一个“等列表需要画头部时再去执行”的函数。
- ArkUI 的
ListItemGroup，header 类型是CustomBuilder，本质上是构建函数； - Flutter 的
GroupedListView，header 对应groupHeaderBuilder，是一个回调； - 小程序里没有专门的header属性，通常用
wx:for渲染分组头视图，数据变、视图变，原理一样。
既然是builder，关键点就来了：只有builder被执行，Header才会重新生成。builder什么时候执行？大部分框架的策略是：列表本身要重建，或者builder依赖的状态发生变化。如果你的Header内容引用的是一个普通成员变量，变量变化时框架并不知道“你变了”，自然不会重新执行builder。
这就是为什么很多人改了变量发现Header没动静。不是框架不支持动态Header，而是你写给框架的“依赖关系”根本没建立起来。
1.2 把普通函数当Builder传，是看不到动态效果的直接原因
展开一个真实现场。ArkUI新手很容易写成这样：
ts复制footer() {
return Text('固定底部')
}
build() {
List() {
ListItemGroup({ header: this.footer() }) {
// 分组内容
}
}
}
这个写法里，this.footer() 在父组件build时立刻执行了一次，得到的结果被当作一个静态节点挂上去。之后就算父组件setState，这个节点的身份仍然是旧的那个，除非你用其他手段让框架把它判定为“已变化”。
正确做法是把它声明为 @Builder，或者在 CustomBuilder 里读取状态、用状态变量来驱动。区别在于值的读取时机不同——是“父组件构建时读一次”，还是“头部每次要渲染时重新读”。
Flutter那边也有类似的错误写法：在 groupHeaderBuilder 里读一个顶层全局变量，变量改了，不调用 setState，自然没有反应。Flutter的刷新机制以widget为载体，你的变量没有和widget树建立依赖，出现这种问题不是Flutter不行，是依赖关系没有建立。
1.3 状态变化后，有人通知Header重绘才是动态的核心
动态设置Header，说白了就是两件事：
- Header依赖的数据，必须是框架能感知的状态（
@State、setState、ValueNotifier等）； - 状态变化时，框架必须能把“这个Header需要重画”的信号传到对应节点。
只要这两件事成立，Header的内容、样式、结构都可以动态变化。你会发现这不只是“给header传参数”的问题，而是数据流方向的问题：数据在变化，Header只是数据的投影。
理解这一点能帮你少走很多弯路。后面讲的所有方案，本质上都是在解决“如何更好地建立依赖、如何精准触发重绘”。
1.4 一个生活化类比：菜单上的“时价菜”
把Header理解成餐厅菜单上的“时价菜”挺合适。
静态Header就像菜单印出来的那一刻，上面写着“今日例汤：南瓜汤”，印刷成本决定了它只能固定；动态Header就像一块电子菜单屏，菜品信息存在数据库里，后厨改了菜名、调了价格，屏幕刷新后自然会显示新内容。
builder就是那个电子菜单的查询接口。你写的builder如果不去数据库查价格，而是把“南瓜汤”三个字直接烧死在屏幕里，那它当然不会变。反过来，只要builder内部读取的是动态数据源，数据一改，界面跟随更新。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 三种经过验证的动态Header实现方式
2.1 状态驱动：把变化内容变成状态变量
最简单的动态Header，是让Header里变化的那部分内容成为组件的状态。
ArkUI里可以这样写：
ts复制@State headerText: string = '全部订单'
@State orderCount: num