Birdor 工具页通用组件规格：输入区、输出区、按钮、错误提示、FAQ 与相关工具

本系列导航

• 上一篇：Birdor JWT Decoder 实现规格
• 下一篇：产品开发落地文档已完成，建议进入 JSON Formatter 和 JWT Decoder 代码实现。
• 返回目录：Birdor 商业计划书目录

本章关键词

工具页组件、输入区、输出区、操作按钮、错误提示、隐私提示、FAQ、相关工具、响应式布局、事件埋点。

适合阅读的人

• 准备实现 Birdor 工具页模板的工程师。
• 需要统一 JSON、JWT、Regex、Log 等工具体验的人。
• 想避免每个工具页重复造组件的人。

本章摘要

Birdor 如果要从几个工具扩展到 100+ 工具，就不能每个页面单独设计输入区、输出区、按钮、错误提示和 FAQ。通用组件规格的目标是让每个工具既保持一致体验，又允许根据任务类型扩展。

本文定义 Birdor 工具页通用组件，包括页面骨架、输入组件、输出组件、操作按钮、错误提示、隐私提示、FAQ、相关工具、指标和响应式布局。JSON Formatter 和 JWT Decoder 应优先使用这套规格，AI Regex 和 AI Log 在此基础上增加 AI 表单、成本提示和结构化报告。

页面骨架

通用工具页结构：

Workbench 是页面核心，必须在首屏可见。Content 是补充，不能干扰任务完成。

ToolHeader

字段：

规则：

• title 直接包含工具词。
• description 说明用户能完成什么。
• privacyNote 必须靠近工具区。
• 不要把营销口号放在首屏核心位置。

ToolInput

输入组件支持：

• textarea。
• code editor。
• key/value form。
• file input。
• structured form。

通用属性：

规则：

• 输入失败不能清空。
• 大输入要提示。
• 敏感工具要前置隐私提示。
• 移动端输入区要有足够高度。

ToolActions

按钮类型：

按钮状态：

• default。
• disabled。
• loading。
• success。
• error。

规则：

• primary action 只能有一个。
• 常用 secondary action 不要藏太深。
• Copy/Download 只有有输出时可用。
• loading 状态必须防止重复提交。
• AI action 要显示成本或额度边界。

ToolOutput

输出类型：

• code block。
• JSON viewer。
• table。
• report。
• split panels。
• claim cards。

通用属性：

规则：

• 输出为空时显示明确空状态。
• 输出要可复制。
• AI 报告要结构化，不展示不可控长文。
• 安全相关输出要显示提示。

ToolError

错误对象：

错误组件规则：

• 说明发生了什么。
• 给出下一步。
• 不暴露内部堆栈。
• 不清空输入。
• 可关联到输入位置时尽量高亮。

错误类型建议统一：

• empty_input。
• invalid_format。
• parse_error。
• too_large。
• unsupported。
• ai_failed。
• quota_exceeded。
• network_error。
• copy_failed。

PrivacyNote

隐私提示分三类：

规则：

• 本地工具要明确“不上传输入”。
• AI 工具要明确“会发送到服务器或模型”。
• 敏感工具要提示不要粘贴生产 secret。
• 隐私提示应靠近输入区，而不是只放 FAQ。

FAQ

FAQ 用于 SEO 和用户教育。每个工具至少包含：

• 这个工具做什么。
• 输入是否会上传。
• 常见错误原因。
• 和相关工具的区别。
• 是否有 API。
• 是否支持 Pro 或批量处理。

FAQ 不应写成泛泛概念。每个问题都要对应真实搜索意图或用户困惑。

RelatedTools

相关工具分三类：

规则：

• 每页 3-6 个高价值相关工具。
• 相关工具要说明下一步用途。
• 不要把所有工具都堆进去。
• 点击事件要记录。

响应式布局

桌面：

• 输入输出可双栏。
• 操作栏靠近输入区。
• 错误提示在输入和输出之间或下方。

移动端：

• 输入输出上下排列。
• 操作按钮可换行。
• 复制和清空按钮不遮挡输入。
• 长输出可滚动。

所有固定格式元素要有稳定尺寸，避免按钮状态、错误文案或动态输出导致布局跳动。

事件规范

通用事件：

• tool_input_start
• tool_primary_action
• tool_success
• tool_error
• tool_copy
• tool_download
• tool_sample
• tool_clear
• tool_related_click
• tool_pro_trigger

事件属性：

• tool_id。
• action。
• success。
• error_type。
• input_size_bucket。
• output_size_bucket。
• user_tier。

禁止记录：

• 原始输入。
• token。
• secret。
• payload 内容。
• AI prompt 原文中包含的敏感数据。

组件复用策略

第一阶段复用：

• JSON Formatter。
• JWT Decoder。
• Base64 Decoder。
• Timestamp Converter。

第二阶段扩展：

• AI Regex Generator。
• AI Log Analyzer。
• AI Config Generator。

AI 工具可以复用 ToolHeader、ToolInput、ToolActions、ToolError、RelatedTools、FAQ，但输出区需要扩展为结构化报告或测试结果。

验收标准

• JSON 和 JWT 能使用同一套基础组件。
• 工具页首屏可完成核心任务。
• 输入失败不清空。
• Copy、Sample、Clear 状态一致。
• 错误提示对象结构统一。
• 隐私提示位置一致。
• 相关工具可配置。
• 通用事件可复用。
• 移动端不出现遮挡和布局跳动。

延伸阅读

• Birdor JSON Formatter 实现规格
• Birdor JWT Decoder 实现规格
• 第三十二章：前端工具页架构
• Birdor 首批工程 Issue
• JSON Formatter PRD
• JWT Decoder PRD