SuperTextEditor 中列表项垂直对齐问题的分析与解决方案

问题描述

在 SuperTextEditor 项目中，当开发者通过样式表设置自定义行高时，列表项（包括有序列表和无序列表）的垂直对齐会出现异常。具体表现为列表项的数字编号或项目符号与文本内容无法正确对齐，这在设置较大行高值时尤为明显。

问题根源分析

经过深入分析，我们发现这个问题实际上由两个独立但相关的原因造成：

1. 有序列表对齐问题：这是由于文本组件和编号组件使用了不同的 TextLeadingDistribution 属性导致的。文本组件默认使用 TextLeadingDistribution.even，而编号组件则没有明确设置这个属性。

2. 无序列表对齐问题：无序列表的项目符号采用简单的居中布局方式，没有考虑文本基线对齐，导致在不同行高设置下无法保持视觉一致性。

技术解决方案

有序列表的修复方案

对于有序列表，解决方案相对简单：确保编号组件和文本组件使用相同的 TextLeadingDistribution 属性。可以通过在样式表中明确设置：

Stylesheet(
  rules: <StyleRule>[
    StyleRule(
      BlockSelector.all,
      (doc, docNode) {
        return {
          "textStyle": TextStyle(
            height: 3.0,
            leadingDistribution: TextLeadingDistribution.even,
          ),
        };
      },
    ),
  ]
)

无序列表的修复方案

无序列表的问题需要更复杂的解决方案。我们推荐使用 WidgetSpan 结合 PlaceholderAlignment.middle 来实现正确的垂直对齐：

dotBuilder: (context, component) {
  final texStyle = component.styleBuilder({});
  
  return Align(
    alignment: Alignment.centerRight,
    child: Text.rich(
      WidgetSpan(
        alignment: PlaceholderAlignment.middle,
        child: Container(
          width: 20,
          height: texStyle.fontSize! * texStyle.height!,
          margin: const EdgeInsets.only(right: 10),
          decoration: const BoxDecoration(
            shape: BoxShape.circle,
            color: Colors.red,
          ),
        ),
      ),
    ),
  );
}

进阶定制建议

在实际开发中，开发者可能还需要根据字体大小动态调整项目符号的大小。这可以通过创建自定义的 ListItemComponentBuilder 来实现：

1. 创建一个继承自 ComponentBuilder 的类
2. 重写 createComponent 方法
3. 在方法中返回自定义的 UnorderedListItemComponent
4. 在 dotBuilder 中根据文本样式动态计算项目符号大小

总结

SuperTextEditor 中的列表项垂直对齐问题主要源于文本布局属性的不一致和项目符号的简单布局方式。通过统一文本分布属性和使用更精确的布局控件，我们可以确保列表项在不同行高设置下都能保持正确的视觉对齐。

对于需要更高度定制的场景，开发者可以通过创建自定义组件构建器来实现更灵活的控制，包括动态调整项目符号大小、颜色等属性。这种解决方案不仅解决了当前的对齐问题，还为未来的样式定制提供了良好的扩展性。