第 13 章提示与错误
这一章统一规定界面上的反馈方式与文案风格。遇到看不懂的提示、弹窗、报错， 来这里对照一下就知道它在说什么。
反馈的四种形态
| 形态 | 用在哪 | 是否打断 |
|---|---|---|
| 状态栏文字 | 进度、结果概要、连接状态 | 否 |
| 轻提示（Toast） | 复制成功、提交成功、导出完成 | 否，几秒后自动消失 |
| 确认弹窗 | 破坏性操作前的确认 | 是 |
| 错误面板 | 需要用户看清原因的错误 | 是 |
一条总原则
能用状态栏和轻提示解决的，不要弹窗。
弹窗会打断你的思路。所以「复制成功」这种不需要决定的事，只用一条飘过的提示就够了。
轻提示的文案
| 场景 | 文案 |
|---|---|
| 提交成功 | 已提交 7 处修改 · 128 ms |
| 复制成功 | 已复制 12,480 行（2.1 MB） |
| 导出完成 | 导出完成：129,480 行 → articles.csv + 「在 Finder 中显示」按钮 |
| 导入完成 | 导入完成：成功 12,480 行，失败 0 行 |
| 已断开 | 连接已断开 |
| 重连成功 | 已重新连接 |
| 只读拦截（单条） | 只读模式：已跳过 1 条写操作语句 |
确认弹窗
只在不可撤销或可能丢数据的操作前出现。
| 场景 | 有确认吗 | 确认方式 |
|---|---|---|
| 删除连接 | 是 | 普通确认按钮 |
| 关闭有未提交改动的标签 | 是 | 三选一：提交 / 放弃并关闭 / 取消 |
| 放弃多于 5 条改动 | 是 | 普通确认 |
| 截断表 | 是 | 手动输入表名 |
| 删除表 | 是 | 手动输入表名 |
| 覆盖已存在的导出文件 | 是 | 普通确认 |
| 关闭只读模式 | 是 | 普通确认 |
| 清空查询历史 / Console Log | 是 | 普通确认 |
按钮措辞必须具体
确认弹窗的按钮不要用「确定 / 取消」，要用能说明后果的词：
应该这样： [ 取消 ] [ 放弃修改 ] [ 提交并继续 ]
不要这样： [ 取消 ] [ 确定 ]
「确定」什么？用户在这个位置需要停顿半秒想一下，而这一停往往就能避免一次误操作。
错误面板
四条必须遵守的规则
- 服务器返回的错误原文不翻译、不改写、不截断。 翻译过的错误信息会让你没法拿去搜索。所以哪怕是英文原文，也原样贴出来。
-
错误码与 SQLSTATE 必须显示。格式统一为
[错误 1062] SQLSTATE 23000。 -
必须说明数据现在是什么状态。这是最容易被忽略、也最重要的一条。例如：
事务已回滚，你的修改都还在暂存区里，尚未生效。提交超时，事务状态未知，请在数据库中手动核对这几行的数据。导出中断，文件不完整。
-
能给出下一步动作就提供按钮：
重试、重新连接、查看详细输出。
常见错误的附加说明
| 错误码 | 含义 | 面板里额外加的一句 |
|---|---|---|
1045 | 认证失败 | 请检查用户名与密码。 |
1049 | 数据库不存在 | 请检查连接配置里的数据库名，或留空。 |
1130 | 主机不允许 | 该账号不允许从当前 IP 连接，请检查数据库的访问白名单。 |
1062 | 唯一键冲突 | 有一行的值与已有数据重复。 |
1064 | 语法错误 | 请检查这条语句。 |
1205 | 锁等待超时 | 有其他事务长时间持有锁，稍后重试。 |
1213 | 死锁 | 事务已被回滚，请重试。 |
2006 / 2013 | 连接丢失 | 连接已断开，正在尝试重新连接。 |
| SSH 认证失败 | — | 请检查 SSH 用户、密钥或密码。 |
加载与空状态
| 场景 | 表现 |
|---|---|
| 首次读取数据 | 网格区域显示骨架占位（不是转圈图标）——骨架能预示内容的形状 |
| 翻页 / 排序 / 过滤 | 保留旧数据并叠加半透明加载遮罩，避免闪烁 |
| 网络慢（超过 1 秒） | 状态栏显示耗时 |
| 超过 10 秒 | 状态栏文字附带「取消」按钮 |
| 空结果 | 明确区分「没有数据」和「查询成功但没返回行」 |
危险状态的视觉提示
| 状态 | 表现 |
|---|---|
| 有未提交改动 | 状态栏橙色条 + 标签标题的橙点 + 提交按钮上的角标数字 |
| 只读连接 | 锁图标 + 连接颜色带 + 状态栏 · 只读 |
| 连接异常 | 红点 + 内容区灰色遮罩 + 「重新连接」按钮 |
| 结构视图可能过期 | 顶部黄色提示条 + 「刷新」按钮 |
文案规范
语气
- 用主动语态、陈述事实
- 不用「您」
- 不用感叹号
- 按钮文案 2–4 个字
- 文件名、路径、SQL 用等宽字体
- 数字与单位之间加空格：
12.3 KB、128 ms、300 行 - 时间用
HH:mm:ss；跨天显示昨天 18:02
术语统一
| 统一用 | 不要用 |
|---|---|
| 数据库 / 库 | schema |
| 标签 | Tab / 页签 |
| 表数据视图 | 数据浏览器 / Grid |
| 变更暂存 / 未提交的修改 | pending change |
| 提交 | 保存 / Commit |
| 放弃 | 撤销 / Discard |
| 快速查看 | Quick Look |
| 连接 | 数据源 / 会话 |
界面语言
界面是中文的，但 SQL 关键字与协议术语保持英文——
SELECT 不翻译成「查询」，SQLSTATE 不翻译成「SQL 状态」。
这些词你在文档、报错、聊天里看到的都是英文，翻译了反而对不上。