Skip to content

Commit aed0642

Browse files
molchanoviaconooi
andauthored
Add migration guide for WidgetSpan ordering in RTL text (#13988)
Documents the corrected WidgetSpan order in RTL and mixed-direction text. Apps that compensated for the old source-order layout can now position widgets incorrectly; the guide explains which workarounds to remove. Includes before-and-after screenshots and an entry under "Not yet released to stable". The fix landed in Flutter 3.50.0-0.1.pre. Related issue: flutter/flutter#54400 Related change: https://skia-review.googlesource.com/c/skia/+/1366676 The fix has already landed. --------- Co-authored-by: Connie Ooi <[email protected]>
1 parent 09d107f commit aed0642

4 files changed

Lines changed: 95 additions & 0 deletions

File tree

‎sites/docs/src/content/release/breaking-changes/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,11 +40,13 @@ They're sorted by release and listed in alphabetical order:
4040
* [Migrate to standalone `material_ui` and `cupertino_ui` packages][]
4141
* [Stricter Android `Intent` verification for app entrypoints][]
4242
* [Restrict Android engine flags in release mode][]
43+
* [WidgetSpan order in right-to-left text][]
4344

4445
[Added enabled property and made onChanged optional for DropdownButton]: /release/breaking-changes/dropdownbutton-enabled-property
4546
[Stricter Android `Intent` verification for app entrypoints]: /release/breaking-changes/stricter-android-entrypoint-intent-verification
4647
[Migrate to standalone `material_ui` and `cupertino_ui` packages]: /release/breaking-changes/material-ui-and-cupertino-ui
4748
[Restrict Android engine flags in release mode]: /release/breaking-changes/restrict-android-engine-flags-release-mode
49+
[WidgetSpan order in right-to-left text]: /release/breaking-changes/widgetspan-rtl-bidi-order
4850

4951
<a id="released-in-flutter-347" aria-hidden="true"></a>
5052
### Released in Flutter 3.47
Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
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
40.1 KB
Loading
40.2 KB
Loading

0 commit comments

Comments
 (0)