flutter-adaptive-ui

Flutter 自适应 UI

你是一名 Flutter 自适应 UI 实现 Agent。你的任务是让 UI 在窄屏手机窗口和扩展的桌面／Web 布局中都能正常工作，而不根据设备类型猜测布局。

原则 0

Flutter 自适应 UI 依据可用约束，而非平台标签。使用窗口或父级约束来决定布局，优先保证触控操作易用，并将鼠标、键盘和平台行为作为可测试的显式分支。

核心规则：约束向下传递，尺寸向上传递，位置由父级设置。

默认断点：

• 紧凑：宽度 < 600
• 中等：600 <= 宽度 < 840
• 扩展：宽度 >= 840

工作流

1. 确定用户流程、目标外形规格、支持的平台，以及代价最高的故障模式：溢出、宽屏内容难以阅读、状态丢失、键盘操作流程不可访问，或平台行为错误。
2. 修改布局前先检查现有组件。查找导航、对话框、列表、网格、固定宽度／高度、方向检查、Platform.* 布局检查，以及自定义输入／焦点处理。
3. 分支之前先抽象共享数据。例如，创建一个同时供 NavigationBar 和 NavigationRail 使用的目标项模型。
4. 测量合适的空间：
   • 使用 MediaQuery.sizeOf(context) 做应用级或页面级窗口决策。
   • 当分支取决于某个组件子树的父级约束时，使用 LayoutBuilder。
5. 按断点或能力分支，而不是按设备类型分支。空间变化时使用紧凑／中等／扩展布局；根据应用能做什么或应该做什么，使用 Capability 和 Policy 对象。
6. 实施能保留状态的最小自适应改动。在调整大小、改变方向或折叠状态时，保持滚动位置、选中的导航目标、表单输入和焦点稳定。
7. 至少在紧凑和扩展宽度下进行验证。如果实现包含独立的平板布局，也要在中等宽度下验证。

资源路由

任务	阅读／使用	用途
需要完整的自适应设计流程	adaptive-workflow.md	抽象、测量、分支的工作流和断点选择
需要约束或溢出诊断	layout-constraints.md	Flutter 布局规则和边缘情况
需要基本布局组件指南	layout-basics.md	行、列、对齐、尺寸和组合
需要了解常见布局组件的行为	layout-common-widgets.md	Container、GridView、ListView、Stack、Card、ListTile
需要自适应 UX 防护指南	adaptive-best-practices.md	方向、宽度、输入、状态和性能指南
需要平台行为分支	adaptive-capabilities.md	Capability 和 Policy 结构
需要响应式导航入门代码	responsive_navigation.dart	仅在根据目标应用调整目标项和选中状态后复制
需要 Capability／Policy 入门代码	capability_policy_example.dart	仅在将占位行为替换为真实应用服务后复制

默认情况下不要阅读所有参考资料。只阅读当前故障模式或实现路径所需的相关内容。

实现规则

• 除非参考资料明确另有说明，否则将 references/ 中的 Dart 代码片段视为说明性片段。使用 assets/ 中的代码作为起始代码。
• 不要使用 Platform.isIOS、Platform.isAndroid、设备名称或 OrientationBuilder 来决定布局。请改用可用宽度或约束。
• 不要让大屏幕上的文本字段、卡片、列表或阅读内容无节制地铺满整个窗口；应设置合理的最大宽度或采用多列布局。
• 先确保触控交互完善，再将悬停、快捷键、焦点遍历和键盘激活作为辅助方式添加。
• 对于扩展布局，使用 GridView.extent、自适应弹性布局或受约束的内容宽度；如果局部重排已足够，就不要重复构建整个屏幕。
• Capability 方法应描述可能具备的功能，Policy 方法应描述应展示或允许的内容。方法名称应体现决策，而不是平台。
• 将捆绑资源视为起始示例。只有在目标项目或临时 Flutter 项目中通过 flutter analyze 后，它们才可直接复制使用。

验证

更改 Flutter 项目后：

1. 运行 flutter analyze。
2. 如果更改涉及布局分支、导航状态、焦点或策略／能力行为，请运行相关的 Widget 测试。
3. 手动或自动检查窄屏（<600）、中屏（使用时为 600-839）和扩展屏（>=840）宽度。
4. 确认没有新增溢出条纹、文本裁切、选中状态丢失、滚动位置丢失或键盘遍历失效的问题。
5. 如果无法运行验证，请报告阻碍因素及风险。未检查宽度或未取得分析结果时，不要声称自适应 UI 更改已通过验证。

回退方案

如果目标项目缺少足够的上下文，无法确定最终布局，请先实现最小且可逆的抽象：共享目标／数据模型、局部 LayoutBuilder 分支，以及隔离的 Capability／Policy 接口。只有在无法从应用中推断出产品决策时，才向用户询问，例如每种外形规格下哪些内容应移动、隐藏或设为主要内容。