| name | optimize-filter-toolbar-layout |
| description | 将 React、Next.js、Ant Design 或 Tailwind 管理后台中松散、纵向堆叠、自动换行或超出内容区的筛选组件，重构为页面最大宽度内的单行水平筛选栏。用于用户要求“筛选框排成一行”“仿照其他管理页面的筛选栏”“压缩筛选区间距”“不要超过页面宽度”或统一同项目列表页工具栏布局时；同时保留原有筛选、重置、刷新、批量操作等业务行为并完成回归验证。 |
单行筛选栏布局优化
把现有项目中表现松散或会换行的筛选区，改造成与同项目优秀页面一致的紧凑单行工具栏。优先复用项目已有模式，避免引入新的布局体系或改动无关业务。
工作流程
1. 明确范围与验收条件
从用户描述、页面截图和目标路由提取以下信息：
- 需要调整的筛选区，不要误改独立的前置选择区、表格或表单。
- 需要保留的控件顺序、状态、事件和禁用逻辑。
- 参考页面及其视觉特征。
- 验收条件：所有筛选控件同一水平线、整体不超过页面或卡片内容宽度、间距紧凑、功能不退化。
需求已经明确时直接实施；仅当控件归属或目标断点会实质改变方案时再询问。
2. 定位目标与参考实现
使用 rg 搜索页面文案、占位符、按钮文字或路由，定位目标组件。再搜索用户指定的参考页面，比较：
- 容器使用 Grid 还是 Flex。
- 搜索框是否吸收剩余宽度。
- 日期、下拉框和按钮的列宽。
gap、min-width、width: 100% 和换行规则。- 页面外层的
max-width、内边距和卡片内容宽度。
优先复用同项目参考页面的列定义和类名。目标组件若使用 flex-wrap，通常就是宽度充足时松散、宽度变小时折行的直接原因。
3. 选择布局策略
管理后台桌面筛选栏优先使用 CSS Grid：
<div
className="grid w-full min-w-0 items-end gap-2"
style={{
gridTemplateColumns:
"minmax(0, 1fr) 128px 128px 112px auto auto auto",
}}
>
{}
</div>
遵循以下规则：
- 将文本搜索框放在
minmax(0, 1fr) 弹性列中，吸收剩余空间并允许安全收缩。
- 为日期和下拉框使用与参考页面一致的固定列宽，常用范围为
112px 到 160px。
- 为按钮使用
auto 列，必要时添加 shrink-0 和紧凑水平内边距。
- 为搜索控件添加
w-full min-w-0，避免子元素的固有宽度撑破 Grid。
- 使用
w-full min-w-0 让工具栏受父级内容区约束。
- 移除目标筛选容器上的
flex-wrap；不要仅通过缩小所有控件来掩盖换行问题。
- 控件顺序优先与同项目参考页一致，例如：搜索、开始日期、结束日期、状态、重置、刷新、主操作。
如果项目明确支持窄屏，不要让“永不换行”和“无横向溢出”互相矛盾。先确认产品断点；桌面端保持单行，移动端应使用项目已有响应式策略或经过用户确认的横向滚动方案。
4. 实施最小改动
只修改布局所需的容器、列顺序和宽度类：
- 保留筛选状态、请求参数、事件回调、加载态和禁用态。
- 保留重置时对受控输入值的清理，确保界面值与请求状态一致。
- 不把独立卡片或选择器强行并入工具栏。
- 不顺手重构表格、接口或无关样式。
- 使用项目现有格式和组件库能力，不新增依赖。
工作区已有其他改动时，只编辑当前任务文件，并在提交前检查差异范围。
5. 添加回归保护
项目已有源码契约测试时，添加最小布局断言，例如：
assert.match(source, /grid w-full min-w-0 items-end gap-2/);
assert.match(source, /minmax\(0, 1fr\)/);
assert.doesNotMatch(source, /flex flex-wrap items-end/);
若项目使用组件测试或端到端测试，优先断言真实几何关系：
- 所有控件的
getBoundingClientRect().top 相同或在允许误差内。
- 工具栏
scrollWidth <= clientWidth。
- 最右侧控件的
right 不超过父内容区的 right。
- 页面没有因本次改动新增水平滚动条。
不要为了测试而复制组件实现；测试应约束关键布局意图。
6. 验证与交付
按项目提供的命令运行：
- 相关测试或 UI 契约测试。
- TypeScript 类型检查。
- ESLint 或项目 Lint。
- 风险较高时运行生产构建。
- 可访问本地页面时，用浏览器在常见桌面宽度检查 DOM 边界和截图。
浏览器验证需要登录但没有可用会话时，不修改凭据或认证逻辑。报告该限制，并让用户的人工验收作为补充证据。
最终报告应简洁说明：
- 修改了哪个筛选栏以及采用的布局规则。
- 是否保持原有筛选业务逻辑。
- 测试、类型检查、Lint 和视觉验收结果。
- 仍存在的断点或认证限制；没有则明确说明完成。
完成标准
仅在以下条件全部满足时完成：
- 目标筛选控件在要求的页面宽度下处于同一水平线。
- 工具栏未超过父级页面或卡片最大宽度。
- 搜索框合理占用剩余空间，固定控件宽度一致且间距紧凑。
- 搜索、日期、状态、重置、刷新和批量操作行为未退化。
- 与改动风险匹配的自动化检查通过，或明确记录无法执行的验证及人工验收结果。
