flutter-responsive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flutter Responsive and Adaptive UI

Flutter 响应式与自适应UI

Design for available constraints, not one screenshot size.

If invoked during a read-only review, report findings only. Do not edit files.

Focus on real layout/adaptation problems, not mechanical replacement of every fixed value or every

MediaQuery

call.

基于可用约束进行设计，而非单一截图尺寸。

若在只读审查模式下被调用，仅报告发现的问题，请勿编辑文件。

聚焦真实的布局/适配问题，而非机械地替换每一个固定值或每一次

MediaQuery

调用。

Core principle

核心原则

Separate:

structural constraint problems visible from code
likely layout risks
runtime/rendering behavior that needs visual/device verification

Static inspection can confirm some layout defects, but it cannot always prove:

actual overflow at a given device size
text clipping at every text scale
keyboard overlap on every platform
foldable hinge behavior
pointer/keyboard interaction quality
real window-resize behavior

When the rendered result depends on runtime constraints or platform behavior, classify it as Needs verification instead of guessing.

区分以下三类问题：

从代码中可识别的结构性约束问题
潜在的布局风险
需要视觉/设备验证的运行时/渲染行为

静态检查可以确认部分布局缺陷，但无法始终证明以下情况：

特定设备尺寸下的实际溢出情况
所有文本缩放比例下的文本裁剪问题
所有平台上的键盘遮挡问题
折叠屏铰链的行为表现
指针/键盘交互的质量
窗口缩放的真实表现

当渲染结果取决于运行时约束或平台行为时，将其归类为需要验证，而非主观猜测。

Constraint-system reasoning

约束系统推理

Reason from Flutter's constraint model before proposing fixes.

Distinguish:

bounded vs unbounded constraints
parent constraints vs screen size
content sizing vs flex sizing
scrollable vs non-scrollable axes
intrinsic sizing vs explicit sizing

在提出修复方案前，先基于Flutter的约束模型进行推理。

区分以下概念：

有界约束与无界约束
父级约束与屏幕尺寸
内容尺寸与弹性尺寸
可滚动轴与不可滚动轴
固有尺寸与显式尺寸

Bounded vs unbounded

有界与无界

An unbounded-axis problem is different from content being too large for a bounded area.

Examples:

```
Column
```
inside an unbounded-height parent
```
ListView
```
inside another vertical scrollable
```
Expanded
```
inside an unbounded axis
child expecting finite width/height when parent does not provide one

Do not fix these by adding arbitrary fixed dimensions.

Identify the actual source of the unbounded constraint.

无界轴问题与内容超出有界区域的问题是不同的。

示例：

处于无界高度父容器中的
```
Column
```
嵌套在另一个垂直可滚动组件中的
```
ListView
```
处于无界轴中的
```
Expanded
```
父容器未提供有限宽高时，子组件期望获得有限宽高

不要通过添加任意固定尺寸来修复这些问题。

要找出无界约束的真实来源。

Row / Column / Flex

Check:

whether children should share available space
whether they should size to content
whether
```
Expanded
```
or
```
Flexible
```
semantics match the intended behavior
whether wrapping is more appropriate
whether a fixed child legitimately needs fixed size

Do not add

Expanded

Flexible

mechanically just because a

Row

overflows.

检查以下几点：

子组件是否应该共享可用空间
子组件是否应该根据内容自适应尺寸
```
Expanded
```
或
```
Flexible
```
的语义是否符合预期行为
使用换行/折行是否更合适
固定尺寸的子组件是否确实需要固定大小

不要仅仅因为

Row

溢出就机械地添加

Expanded

或

Flexible

。

Nested scrollables

嵌套可滚动组件

Inspect nested

ListView

GridView

SingleChildScrollView

, or other scrollables for:

axis conflicts
unbounded constraints
unnecessary
```
shrinkWrap
```
conflicting scroll physics
eager layout cost from shrink-wrapped large collections
unclear ownership of scrolling

Do not use

shrinkWrap: true

merely to silence a constraint exception.

Do not add

SingleChildScrollView

as a default overflow fix.

Use scrolling only when the content genuinely should scroll.

检查嵌套的

ListView

、

GridView

、

SingleChildScrollView

或其他可滚动组件是否存在以下问题：

轴方向冲突
无界约束
不必要的
```
shrinkWrap
```
滚动物理效果冲突
对大型集合使用shrinkWrap导致的即时布局开销
滚动控制权不清晰

不要仅仅为了消除约束异常就使用

shrinkWrap: true

。

不要将添加

SingleChildScrollView

作为默认的溢出修复方案。

仅当内容确实需要滚动时才使用滚动组件。

Available constraints vs screen size

可用约束与屏幕尺寸

Prefer decisions based on the space actually available to the component.

Use

LayoutBuilder

when component behavior depends on parent constraints.

Use

MediaQuery

when behavior depends on screen/environment information such as:

view insets
text scaling
platform padding
orientation
system UI

Do not assume screen width equals available component width.

This matters in:

dialogs
side panels
nested layouts
split-screen
desktop windows
foldables
embedded/hosted UI regions

优先基于组件实际可用的空间做决策。

当组件行为取决于父级约束时，使用

LayoutBuilder

。

当行为取决于屏幕/环境信息时，使用

MediaQuery

，例如：

视图内边距
文本缩放
平台内边距
屏幕方向
系统UI

不要假设屏幕宽度等于组件可用宽度。

这一点在以下场景中尤为重要：

对话框
侧边面板
嵌套布局
分屏
桌面窗口
折叠屏
嵌入式/托管UI区域

Fixed dimensions

固定尺寸

Fixed dimensions are not automatically wrong.

They may be appropriate for:

icons
logos
avatars
thumbnails
known touch targets
deliberately fixed controls
visual assets with intended aspect ratios

Report a fixed dimension only when it creates a realistic risk under supported:

screen sizes
text scaling
localization
orientation
window resizing
keyboard/inset changes
parent constraints

Do not replace a valid fixed value with proportional scaling merely to make the layout "responsive."

固定尺寸本身并非错误。

它们适用于以下场景：

图标
Logo
头像
缩略图
已知的触控目标
刻意固定大小的控件
有预期宽高比的视觉资源

仅当固定尺寸在支持的以下场景中会产生实际风险时，才报告该问题：

屏幕尺寸
文本缩放
本地化
屏幕方向
窗口缩放
键盘/内边距变化
父级约束

不要仅仅为了让布局“响应式”，就用比例缩放替换有效的固定值。

Text and localization-sensitive layout

文本与本地化敏感布局

Allow for:

longer translations
Arabic/English length differences
multiple lines
increased text scale
dynamic content

Review:

fixed-height containers around text
tightly constrained rows
hardcoded line counts
clipping/ellipsis that hides critical content
buttons that cannot grow
labels competing for horizontal space

Do not assume clipping exists from static code alone when actual constraints and text are unknown.

Mark uncertain rendered behavior for visual verification.

考虑以下情况：

更长的翻译文本
阿拉伯语/英语的文本长度差异
多行文本
文本缩放比例增大
动态内容

审查以下内容：

文本周围的固定高度容器
约束严格的Row
硬编码的行数
隐藏关键内容的裁剪/省略号
无法自适应增大的按钮
争抢水平空间的标签

当实际约束和文本内容未知时，不要仅通过静态代码就断定存在裁剪问题。

将不确定的渲染行为标记为需要视觉验证。

Breakpoints

断点

Use a small number of meaningful layout modes.

Derive breakpoints from layout behavior, not from one device model.

Good breakpoint reasoning asks:

when does the current composition stop working well?
when does available space allow a materially better layout?
when should navigation or content arrangement change?

Avoid:

device-name checks
dozens of arbitrary width thresholds
breakpoints chosen only because a screenshot was taken at that width

Prefer semantic modes such as:

compact
medium
expanded

when they fit the project.

Do not introduce a breakpoint system if the existing layout already adapts cleanly without one.

使用少量有意义的布局模式。

断点应基于布局行为推导，而非单一设备型号。

合理的断点推导需要考虑：

当前布局组合何时会无法良好运行？
可用空间何时能支持更优的布局？
导航或内容排布何时需要调整？

避免：

按设备名称判断
数十个任意的宽度阈值
仅因为截图是在该宽度下拍摄的就选择对应断点

优先使用语义化模式，例如：

紧凑（compact）
中等（medium）
扩展（expanded）

前提是它们适合项目需求。

如果现有布局无需断点系统就能良好适配，就不要引入断点系统。

Safe areas and insets

安全区域与内边距

Account for relevant environmental constraints:

status bars
navigation bars
notches/cutouts
keyboard insets
foldable display features
bottom gesture areas
modal insets

Do not nest

SafeArea

mechanically.

Inspect whether parent layouts already handle system padding.

Do not add padding twice.

考虑相关的环境约束：

状态栏
导航栏
刘海/挖孔
键盘内边距
折叠屏显示特性
底部手势区域
模态框内边距

不要机械地嵌套

SafeArea

。

检查父布局是否已经处理了系统内边距。

不要重复添加内边距。

Dialogs and bottom sheets

对话框与底部弹窗

Review:

max width on large screens
keyboard insets
content growth
text scaling
safe areas
scrolling behavior
action buttons remaining reachable
nested scrollables

Do not assume a mobile-width dialog should expand to full desktop width.

Do not force fixed height just to keep content visible.

审查以下内容：

大屏幕下的最大宽度
键盘内边距
内容增长
文本缩放
安全区域
滚动行为
操作按钮是否始终可点击
嵌套可滚动组件

不要假设移动端宽度的对话框应该扩展到桌面端全宽。

不要仅仅为了让内容可见就强制设置固定高度。

Lists and grids

列表与网格

Review adaptive collections for:

column count
spacing
item minimum/maximum width
overly stretched cards
too-dense layouts on small screens
eager building
nested scrolling
aspect-ratio assumptions

Do not scale every element proportionally with screen width.

Prefer layout changes that preserve usability rather than mathematically scaling all dimensions.

审查自适应集合的以下方面：

列数
间距
列表项的最小/最大宽度
卡片被过度拉伸
小屏幕下布局过于密集
即时构建开销
嵌套滚动
宽高比假设不合理

不要让所有元素都随屏幕宽度成比例缩放。

优先选择保证可用性的布局调整方式，而非对所有尺寸进行数学上的等比例缩放。

Orientation, window resizing, and multi-window

屏幕方向、窗口缩放与多窗口

Do not treat orientation as the only source of size change.

For supported platforms, consider:

live desktop/web window resizing
split-screen
multi-window
changing parent constraints
keyboard appearance
system UI changes
foldable posture/hinge regions

Layout should respond to current constraints rather than assuming a one-time startup size.

Do not require foldable-specific logic when the project does not target or need it.

不要将屏幕方向视为尺寸变化的唯一来源。

对于支持的平台，考虑以下情况：

桌面端/Web端窗口实时缩放
分屏
多窗口
父级约束变化
键盘弹出
系统UI变化
折叠屏姿态/铰链区域

布局应响应当前约束，而非假设启动时的尺寸是固定不变的。

如果项目不针对或不需要折叠屏支持，就不要添加折叠屏专属逻辑。

Platform interaction patterns

平台交互模式

When relevant to supported targets, consider:

touch
mouse/pointer
hover
wheel scrolling
keyboard navigation
shortcuts
right-click/context actions
TV/remote focus

Do not create separate widget trees for every platform unless behavior genuinely differs.

Prefer adaptive composition where practical.

Do not overengineer desktop/web interaction for a mobile-only application.

当与支持的目标平台相关时，考虑以下情况：

触控
鼠标/指针
悬停
滚轮滚动
键盘导航
快捷键
右键/上下文操作
电视/遥控器焦点

不要为每个平台创建单独的组件树，除非行为确实存在差异。

在可行的情况下优先使用自适应组合。

不要为仅面向移动端的应用过度设计桌面端/Web端交互。

Responsive vs adaptive

响应式与自适应

Responsive behavior changes layout based on available space.

Adaptive behavior may also change interaction pattern or component choice for a platform/form factor.

Do not force platform-specific widgets merely for visual difference.

Use adaptive behavior when it improves real usability or matches required platform interaction semantics.

响应式行为基于可用空间调整布局。

自适应行为还可能针对平台/设备形态调整交互模式或组件选择。

不要仅仅为了视觉差异就强制使用平台专属组件。

当自适应行为能提升实际可用性或符合所需的平台交互语义时，才使用自适应行为。

Full-project responsive coverage

全项目响应式覆盖

During an explicitly requested full-project production audit, systematically consider the user-facing layout surfaces that actually exist.

Typical areas include:

app shell/navigation
primary feature screens
forms
dialogs
bottom sheets
lists/grids
detail screens
empty/error/loading states
onboarding/authentication
localized Arabic/English layouts
large text
orientation changes
keyboard-open states
tablet layouts
desktop/web windows when targeted
split-screen/multi-window when relevant

Do not claim the whole UI is responsive because a few screens were inspected.

Inspect shared layout primitives plus enough production-critical feature screens to support the conclusion.

If coverage is incomplete, mark affected surfaces as:

Not reviewed
Needs verification

rather than implying complete responsive readiness.

在明确要求的全项目生产环境审计中，应系统地考虑实际存在的用户可见布局界面。

典型的审查范围包括：

应用外壳/导航
核心功能页面
表单
对话框
底部弹窗
列表/网格
详情页
空状态/错误状态/加载状态
新手引导/认证流程
阿拉伯语/英语本地化布局
大字体场景
屏幕方向切换
键盘弹出状态
平板布局
目标平台包含桌面端/Web时的窗口适配
相关场景下的分屏/多窗口适配

不要因为检查了少数页面就声称整个UI都是响应式的。

需要检查共享布局基元，以及足够多的生产环境核心功能页面，才能支撑结论。

如果覆盖不完整，将受影响的界面标记为：

未审查
需要验证

而非暗示已经完全具备响应式适配能力。

Evidence discipline

证据规范

Classify findings as:

Confirmed
Likely
Needs verification

Examples:

Confirmed:
```
Expanded
```
is used in an actually unbounded axis and the code path establishes the constraint violation.
Needs verification: translated text may overflow at maximum supported text scale on a narrow device.
Confirmed: a dialog has an unconditional 900px width with no surrounding constraint on a supported 360px-wide layout.
Likely: this will produce poor layout on small phones.
Confirmed: a nested scrollable uses
```
shrinkWrap
```
over an unbounded large dataset.
Needs verification: this creates noticeable runtime jank on supported devices.

Do not inflate severity using an unverified rendered or performance consequence.

Do not assume:

fixed width = responsiveness bug
```
MediaQuery
```
= bad architecture
```
SingleChildScrollView
```
= correct overflow fix
```
shrinkWrap
```
= correct nested-scroll fix
```
Expanded
```
= correct Row/Column fix
landscape = tablet
wide screen = desktop
orientation = available layout width

Inspect actual constraints and supported targets.

将发现的问题归类为：

已确认
大概率存在
需要验证

示例：

已确认：
```
Expanded
```
被用于实际无界的轴中，且该代码路径确实存在约束违规。
需要验证：在窄屏设备上，翻译后的文本可能在最大支持的文本缩放比例下溢出。
已确认：某个对话框设置了无条件的900px宽度，而在支持的360px宽布局中没有外围约束。
大概率存在：这会在小屏手机上导致布局异常。
已确认：嵌套的可滚动组件对无界的大型数据集使用了
```
shrinkWrap
```
。
需要验证：这会在支持的设备上造成明显的运行时卡顿。

不要使用未经验证的渲染或性能后果来夸大问题严重程度。

不要假设：

固定宽度 = 响应式缺陷
```
MediaQuery
```
= 架构不佳
```
SingleChildScrollView
```
= 正确的溢出修复方案
```
shrinkWrap
```
= 正确的嵌套滚动修复方案
```
Expanded
```
= Row/Column的正确修复方案
横屏 = 平板
宽屏 = 桌面端
屏幕方向 = 可用布局宽度

要检查实际约束和支持的目标平台。

Cargo-cult guardrails

盲从行为警示

Do not mechanically:

wrap overflowing layouts in
```
SingleChildScrollView
```
add
```
Expanded
```
everywhere
add
```
Flexible
```
everywhere
set
```
shrinkWrap: true
```
replace fixed values with percentages
introduce breakpoints everywhere
replace every
```
MediaQuery
```
with
```
LayoutBuilder
```
add
```
SafeArea
```
around every screen
create separate mobile/tablet/desktop widget trees
scale all padding/font/icon values by screen width

Use the smallest change that fixes the verified layout problem.

不要机械地：

给溢出的布局套上
```
SingleChildScrollView
```
到处添加
```
Expanded
```
到处添加
```
Flexible
```
设置
```
shrinkWrap: true
```
用百分比替换固定值
到处引入断点
把所有
```
MediaQuery
```
都替换成
```
LayoutBuilder
```
给每个页面都套上
```
SafeArea
```
创建单独的移动端/平板端/桌面端组件树
按屏幕宽度缩放所有内边距/字体/图标尺寸

采用能修复已验证布局问题的最小改动方案。

Reporting

报告规范

For each finding, report:

file/component
supported layout/context affected
exact constraint/adaptation issue
evidence
realistic trigger
likely or verified user impact
recommended direction
confidence
runtime/visual/device verification required

For full-project audits, also report:

surfaces actually reviewed
form factors actually considered
surfaces requiring visual/device verification
unsupported/unreviewed form factors

Use evidence-bounded wording.

Prefer:

"No structural responsive-layout issue was identified in the reviewed screens."

over:

"The UI is fully responsive."

Prefer:

"The reviewed layout adapts correctly to the inspected constraints."

over:

"Works on all screen sizes."

Do not claim:

fully responsive
no overflow
tablet-ready
desktop-ready
foldable-ready
works at all text scales
works on all screen sizes

unless the evidence actually supports those claims.

对于每个发现的问题，报告以下内容：

文件/组件
受影响的支持布局/场景
具体的约束/适配问题
证据
实际触发条件
可能或已验证的用户影响
建议的修复方向
置信度
是否需要运行时/视觉/设备验证

对于全项目审计，还需报告：

实际审查的界面
实际考虑的设备形态
需要视觉/设备验证的界面
不支持/未审查的设备形态

使用有证据支撑的表述。

优先使用：

“在已审查的页面中，未发现结构性的响应式布局问题。”

而非：

“UI是完全响应式的。”

优先使用：

“已审查的布局能够正确适配所检查的约束条件。”

而非：

“适用于所有屏幕尺寸。”

不要声称：

完全响应式
无溢出
适配平板
适配桌面端
适配折叠屏
适用于所有文本缩放比例
适用于所有屏幕尺寸

除非有实际证据支撑这些结论。

Final principle

最终原则

This skill answers:

"What layout/adaptation risks are supported by the implementation, and which rendered behaviors still require visual or device verification?"

It does not answer:

"Can static inspection prove every screen works on every possible size, orientation, locale, and device?"

本技能解答：

“当前实现存在哪些已证实的布局/适配风险，哪些渲染行为仍需要视觉或设备验证？”

本技能不解答：