# 前端用户体验规则 ## 你可能搞错了什么 **“按钮可以工作。”** 工作不是标准。交易期间会禁用吗？它显示一个旋转器吗？在链确认之前它会保持禁用状态吗？如果用户拒绝，是否会显示错误？人工智能代理每次都会跳过所有这些。 **“我使用了瓦格米钩子。”** 错误的钩子。 Scaffold-ETH 2 用 `useTransactor` 包装 wagmi，它**等待交易确认**——而不仅仅是钱包签名。 Raw wagmi 的“writeContractAsync”会在用户在 MetaMask 中单击“确认”时解析，然后再挖掘 tx。当交易仍待处理时，您的按钮会重新启用。 **“我显示了地址。”** 作为原始十六进制？那不是显示它。 `

` 为您提供 ENS 分辨率、区块头像、复制到剪贴板和区块浏览器链接。原始“0x1234...5678”是不可接受的。 ** ** ## 规则 1：每个链上按钮 — 加载器 + 禁用 > ⚠️ **这是 AI 代理的 #1 BUG。** 用户单击“批准”，登录钱包，返回应用程序，然后可以再次单击“批准”按钮 - 因此他们再次单击它，发送重复的交易，现在有两个批准正在等待。 **该按钮必须被禁用，并从点击那一刻起直到交易在链上确认为止显示一个旋转图标。**直到钱包关闭为止。直到签名发送为止。直到区块确认。任何触发区块链交易的按钮都必须： 1. **点击后立即禁用** 2. **显示旋转器**（“批准...”、“质押...”等） 3. **保持禁用状态**，直到状态更新确认操作已完成 4. **完成后显示成功/错误反馈** // ✅ 正确：每个操作单独加载状态 const [isApproving, setIsApproving] = useState(false); const [isStake, setIsStake] = useState(false); <按钮已禁用={正在批准} onClick={async()=>{ setIsApproving(true); 尝试{ 等待 writeContractAsync({ functionName: "approve", args: [...] }); } 捕获 (e) { 控制台.错误(e); notification.error("审核失败"); }最后{ setIsApproving(假); } }} > {正在批准？ “批准...”：“批准”} **❌切勿对多个按钮使用单个共享的`isLoading`。**每个按钮都有自己的加载状态。当 UI 有条件地在按钮之间切换时，共享状态会导致出现错误的加载文本。 ### 仅脚手架挂钩 — 绝不生瓦格米 // ❌ 错误：原始 wagmi — 签名后解决，而不是确认 const { writeContractAsync } = useWriteContract(); 等待 writeContractAsync({...}); // MetaMask 签名后立即返回！ // ✅ 正确：脚手架钩子 — 等待 tx 被挖掘 const { writeContractAsync } = useScaffoldWriteContract("MyContract"); 等待 writeContractAsync({...}); // 等待实际的链上确认 **为什么：** `useScaffoldWriteContract` 内部使用 `useTransactor`，等待区块确认。原始 wagmi 不会——当交易仍在内存池中时，您的 UI 将显示“成功”。 ** ** ## 规则 2：四状态流 — 连接 → 网络 → 批准 → 操作当用户需要与应用程序交互时，有四种状态。一次只显示一个大而明显的按钮： 1. 未连接？ → 大“连接钱包”按钮（不是“连接你的钱包来玩”的文字） 2.网络错误？ → 大“切换到基地”按钮 3. 认可度不够？ →“批准”按钮（根据规则 1 使用加载程序） 4. 获得足够的认可？ →“质押”/“存款”/操作按钮 > **永远不要显示“连接您的钱包来玩”或“请连接以继续”之类的文本提示。** 显示按钮。用户应该始终只有一件事可以点击。 const { 数据：津贴 } = useScaffoldReadContract({ 合约名称：“代币”，函数名称：“津贴”， args: [地址, 合约地址], }); const needApproval = !allowance ||津贴<金额； const errorNetwork = chain?.id !== targetChainId; const notConnected = !地址; {未连接？（ // 大连接按钮 — 非文本 ): 网络错误？（ <按钮 onClick={switchNetwork} 禁用={isSwitching}> {正在切换？ “切换...”：“切换到基地”} ): 需要批准吗？（ <按钮 onClick={handleApprove} 禁用={isApproving}> {正在批准？ “批准...”：“批准$TOKEN”} ) : ( <按钮 onClick={handleStake} 禁用={isStake}> {正在质押？ “质押...”：“质押”} )} **关键细节：** * 始终通过挂钩读取津贴，以便在批准交易确认时 UI 自动更新 * 切勿仅依赖当地政府进行津贴追踪 * 首先出现错误的网络检查 - 如果用户在错误的网络上单击“批准”，一切都会崩溃 * **切勿同时显示“批准”和“操作”** — 一次一个按钮 ** ** ## 规则 3：地址显示 — 始终为 `

` **每次显示以太坊地址**时，请使用scaffold-eth的`

`组件：从“~~/components/scaffold-eth”导入{地址}； // ✅ 正确 <地址地址={用户地址}/> // ❌ 错误 — 永远不要渲染原始十六进制 {用户地址}

0x1234...5678

` 处理 ENS 分辨率、块化身、复制到剪贴板、截断和块浏览器链接。原始十六进制是不可接受的。 ### 地址输入 — 始终为 `` **每次用户需要输入以太坊地址**时，请使用 ``：从“~~/components/scaffold-eth”导入{AddressInput}； // ✅ 正确 // ❌ 错误 — 切勿使用原始文本输入作为地址 setRecipient(e.target.value)} /> `` 提供 ENS 解析（类型“vitalik.eth”→解析为地址）、块头像预览、验证和粘贴处理。 **该对：`

` 用于显示，`` 用于输入。总是。** ### 显示您的合约地址 **每个 dApp 都应使用“

”在主页底部显示其部署的合约地址**。用户希望在区块浏览器上验证合约。这可以建立信任，并且是标准做法。

合同：

<地址地址={deployedContractAddress} />

** ** ## 规则 4：美元价值无处不在 **显示的每个代币或 ETH 金额都应包含其美元价值。** **每个代币或 ETH 输入都应显示实时美元预览。** // ✅ 正确 — 以美元显示 1,000 个代币（约 4.20 美元） 0.5 ETH（约 1,250.00 美元） // ✅ 正确 — 输入带有实时美元预览 <输入值={金额} onChange={...} /> ≈ ${(parseFloat(金额 || "0") * tokenPrice).toFixed(2)} USD // ❌ 错误 — 没有美元上下文的金额 1,000 TOKEN // 用户不知道这值多少钱 **从哪里获取价格：** * **ETH 价格：** SE2 内置钩子 — `useNativeCurrencyPrice()` * **自定义代币：** DexScreener API (`https://api.dexscreener.com/latest/dex/tokens/TOKEN_ADDRESS`)、链上 Uniswap 报价器或 Chainlink 预言机 **这适用于显示和输入：** * 显示余额？在旁边显示美元。 * 用户输入要发送/质押/交换的金额？在输入下方显示实时美元预览。 * 交易确认？显示他们将要做的事情的美元价值。 ** ** ## 规则 5：标题不得重复 **请勿将应用程序名称作为“

”放在页面主体的顶部。** SE2 标头已显示应用程序名称。重复它会浪费空间并且看起来很业余。 // ❌ 错误——人工智能代理总是这样做
{/* 已经显示“🦞 我的 dApp” /} <主要>
🦞 我的 dApp
{/ 重复！删除这个。 /}
应用程序说明
... // ✅ 正确 - 直接跳到内容
{/ 显示应用名称 /} <主要>
{/ 统计数据、余额、操作 - 没有多余的标题 */}
## 规则 6：RPC 配置永远不要使用公共 RPC（`mainnet.base.org` 等）——它们会限制速率并导致生产中的随机故障。在 `scaffold.config.ts` 中，始终设置： rpc覆盖：{ [chains.base.id]: process.env.NEXT_PUBLIC_BASE_RPC || “https://mainnet.base.org”， }, pollingInterval: 3000, // 3秒，不是默认的30000 将 API 密钥保留在`.env.local`中——切勿将其硬编码到提交到 Git 的配置文件中。 > ⚠️ SE2 的 `wagmiConfig.tsx` 添加了一个裸露的 `http()` （无 URL）作为后备传输。 Viem 将裸露的 `http()` 解析为链的默认公共 RPC（例如 Base 的 `mainnet.base.org`）。即使在脚手架配置中设置了“rpcOverrides”，公共 RPC 仍然会受到攻击，因为 viem 的“fallback()”会并行触发传输。您必须从“services/web3/wagmiConfig.tsx”中的后备数组中删除裸露的“http()”，以便仅使用您配置的 RPC。如果不这样做，您的应用程序将在每个轮询周期向公共 RPC 发送垃圾邮件，并在生产中获得 429 速率限制。监控 RPC 使用情况：** Sensible = 每 3 秒 1 个请求。如果您看到每秒超过 15 个请求，则说明存在错误： * 钩子在循环中重新渲染 * 重复的钩子调用 * 缺少依赖数组 * `watch: true` 在不需要它的钩子上 ## 规则 7：使用 DaisyUI 语义颜色 — 切勿对深色背景进行硬编码 AI 代理喜欢深色 UI，并且会对它们进行硬编码。这总是错误的： // ❌ 错误 — 硬编码黑色，破坏了整个 DaisyUI 主题系统
为什么这是一个问题： SE2 附带了为浅色和深色主题配置的 DaisyUI（通常通过 `globals.css` 或 `tailwind.config.ts`）。它还在标题中包含一个“”切换开关。当你对深色背景进行硬编码时，你就破坏了这一切： * Light模式用户（macOS/iOS/Windows系统设置）会出现黑页 * 主题切换不执行任何操作 - 页面忽略“数据主题” * `prefers-color-scheme: light` 被默默忽略始终使用 DaisyUI 语义颜色变量： // ✅ 正确 — 响应系统偏好和主题切换
// DaisyUI 语义类 - 在任何地方都使用它们： // bg-base-100（最轻的表面 - 卡、输入） // bg-base-200（默认页面背景） // bg-base-300（边框、分隔线） // 文本基础内容（主要文本） // text-base-content/60（辅助/静音文本）如果你真的想要仅限黑暗，你必须全力以赴——不要半途而废： // ✅ 可接受仅深色 — 但也从标题中删除 // 在 app/layout.tsx 中： // 并从 Header.tsx 中删除 // 不要留下不执行任何操作的主题切换快速扫描错误： grep -rn 'bg-\[#0\|bg-black\|bg-gray-9\|bg-zinc-9\|bg-neutral-9\|bg-slate-9'packages/nextjs/app/ 根页面包装器上的任何匹配 → 修复它。 ## 规则 8：修复 SE2 的药丸状表单输入 SE2 的 DaisyUI 主题设置“--radius-field: 9999rem”——完全药丸形状的输入。单行输入看起来不错，但文本区域、多行输入和选择看起来很糟糕——文本剪辑与极端边框半径相对应。人工智能代理永远不会解决这个问题。他们看到 DaisyUI 类，认为它是正确的，并发送药丸状文本区域。在主题中修复它，而不是在每个元素中修复它。在 `packages/nextjs/styles/globals.css` 中，更改两个主题： /* 在@plugin“daisyui/theme”块中（浅色和深色）：/ --半径场：9999rem； / ❌ 默认 — 药丸形状，剪辑 textarea 文本 / --半径场：0.5rem； / ✅ rounded-lg 等效项 — 适用于所有表单元素 / 就是这样——每个主题一行，每个“input”、“select”和“textarea”都会全局继承它。不要将“rounded-md”添加到单个元素中——这会与主题系统发生冲突，并在主题更改时中断。快速检查： grep“半径字段”packages/nextjs/styles/globals.css 如果显示“9999rem”，请修复它。 ## 规则 9：合约错误翻译当合同恢复时，用户必须看到人类可读的解释。不是十六进制选择器。不是静音按钮重置。不是控制台错误。原则：阅读您合约的 ABI。查找每个自定义错误。将每一项都映射为简单的英语。将其内联显示在触发它的按钮下方。步骤： 1. 从 ABI 中提取所有错误 — 合约的自定义错误和继承错误（OpenZeppelin 等） 2. 编写一个映射函数，它接受捕获的错误并返回面向用户的字符串 3. 包括钱包级别的错误 — 用户被拒绝、gas 不足 4. 添加后备 - 如果无法解析它，仍然显示_something_（“交易失败”） 5. 内联显示 — 按钮下方的持续警报，而不是提示。当用户编辑输入时清除它。 // ❌ 错误 — 用户什么也看不到尝试 { 等待 writeTx(...) } catch (e) { console.error(e) } // ✅ 右 — 用户看到“代币余额不足” 尝试 { 等待 writeTx(...) } catch (e) { setTxError(parseContractError(e)) } // 按钮下方： {tx错误&&(
{txError}
)} 如何查找错误： # 列出合约 ABI 中的所有自定义错误猫部署合同.ts | grep -o '"名称":"[^"]错误[^"]"' |排序-u # 或者来自 Solidity 源 grep -rn '错误' 合同/src/ | grep -v '//' 该列表中的每个错误都需要在前端中有一个人类可读的字符串。如果您继承了 OpenZeppelin，它们的错误（`ERC20InsufficientBalance`、`OwnableUnauthorizedAccount` 等）也在您的 ABI 中 — 不要忘记它们。 ## 规则 10：发布前检查表在将前端部署到生产环境之前，每个项目都必须通过：开放图谱/Twitter 卡（必需）： // 在 app/layout.tsx 或 getMetadata.ts 中导出常量元数据：元数据 = { 标题：“您的应用程序名称”，描述：“应用程序的描述”，打开图：{ 标题：“您的应用程序名称”，描述：“应用程序的描述”，图片: [{ url: "https://YOUR-LIVE-DOMAIN.com/thumbnail.png" }], }, 推特：{ 卡：“summary_large_image”，标题：“您的应用程序名称”，描述：“应用程序的描述”，图片：[“https://YOUR-LIVE-DOMAIN.com/thumbnail.png”]， }, }; ⚠️ OG 图片 URL 必须是：以 `https://` 开头的绝对 URL * 实时生产域（不是“localhost”，不是相对路径） * 不是可以取消设置的环境变量 * 实际可达（通过在浏览器中访问URL进行测试）删除所有 Scaffold-ETH 2 默认身份： * 重写自述文件 — 不是 SE2 模板自述文件 * 清理页脚 — 删除 BuidlGuidl 链接、“Fork me”链接、支持链接、任何 SE2 品牌。替换为您项目的存储库链接 * 更新了 Favicon — 不是 SE2 默认值 * 选项卡标题是您的应用程序名称，而不是“Scaffold-ETH 2” 完整清单： * OG图像URL是绝对的，实时生产域 * OG标题和描述集（不是默认的SE2文本） * Twitter 卡片类型集 (`summary_large_image`) * 删除了所有 SE2 默认品牌（自述文件、页脚、图标、选项卡标题） * 浏览器选项卡标题正确 * RPC 覆盖集（不是公共 RPC） * 从 wagmiConfig.tsx 后备数组中删除了裸露的 `http()`（无静默公共 RPC 后备） * `pollingInterval` 为 3000 * 所有合约地址均与部署的地址匹配 * 生产代码中没有硬编码的 testnet/localhost 值 * 每个地址显示都使用 `
` * 每个地址输入都使用`` * 每个链上按钮都有自己的加载器+禁用状态 * 批准流程有网络检查→批准→动作模式 * 没有重复的 h1 标题匹配标题没有硬编码的深色背景 - 页面使用“bg-base-200 text-base-content”（或深色强制+切换删除） ## externalContracts.ts — 构建之前所有外部合约（代币、协议、您未部署的任何内容）都必须在构建前端之前添加到 `packages/nextjs/contracts/externalContracts.ts` 中，并包含地址和 ABI。 // 包/nextjs/contracts/externalContracts.ts 导出默认值{ 8453: { // 基础链 ID 美元结算公司：{ 地址：“0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913”， abi: [...], // ERC-20 ABI }, }, 作为常量；为什么之前：脚手架挂钩（`useScaffoldReadContract`、`useScaffoldWriteContract`）仅适用于在`deployedContracts.ts`（自动生成）或`externalContracts.ts`（手动）中注册的合约。如果您编写引用未注册合约的前端代码，它会默默地失败。永远不要编辑`deployedContracts.ts` - 它是由`yarn deploy`自动生成的。将您的外部合约放入“externalContracts.ts”中。 ## 人类可读的数量始终在合同单位和显示单位之间进行转换： // 合约 → 显示从“viem”导入 { formatEther, formatUnits }; formatEther(weiAmount); // 18 位小数（ETH、DAI、大多数代币） formatUnits(usdcAmount, 6); // 6 位小数（USDC、USDT） // 显示 → 合约从“viem”导入{parseEther，parseUnits}；解析以太（“1.5”）； // → 1500000000000000000n parseUnits("100", 6); // → 100000000n (USDC) 永远不要向用户显示原始 wei/单位。 `1500000000000000000` 没有任何意义。 “1.5 ETH（约 3,750 美元）”意味着一切。 ## 资源 SE2 文档： * UI 组件： * SpeedRun 以太坊：

前端用户体验

包含技能