agentleFS
LinuxSuRenLinuxSuRen/my-dsh-skills/skills/ui-responsive-list/SKILL.md

ui-responsive-list

Skill2 starsChanged 39 days agoMITView on GitHub

列表页 UI 自适应规范:筛选区「放得下才显示 + 折叠展开多行」、表格/卡片双视图按视口宽度定默认(窄屏卡片、宽屏表格)、移动端韧性红线(320px 不崩:dvh/svh、min() 封顶、容器内滚动、44px 触摸目标)。提炼自多套管理端 Web 列表页改造实战并吸收社区移动韧性实践。

The file

Files
SKILL.md

列表页 UI 自适应(筛选折叠 + 视图默认值)

两条规则 + 一套可复用的实现方式。适用于任何技术栈;示例以 React + Tailwind 落地。

规则 1:筛选区自适应折叠

交互定义:

  • 列表查询项较多时,默认单行只展示完全放得下的筛选控件 + 操作按钮(查询/重置等,常驻行尾、永不折叠)。
  • 放不下的控件自动隐藏,行尾出现「展开」按钮;用户点击后多行展示全部控件,按钮变为「收起」。
  • 全部控件都放得下时与普通单行筛选区无差别(不出现展开按钮),因此对控件少的页面零副作用。
  • 不用横向滚动(overflow-x-auto)兜底——超出可视区的控件等于不存在;也不用固定断点硬编码显隐,以实测容器宽度为准。

实现要点(ResizeObserver 方案):

  • 可见数量 = 用 ResizeObserver 实测容器宽度和每个控件宽度后计算;监听容器与其父级,侧边栏收起、窗口缩放实时生效。
  • 计算逻辑抽成纯函数(输入:各控件宽度、容器宽度、按钮区宽度、间距;输出:可见数量),便于单测,不依赖 DOM。
  • 两遍计算消歧:先假设不需要展开按钮算一遍;若有控件放不下,为展开按钮多预留一位再算一遍。极窄容器下至少保留第一个控件,避免整行只剩按钮。
  • 被隐藏的控件保持挂载:用 position: absolute + visibility: hidden + pointer-events: none 移出可视流,而不是卸载或不渲染——受控值、弹层内部状态、测量宽度都不丢,展开瞬间无状态回退。
  • 展开态切换为 flex-wrap 多行;收起后重新测量。
  • SSR/首帧先全部展示(未测量状态),useLayoutEffect 内测量后再折叠,避免闪变。
  • 组件始终 preventDefault 表单原生提交;查询按钮用 type="submit",回车与按钮共用一条提交路径。
  • 表单级属性(如引导锚点 data-tour)通过 rest props 透传到根 form。

规则 2:表格/卡片视图按视口宽度定默认

交互定义:

  • 列表页同时提供表格、卡片两种展示风格时:窄屏(视口 < 1024px)默认卡片,宽屏默认表格。
  • 用户手动切换过的偏好(localStorage 持久化)优先于视口默认值。
  • 默认值在页面挂载时判定一次即可,不随窗口拖动实时切换,避免打断用户操作。
  • 只有纯表格的页面不强制补卡片视图;为列表新增卡片视图时按页按需添加,遵循同一默认值规则。

实现要点:

  • 读初始视图的函数按「存储偏好 → 视口宽度」顺序决策;SSR 场景首帧固定表格视图,挂载后再同步真实初始值,避免水合不匹配。

移动端韧性红线(320px 不崩)

桌面端好看、手机端翻车是最高频返工源。以下为红线级规则(吸收自社区 doesntbreak 实践,按本库口径改写),适用于所有 Web 页面而非仅列表页:

  • 不出现整页横向滚动条:布局容器不用固定像素宽;需要上限时用 min(100%, Npx) 封顶(max-width 同理),让内容在窄屏自然收缩。
  • 弹性布局优先:flex-wrap 与 grid auto-fit/minmax 让内容自动换行与塌缩,替代手写断点显隐;所有网格在窄屏塌缩为单列是默认行为而非补丁。
  • 视口单位用 dvh/svh 替代 100vh(移动端地址栏伸缩导致 100vh 溢出出滚动条);100vw 慎用(含滚动条宽度)。
  • 宽表格在自身容器内横向滚动(外层 overflow-x: auto 包裹),绝不让整页跟着横滚。
  • 触摸目标 ≥ 44×44px(含图标按钮、分页器、展开/收起按钮);输入框 font-size ≥ 16px 防 iOS 聚焦自动缩放。
  • 侧栏在窄屏变抽屉/底部弹层,操作按钮沉底;隐藏不是删除——入口必须仍有可达路径。
  • 交付前在真实失败宽度上检查:320 / 375 / 768px(DevTools 设备模拟即可),不是只看自己手机。

落地清单(新列表页接入步骤)

  1. 筛选区优先复用项目内已有的响应式筛选栏组件(如有);没有则按本技能规则实现,控件尺寸遵循紧凑规范(h-8、text-xs、px-2、shrink-0;按钮 size="sm")。
  2. 查询/重置等按钮通过组件的 actions 属性传入,不放筛选控件流里。
  3. 有表格/卡片双视图的页面:初始视图函数实现「存储偏好优先、否则按 1024px 断点」,手动切换时写回 localStorage。
  4. 源文本断言类的回归测试若锚定了旧类名/旧标记(如 overflow-x-auto、旧常量名),随实现切换一并更新断言目标。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.