optimize-filter-toolbar-layout

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. 验证与交付

按项目提供的命令运行：

1. 相关测试或 UI 契约测试。
2. TypeScript 类型检查。
3. ESLint 或项目 Lint。
4. 风险较高时运行生产构建。
5. 可访问本地页面时，用浏览器在常见桌面宽度检查 DOM 边界和截图。

浏览器验证需要登录但没有可用会话时，不修改凭据或认证逻辑。报告该限制，并让用户的人工验收作为补充证据。

最终报告应简洁说明：

• 修改了哪个筛选栏以及采用的布局规则。
• 是否保持原有筛选业务逻辑。
• 测试、类型检查、Lint 和视觉验收结果。
• 仍存在的断点或认证限制；没有则明确说明完成。

完成标准

仅在以下条件全部满足时完成：

• 目标筛选控件在要求的页面宽度下处于同一水平线。
• 工具栏未超过父级页面或卡片最大宽度。
• 搜索框合理占用剩余空间，固定控件宽度一致且间距紧凑。
• 搜索、日期、状态、重置、刷新和批量操作行为未退化。
• 与改动风险匹配的自动化检查通过，或明确记录无法执行的验证及人工验收结果。