Flutter问题记录 - Text组件设置不限行数无效

小咪咪 2024-05-24 21:39 103阅读 0赞

#### 文章目录 ####

*  前言
 *  开发环境
 *  问题描述
 *  问题分析
 *  解决方案
 *  最后

--------------------

## 前言 ##

梳理Flutter项目的过程中发现还有一些遗留的`TODO`没处理，其中有一个和`Text`组件相关。

## 开发环境 ##

*  Flutter: 3.7.12
 *  Dart: 2.19.6

## 问题描述 ##

`Text`组件设置`maxLines: null`不限制行数：

Text(
      'The [Text] widget displays a string of text with single style. The string might break across multiple lines or might all be displayed on the same line depending on the layout constraints.',
      softWrap: true,
      overflow: TextOverflow.ellipsis,
      maxLines: null,
    )

设置无效，只显示一行：

![screenshot1][]

当时赶项目进度，没时间细究，暂时通过设置`maxLines: 9999`实现虚假的不限制行数。

## 问题分析 ##

先看看`maxLines`的文档注释：

/// An optional maximum number of lines for the text to span, wrapping if necessary.
    /// If the text exceeds the given number of lines, it will be truncated according
    /// to [overflow].
    ///
    /// If this is 1, text will not wrap. Otherwise, text will be wrapped at the
    /// edge of the box.
    ///
    /// If this is null, but there is an ambient [DefaultTextStyle] that specifies
    /// an explicit number for its [DefaultTextStyle.maxLines], then the
    /// [DefaultTextStyle] value will take precedence. You can use a [RichText]
    /// widget directly to entirely override the [DefaultTextStyle].

从文档中可知，当`maxLines`设为`null`时，如果`DefaultTextStyle`中有指定`maxLines`的值，那么将以这个值为准。查看`Text`组件的`build`方法，确实是这样的。

`Text`的`build`方法（省略部分）：

@override
    Widget build(BuildContext context) {
        
      final DefaultTextStyle defaultTextStyle = DefaultTextStyle.of(context);
      ...
      Widget result = RichText(
        ...,
        maxLines: maxLines ?? defaultTextStyle.maxLines,
        ...,
      );
      ...
      return result;
    }

问题的原因难道就是这个？断点调试看看：

![screenshot2][]

`DefaultTextStyle`并没有指定`maxLines`的值，也是`null`。通过不断断点调试，可以很确定`maxLines`的值一直都是`null`。这难道是Flutter的bug？想了想应该不可能，如果是Flutter的bug，这么明显的问题应该早就被修复了。

假定Flutter没问题，那问题只能出在`Text`组件的使用上。除了`maxLines`，还设置了`softWrap`和`overflow`属性。咦?？️不限制行数的情况下，文本不存在溢出情况，那设置`overflow`属性完全是多此一举。移除`overflow: TextOverflow.ellipsis`，重新运行一切正常！

`TextOverflow`定义：

enum TextOverflow {
        
      /// Clip the overflowing text to fix its container.
      clip,
    
      /// Fade the overflowing text to transparent.
      fade,
    
      /// Use an ellipsis to indicate that the text has overflowed.
      ellipsis,
    
      /// Render overflowing text outside of its container.
      visible,
    }

奇怪的是只有`TextOverflow.ellipsis`有问题，其他文本溢出处理方式没问题。

![screenshot3][]

通过追踪`overflow`属性的传递，来到`RenderParagraph`类的构造方法：

![screenshot4][]

初始化`TextPainter`时，如果`overflow`属性值等于`TextOverflow.ellipsis`，会用`_kEllipsis`常量初始化`ellipsis`。`_kEllipsis`常量定义：

// '\u2026'即省略号'…'
    const String _kEllipsis = '\u2026';

继续往下走，在`TextPainter`类中找到关于`ellipsis`的定义：

/// The string used to ellipsize overflowing text. Setting this to a non-empty
    /// string will cause this string to be substituted for the remaining text
    /// if the text can not fit within the specified maximum width.
    ///
    /// Specifically, the ellipsis is applied to the last line before the line
    /// truncated by [maxLines], if [maxLines] is non-null and that line overflows
    /// the width constraint, or to the first line that is wider than the width
    /// constraint, if [maxLines] is null. The width constraint is the `maxWidth`
    /// passed to [layout].
    ///
    /// After this is set, you must call [layout] before the next call to [paint].
    ///
    /// The higher layers of the system, such as the [Text] widget, represent
    /// overflow effects using the [TextOverflow] enum. The
    /// [TextOverflow.ellipsis] value corresponds to setting this property to
    /// U+2026 HORIZONTAL ELLIPSIS (…).
    String? get ellipsis => _ellipsis;
    String? _ellipsis;

关键在于第二段文档注释，当`maxLines`为`null`且文本不止一行（文本宽度超出一行的宽度）时，`ellipsis`会用于第一行，也就是截断为一行。文档已经说的很清楚了，我也不知道当时为啥还要标个`TODO`?。不过有句话说得好，来都来了，怎么也得继续再往下看看具体是在哪做文本截断处理的。

找了一番，发现难以继续分析下去，文本的绘制应该涉及到了Flutter引擎部分，光靠Flutter框架代码想要分析下去有点难。不过，也不是没有收获，在`RenderParagraph`类的`performLayout`方法中发现了一些关键调用：

![screenshot5][]

执行布局时，调用`textPainter.size`获取的高度只有一行的高度，最关键的是调用`_textPainter.didExceedMaxLines`返回了`true`，这表示文本被截断或被省略。`didExceedMaxLines`方法的定义：

/// Whether any text was truncated or ellipsized.
    ///
    /// If [maxLines] is not null, this is true if there were more lines to be
    /// drawn than the given [maxLines], and thus at least one line was omitted in
    /// the output; otherwise it is false.
    ///
    /// If [maxLines] is null, this is true if [ellipsis] is not the empty string
    /// and there was a line that overflowed the `maxWidth` argument passed to
    /// [layout]; otherwise it is false.
    ///
    /// Valid only after [layout] has been called.
    bool get didExceedMaxLines {
        
      assert(_debugAssertTextLayoutIsValid);
      return _paragraph!.didExceedMaxLines;
    }

`didExceedMaxLines`方法的第三段文档注释也明确说了，如果`maxLines`为`null`且`ellipsis`不为空，会返回`true`。沿着`_paragraph!.didExceedMaxLines`来到了`Flutter SDK目录/bin/cache/pkg/sky_engine/lib/ui/text.dart`文件：

/// True if there is more vertical content, but the text was truncated, either
    /// because we reached `maxLines` lines of text or because the `maxLines` was
    /// null, `ellipsis` was not null, and one of the lines exceeded the width
    /// constraint.
    ///
    /// See the discussion of the `maxLines` and `ellipsis` arguments at
    /// [ParagraphStyle.new].
    @Native<Bool Function(Pointer<Void>)>(symbol: 'Paragraph::didExceedMaxLines', isLeaf: true)
    external bool get didExceedMaxLines;

从这开始，已经脱离Flutter框架，来到[Flutter引擎][Flutter]。经过一番查找，最终锁定在了`skia`项目中的[TextWrapper.cpp][]文件，里面有个`breakTextIntoLines`函数，顾名思义，这个函数的作用就是将文本分成几行。这个函数有点长，又是`C++`写的，直接看有点累，如果能调试会轻松很多，调试环境的搭建可以参考这篇文章[Flutter - 搭建引擎调试环境（iOS）][Flutter - _iOS]。

![screenshot6][]

从调试结果看，如果有`ellipsis`且不限制行数时，会提前终止循环，也就是第一行就被截断。分析到这，基本可以确定文本最终就是在这被分行截断。

## 解决方案 ##

Text组件设置不限行数时，请勿将`overflow`属性设置为`TextOverflow.ellipsis`。

## 最后 ##

如果这篇文章对你有所帮助，请不要吝啬你的点赞?加星?，谢谢～

[screenshot1]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/4634142b7f324df4b6179e9dd5166129.png
[screenshot2]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/6577061ac392492e98d455c2909c683a.png
[screenshot3]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/157270cebded4cc1ba5eec48edd694c5.png
[screenshot4]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/05b7c22b8cbb4a5d9604bd5b1b380c39.png
[screenshot5]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/691faa509cc247018df9b2a3fe76e52b.png
[Flutter]: https://github.com/flutter/engine/blob/main/lib/ui/text.dart
[TextWrapper.cpp]: https://github.com/google/skia/blob/main/modules/skparagraph/src/TextWrapper.cpp
[Flutter - _iOS]: https://blog.csdn.net/crasowas/article/details/130379070
[screenshot6]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/24/127f45d39bc64a8ebd61fb686afdf4cd.png