flutter-text-rendering

Flutter 文本渲染

在动态内容长度、不同地区设置和无障碍设置下，渲染清晰且可预测的文本。

诊断

调整布局前，先找出问题机制：

1. 主轴 Flex 溢出： 非 Flex 的 Text 在 Flex 主轴上可能受到无界约束，并选择大于其与同级元素之间可用空间的固有尺寸，从而导致 RenderFlex overflowed。
2. 孤行单词： 标题或段落的最后一个单词因换行发生在最后一个空格处，独自落在新的一行。
3. 不可控的截断： 文本悄然裁切，或超出预期行数，且没有明显的截断提示（ellipsis、fade）。
4. 行内排版中断： Row 中多个相邻的 Text widget 无法像连续段落一样流畅换行，导致换行效果不自然。
5. 文本缩放导致布局失效： 系统字体缩放比例增大（TextScaler）后，文本在固定高度的容器中被裁切，或将关键操作挤出屏幕。

规则

• 约束相互竞争的分支，而不是所有 Text： 在 Row 中，当文本需要与同级元素共享有限的水平空间时，使用 Flexible、Expanded、SizedBox 或 ConstrainedBox。在 Column 中，Flex 会改变垂直空间分配，因此并非解决水平文本溢出的默认方法。父级主轴约束无界时，切勿添加 Flex 子项。
• 仅在适合分词方式时避免孤行单词： 对于以空格分隔单词的标题、名称和提示文本，可以使用不换行空格（\u00A0）将最后两个单词连在一起。不要在所有地区设置下都采用此启发式方法。
• 有意选择换行或截断： 完整文案至关重要时，允许自然换行。产品要求截断时，应将明确的 maxLines 与 TextOverflow.ellipsis、TextOverflow.fade 或 TextOverflow.clip 搭配使用。未经确认单行裁切是否可接受，不要设置 softWrap: false。
• 使用 Text.rich 设置行内样式： 混合使用不同字重、颜色、行内徽标（WidgetSpan）或链接识别器时，优先使用 Text.rich，以继承环境样式并支持文本缩放。原始 RichText 需要明确设置 span 样式和缩放，但可以继承环境文本方向。
• 文本布局取决于文案尺寸时，使用 TextPainter 测量： 构建动态标签、自定义画布提示文本或可展开的“阅读更多”组件时，应使用明确的 maxWidth 以及环境中的方向、地区设置和 TextScaler 来布局 TextPainter，从而检查渲染高度和 didExceedMaxLines。
• 适配文本缩放： 支持放大的系统字体（MediaQuery.textScalerOf(context)）。避免为文本设置硬编码的容器高度；优先使用灵活或可滚动的容器。
• 考虑国际化： 设计文案容器时，应能容纳本地化字符串扩展 20–35% 的长度，并支持双向文本（TextDirection）。

条件参考

• 修复 Flex 溢出、使用不换行空格消除孤行单词、配置 TextPainter 测量或管理多行截断时，请阅读文本溢出与换行。

验证

使用以下内容测试文本组件：

1. 最短文案（空内容或单个短词）。
2. 符合预期的常见文案。
3. 最长文案／本地化文案（包括带重音符号的字符串和较长的不含空格字符串）。
4. 放大的字体缩放（TextScaler.linear(1.5) 和 TextScaler.linear(2.0)）。
5. 受限的父级宽度（窄屏手机、紧凑卡片、列表项）。

编写 widget 测试，断言没有 RenderFlex 溢出，确认行数符合预期，并验证截断或不换行词组的显示效果符合预期。

Sources

• Flutter Text class
• Flutter RichText class
• Flutter TextPainter class
• Flutter TextOverflow enum
• Flutter TextScaler class