frontend-patterns

前端模式

适用于各种场景的前端最佳实践。请阅读以下所有模式。如果某个模式适用于你即将构建的内容，就请遵循。 对于这里已明确规定的事项，无需征求许可，只需遵循规则，并用一句话说明你已遵循。

何时参考此技能

在以下任何情况下：

• 编写或编辑 TSX/JSX
• 添加执行保存/创建/提交操作的按钮
• 添加任何表单
• 添加任何对话框、模态框、弹出框或工作表
• 设置键盘快捷键
• 审查 UI 更改

如果以下模式都不适用于当前场景，请不作说明，返回原始任务。

模式

• 对于桌面端，Cmd+Enter 应始终表示“提交”——无论是保存、创建、发送、确认还是其他主要操作。Cmd+Enter 的行为应与手动点击主要按钮完全一致（禁用、加载和验证行为相同，副作用也相同）。Windows/Linux 上使用 Ctrl+Enter（e.metaKey || e.ctrlKey）。
• 需要使用对话框时，请改用 ResponsiveDialog：它在桌面端显示 Dialog，在移动端显示 Drawer。这样移动端的用户体验更好，因为移动端的对话框体验不太理想。如果不存在此组件，请使用 shadcn 的 Dialog 和 Drawer 组件创建一个（镜像 shadcn 的 Dialog API，使其可直接替换使用——Content、Header、Title、Description、Footer、Trigger、Close）。
• 防止对话框/模态框/抽屉/侧边面板关闭时丢失未保存的编辑内容。 如果对话框（或类似的可关闭容器）中有可编辑字段，而用户在存在未保存更改时尝试关闭——没有自动保存、未点击 Save/Submit 按钮，或更改尚未以其他方式持久化——请拦截关闭操作并先请求确认（例如：“你有尚未保存的更改。仍要关闭吗？你的进度将会丢失。”）。仅在用户确认后才关闭。此规则适用于所有关闭方式：X/关闭按钮、点击背景/遮罩层、按 Escape，以及移动端抽屉滑动关闭。请跟踪表单是否已修改（比较当前值与初始值，或使用表单库提供的脏状态标记）；如果没有任何更改，则跳过确认，让常见操作保持顺畅。
• 渲染 Markdown 内容（聊天消息、大模型输出、评论、备注，以及任何可能包含 Markdown 的用户/AI 撰写文本）时，绝不能只把字符串用 {text} 或 whitespace-pre-wrap 塞进 <div> 或 <p>。 请使用真正的 Markdown 渲染器。默认使用 react-markdown，搭配 remark-gfm（表格、删除线、任务列表、自动链接）和 remark-breaks（使单个 \n 转换为 <br>——不使用此插件时，单个换行会折叠，输出看起来会像一整堵连成一片的文字，这是 Agent 反复交付的失败模式）。代码块请添加 rehype-highlight 或 react-syntax-highlighter。安装：npm i react-markdown remark-gfm remark-breaks。最简用法：

  import ReactMarkdown from 'react-markdown';
  import remarkGfm from 'remark-gfm';
  import remarkBreaks from 'remark-breaks';
  
  <ReactMarkdown remarkPlugins={[remarkGfm, remarkBreaks]}>{text}</ReactMarkdown>
  

  不要使用 dangerouslySetInnerHTML 搭配手写的正则替换器（.replace(/\n/g, '<br>') 等）——这会造成 XSS 漏洞，还会遗漏其他所有 Markdown 结构。如果项目已统一使用其他渲染器（marked、markdown-it、MDX），则使用该渲染器，但请确认已启用单换行转 <br> 的行为（在 marked/markdown-it 中设置 breaks: true）。
• 优先使用服务端组件。 只有组件确实需要浏览器功能时才添加 'use client'——例如交互状态/副作用（useState、useEffect、refs）、事件处理程序或仅限浏览器使用的 API。尽可能将客户端边界放在组件树的低层：将交互功能放进小型叶子组件，而不是把整个页面/路由标记为 'use client'。
• 使用 Tailwind 工具类和项目现有的设计令牌进行样式设计；避免自定义 CSS。 使用已配置的令牌/主题（颜色、间距、圆角、排版），而不是硬编码值；避免使用一次性的 CSS 文件或内联 style={{…}}，除非确有 Tailwind 无法表达的需求（使用时请用一行说明原因）。
• 将可复用的设计系统基础组件放在 components/ui/* 下。 通用的、适用于整个应用的构建块（按钮、输入框、对话框等）应放在那里；功能专属组件则不应放在那里（请与对应功能放在一起——参见 codebase-conventions 技能）。
• 内容绝不能溢出其容器——任何文本或元素都不应超出、溢出容器边界，或撑宽布局。 这不是可有可无的润色；请将任何溢出视为需要修复的缺陷，而不是报告的问题。常见原因是在固定宽度/弹性布局/网格容器中出现了较长且不间断的字符串——URL、文件路径、令牌、电子邮件、哈希值，或 word-after-word-after-word。应采用以下默认做法：
  • 可换行文本（段落、说明、标签、链接文本，以及任何包含用户/AI 提供字符串或 URL 的内容）：添加 break-words（overflow-wrap: anywhere），让长字符串换行而不是溢出。单独使用 word-break 无法在任意位置断开 URL/路径——请使用 break-words/anywhere。对于 href 文本是原始 URL 的锚点，请换行显示的文本，例如 <a className="break-words">。
  • 不适合换行的单行字段（表格单元格、列表行、标签胶囊、面包屑）：使用 truncate（overflow-hidden text-ellipsis whitespace-nowrap），并通过 title/工具提示展示完整值。
  • 承载文本的 Flex/Grid 子项： 为 Flex/Grid 项添加 min-w-0。否则，项目的最小宽度会等于其内容宽度，导致 truncate/break-words 悄无声息地失效，行内容也会撑出容器——这是“仍然溢出”最常见的原因。
  • 确实较宽的内容（代码块、表格、pre）：为容器添加 overflow-x-auto，使其可滚动，而不是撑宽页面。
  • 在认为工作完成前，务必使用极长且无分隔的字符串（粘贴一个 200 字符的 URL）检查新 UI。构建或编辑任何 UI 后，都要检查是否存在溢出，并主动修复，无需等待别人提出。

此技能适用时的行为方式

1. 确定哪些模式适用于当前工作。
2. 应用这些模式。除非有具体原因表明模式不适用，否则不要提出替代方案。
3. 用一行简短的话告诉用户你应用了哪个模式，以便他们在需要时进行调整。
4. 如果 ResponsiveDialog 不存在且你必须创建它，也要说明这一点。

后续模式

此技能会随着时间不断扩展。应将新模式作为要点添加到上方的 模式 部分，并将其表述为 Agent 可机械执行的规则。