|
| 1 | +--- |
| 2 | +title: WidgetSpan order in right-to-left text |
| 3 | +description: >- |
| 4 | + WidgetSpans now follow bidirectional visual order in right-to-left text. |
| 5 | + Remove workarounds that compensated for the previous layout. |
| 6 | +--- |
| 7 | + |
| 8 | +{% render "docs/breaking-changes.md" %} |
| 9 | + |
| 10 | +## Summary |
| 11 | + |
| 12 | +`WidgetSpan` widgets in right-to-left (RTL) and mixed-direction text |
| 13 | +now follow the visual order determined by the Unicode bidirectional algorithm. |
| 14 | +Apps that compensated for the previous incorrect order |
| 15 | +might display inline widgets in the wrong positions after upgrading. |
| 16 | + |
| 17 | +## Background |
| 18 | + |
| 19 | +Skia's paragraph layout previously placed inline widget placeholders |
| 20 | +in source order, even when the surrounding text was visually reordered. |
| 21 | +This caused inline widgets in Arabic, Hebrew, and mixed-direction text |
| 22 | +to appear in the wrong positions. |
| 23 | + |
| 24 | +Paragraph layout now places inline widget placeholders in bidirectional visual |
| 25 | +order. Your `WidgetSpan` children stay in logical reading order in your Dart |
| 26 | +code, and layout returns placeholder boxes with the corrected visual |
| 27 | +coordinates. No public API signatures changed. |
| 28 | + |
| 29 | +The following example shows the corrected positions of inline widgets |
| 30 | +in mixed-direction text: |
| 31 | + |
| 32 | +| Before | After | |
| 33 | +| :---: | :---: | |
| 34 | +| ![Incorrect widget order][before] | ![Correct widget order][after] | |
| 35 | + |
| 36 | +## Migration guide |
| 37 | + |
| 38 | +If your app uses `WidgetSpan` widgets without compensating for the old layout, |
| 39 | +no code changes are needed. |
| 40 | +Otherwise, remove workarounds added specifically for this issue: |
| 41 | + |
| 42 | +* Translating or swapping widgets on the same line using `Transform.translate` |
| 43 | + offsets or `GlobalKey` measurements. |
| 44 | +* Reversing the source order of `WidgetSpan` widgets for RTL text. |
| 45 | + Keep spans in the logical order of the content and let text layout |
| 46 | + determine their visual positions. |
| 47 | +* Mirroring placeholder-box x-coordinates in custom layout code. |
| 48 | + Use the returned coordinates directly. |
| 49 | + |
| 50 | +For example, remove a translation that compensated for the old RTL order. |
| 51 | +Here, `rtlSwapOffset` is an offset calculated by the app's workaround, |
| 52 | +and `inlineWidget` is the widget embedded in the text. |
| 53 | + |
| 54 | +Code before migration: |
| 55 | + |
| 56 | +```dart |
| 57 | +WidgetSpan( |
| 58 | + child: Transform.translate( |
| 59 | + offset: rtlSwapOffset, |
| 60 | + child: inlineWidget, |
| 61 | + ), |
| 62 | +) |
| 63 | +``` |
| 64 | + |
| 65 | +Code after migration: |
| 66 | + |
| 67 | +```dart |
| 68 | +WidgetSpan(child: inlineWidget) |
| 69 | +``` |
| 70 | + |
| 71 | +Also remove the code that calculated the compensating offsets. |
| 72 | +Check RTL and mixed-direction text, including wrapped lines, |
| 73 | +and update golden tests that captured the incorrect layout. |
| 74 | + |
| 75 | +## Timeline |
| 76 | + |
| 77 | +Landed in version: 3.50.0-0.1.pre<br> |
| 78 | +In stable release: Not yet |
| 79 | + |
| 80 | +## References |
| 81 | + |
| 82 | +GitHub issue: |
| 83 | + |
| 84 | +* [Issue 54400][] |
| 85 | + |
| 86 | +Relevant PRs: |
| 87 | + |
| 88 | +* [Skia CL 1366676][] |
| 89 | + |
| 90 | +[after]: /assets/images/docs/breaking-changes/widgetspan-rtl-after.webp |
| 91 | +[before]: /assets/images/docs/breaking-changes/widgetspan-rtl-before.webp |
| 92 | +[Issue 54400]: {{site.repo.flutter}}/issues/54400 |
| 93 | +[Skia CL 1366676]: https://skia-review.googlesource.com/c/skia/+/1366676 |
0 commit comments