SliverChildBuilderDelegate与SliverChildListDelegate中semanticIndexCallback的作用是什么

核心作用说明 #

这个属性是Flutter为列表类组件提供的无障碍语义适配接口，服务于屏幕阅读器、语义化分析等场景，官方描述的准确翻译为：

给定子组件和其在当前Sliver已加载队列中的本地索引，返回该子项对应的全局语义索引。

背景原理 #

Sliver系列组件默认采用懒加载机制，只会渲染当前可视区附近的子项，组件构建时传入的localIndex（也就是builder回调中的index参数）是当前Sliver已加载子项的内部相对索引，不是子项在整个完整列表中的全局顺序。如果没有语义索引的映射，屏幕阅读器等无障碍工具会错误识别子项的实际位置，导致视障用户无法正常使用列表导航功能。

不同场景的使用规则 #

SliverChildListDelegate 场景 #

该Delegate的子项是提前完整传入的固定列表，默认语义索引就等于本地索引，绝大多数场景不需要自定义回调，仅当列表中存在不需要计入语义顺序的元素时才需要配置：

• 例如列表中插入的装饰分割线、无意义的广告位、纯展示的背景组件，可以在回调中返回null，让这些元素不被计入语义序号
• 若存在分组标题类需要单独调整序号的元素，也可以通过回调自定义映射规则

SliverChildBuilderDelegate 场景 #

这是需要重点配置该回调的场景，尤其是列表包含头部、分组、分页加载逻辑，或者和其他Sliver组合在CustomScrollView中使用时，必须通过回调完成本地索引到全局语义索引的映射，示例代码如下：

CustomScrollView(
  slivers: [
    // 第一个Sliver是顶部Banner，共1个语义项
    SliverToBoxAdapter(child: TopBanner()),
    // 第二个Sliver是内容列表，包含1个头部+200条内容
    SliverList(
      delegate: SliverChildBuilderDelegate(
        (context, index) {
          if (index == 0) return const ListHeader();
          return ContentItem(data: contentList[index - 1]);
        },
        childCount: 1 + contentList.length,
        semanticIndexCallback: (widget, localIndex) {
          // 列表头部不需要计入内容项语义序号，返回null忽略
          if (localIndex == 0) return null;
          // 全局语义索引 = 前面Sliver的语义项总数 + 当前内容项的全局偏移
          // 前面的Banner占1个语义位，当前内容项偏移是localIndex-1，所以最终返回 1 + (localIndex -1) = localIndex
          return localIndex;
        },
      ),
    )
  ]
)

注意事项 #

• 语义索引要求为连续不重复的正整数，整个CustomScrollView内所有Sliver的语义索引需要按页面从上到下的顺序统一编排，不能出现冲突
• 返回null代表该子项不需要纳入语义导航序列，不会被屏幕阅读器识别为列表的可导航项
• 该配置是应用无障碍适配的必填项之一，不符合要求的应用在很多应用市场的上架审核中会被驳回

内容的提问来源于stack exchange，提问作者The Chinky Sight